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

TELNewWithResult

Creates a new telephone record and returns a handle to the newly created record or generates a specified error message.

pascal TELHandle TELNewWithResult (
                     short procID,
                     TELFLags flags,
                     long refCon,
                     long userData,
                     TELErr *error);

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.

error

On exit, a result code that indicates the status of the attempt to create a new record.

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), TELNewWithResult returns nil.

DESCRIPTION

The TELNewWithResult 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 TELNewWithResult 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. TELNewWithResult 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

The TELNewWithResult function is identical to the older TELNew function, except that it returns information about errors that may occur during the process of creating a new telephone record.

Not all versions of the Telephone Manager support the TELNewWithResult function. You should use the Gestalt function to verify that TELNewWithResult is available before calling it.

SEE ALSO

See Listing 1-4 on page 1-17 for a code sample that illustrates how to call the Gestalt function to verify that TELNewWithResult is available.