Inside Macintosh: Telephony /

Chapter 1 - Introduction to Telephony on the Macintosh / Telephone Manager Initialization Reference

Telephone Manager Initialization Functions / Creating, Initializing, and Validating a Telephone Record

TELNew

Creates a new telephone record and returns a handle to it.

pascal TELHandle TELNew (
                     short procID,
                     TELFLags flags,
                     long refCon,
                     long userData);

procID

The tool ID that is dynamically assigned to a telephone tool by the Telephone Manager. You acquire a tool ID for each telephone tool by using the TELGetProcID function.

flags

A set of telephone record flags. See "Telephone Record Flags" on page 1-22 for a description of the constants you can use to set this parameter. Not all telephone terminals support these features.

refCon

Reserved for use by your application.

userData

Reserved for use by your application.

function result

A handle to a telephone record. You can use this handle with other Telephone Manager functions to address the new telephone record. If an error occurs that prevents a new telephone record from being created (such as insufficient memory), TELNew returns nil. You can determine which error has occurred by calling the TELGetTelNewErr function.

DESCRIPTION

The TELNew function returns, as its function result, a handle to a telephone record based on the parameters passed to it by the telephone tool specified by the procID parameter. The TELNew function then calls the TELDefault function twice to determine how the telephone tool is configured and places this information in the config and oldConfig fields of the new record. TELNew is called automatically each time a new telephone tool is selected and configured, as described in "Configuring a Telephone Tool with the Standard Interface" on page 1-37.

After all the relevant fields are filled in, the Telephone Manager loads the main code resource associated with the telephone tool, moves it high in the current heap, and locks it in a reserved area of memory. If everything is successful, the Telephone Manager returns a handle that is subsequently used to address the new record.

SPECIAL CONSIDERATIONS

In general, you should use the TELNewWithResult function to create a new telephone record. The TELNewWithResult function returns additional information about any errors that occur in the process of creating a new record. Or, you can use the TELGetTelNewErr function to determine whether any errors occurred during a call to TELNew.