Inside Macintosh: Telephony /

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

Telephone Manager Initialization Functions / Configuring a Telephone Tool with the Standard Interface

TELChoose

Displays a dialog box in which a user can specify the settings for a given telephone tool.

pascal TELErr TELChoose (
                     TELHandle *hTEL,
                     Point where,
                     TelephoneChooseIDleUPP idleProc);

hTEL

On entry, a handle to a telephone record specifying the initial tool and settings of the tool-selection dialog box. On exit, a handle to a telephone record specifying the tool and settings selected by the user, or nil if a significant error occurred during the execution of TELChoose.

where

The point, specified in global coordinates, where the upper-left corner of the tool settings dialog box should be positioned. You should place the dialog box as close as possible to the upper-left corner of the screen because the size of the tool-settings dialog box can vary depending on the telephone tool.

idleProc

A function, with no parameters, that the Telephone Manager calls each time TELChoose loops through the setup dialog box filter procedure. Pass nil in this parameter if your application has no idle procedure. For details on how to implement an idleProc procedure, consult Inside the Macintosh Communications Toolbox.

function result

A result code. The result codes telChooseCancel, telChooseAborted, telChooseDisaster and telChooseFailed indicate that the configuration process was not completed for some reason. The result codes telChooseOKMinor and telChooseMajor indicate that the configuration process succeeded. For information about these result codes, see "Tool Choosing Result Codes" on page 1-24.

DESCRIPTION

The TELChoose function displays a standard tool-settings dialog box that lets users select a telephone tool and the desired configuration settings. On entry, hTEL is a handle to a telephone record that specifies the initial settings of the dialog box. TELChoose returns, in the hTEL parameter, a handle to a telephone record whose fields are set according to the user's selections. If a significant error occurs during the configuration process, the hTEL parameter is set to nil.

If the user selects a new telephone tool and specifies the configuration settings, TELChoose automatically creates a new telephone record for the telephone terminal and returns a handle to that record in the hTEL parameter. TELChoose also fills in the configuration details with the settings specified by the user and the default configuration values returned through the TELDefault function. TELChoose then calls the TELValidate function to ensure that all of the configuration settings are valid for the selected telephone tool.

Each telephone record contains the configuration settings for a single telephone terminal (for example, the GeoPort Telecom Adapter or ISDN interface). If your application supports more than one telephone terminal, you must provide a mechanism for configuring each one.

SPECIAL CONSIDERATIONS

TELChoose calls TELNew to create a new telephone record. If a new telephone record cannot be created, TELChoose returns a non-zero result code. You can call TELGetTelNewErr to determine the result code from that call to TELNew.