Inside Macintosh: Telephony /

Chapter 4 - Call Appearances / Call Appearance Reference

Call Appearance Functions / Placing an Outgoing Call

TELSetupCall

Creates a call appearance structure for an outgoing call.

pascal TELErr TELSetupCall (
                     TELDNHandle hTELDN, 
                     TELCAHandle *hTELCA, 
                     ConstStr255Param destDN, 
                     ConstStr255Param destName, 
                     ConstStr255Param destSubaddress, 
                     ConstStr255Param userUserInfo, 
                     short bearerType, 
                     short rate);

hTELDN

A handle to a directory number structure. You obtain a handle to a directory number structure from the TELDNLookupByIndex or TELDNLookupByName function.

hTELCA

On exit, a handle to a call appearance structure for the call being set up. The function allocates the structure and returns the handle. You are responsible for disposing of the handle (by calling the TELCADispose function (page 4-52)). The call appearance structure is described in the section "Call Appearance Structure" (page 4-19).

destDN

A pointer to a Pascal-style string containing the destination phone number or network address. If you completely specify the destination number here, you can place the call by calling the TELConnect function (page 4-27). If you set this parameter to nil or provide only a partial number, you place the call by calling the TELDialDigits function (page 4-28) and providing the remaining portion of the destination number. A partial number is any portion of a complete number, starting with the first digit and keeping any other digits in the partial number in sequence. The Telephone Manager requires only that the digits be provided in proper sequence; how the number is partitioned is irrelevant. If you set this parameter to nil, you can place a call to an implicit destination by calling the TELVoiceMailAccess (page 4-48), TELPaging (page 4-48), or TELIntercom (page 4-49) function.

destName

A pointer to a Pascal-style string containing the name of the party associated with the destination phone number. This is an optional parameter; if you don't have the remote party name, set the pointer to nil.

destSubaddress

A pointer to a Pascal-style string containing a subaddress, as defined by the ISDN S-Bus specification. You should set this parameter if the telephone network supports subaddressing. To find out, call the TELGetInfo function and check the bit hasSubaddress in the telephone structure.

userUserInfo

A pointer to a Pascal-style string containing user-to-user information, as defined by certain telephone networks. You should set this parameter if the network supports user-to-user information. To find out, call the function TELGetInfo and check the bit hasUserUserInfo in the telephone structure.

bearerType

Reserved. Set to 0.

rate

Reserved. Set to 0.

function result

A result code.

DESCRIPTION

The TELSetupCall function creates a new call appearance structure for application-initiated calls and returns a handle to that structure in the hTELCA parameter. Your application needs a call appearance structure before it can place and manipulate an outgoing call.

If TELSetupCall completes successfully, the starting state of the newly created call appearance is telCAIdleState. Note, however, that your call appearance message handler does not get a telCAIdleMsg message at this time.

Note

If a user manually initiates a call, your call appearance message handler gets a telCAOutgoingMsg message that contains a handle to the new call appearance structure. You also get a telCAOutgoingMsg message containing a new handle if another Telephone Manager client initiates a call. The Telephone Manager sends an identical message to all registered message handlers that want to receive a given type of call appearance message.

SPECIAL CONSIDERATIONS

The Telephone Manager preallocates a fixed number of call appearance structures. If your application does not dispose of call appearance structures it no longer needs (by calling TELCADispose), you risk running out of them.

SEE ALSO

See "Placing an Outgoing Call" (page 4-24) for a list of the functions you can use to place a call once you obtain a new call appearance structure.