Inside Macintosh: Telephony /

Chapter 4 - Call Appearances / Call Appearance Reference

Call Appearance Functions / Getting Information About Call Appearances

TELCALookup

Provides a handle to a call appearance structure associated with a directory number.

pascal TELErr TELCALookup (
                     TELDNHandle hTELDN, 
                     short internalExternal, 
                     short index, 
                     TELCAHandle *hTELCA);

hTELDN

A handle to a directory-number structure. You provide the handle.

internalExternal

A constant that specifies where a call appearance originates relative to the local switch or closed user group. The function counts only call appearances that meet the specification you provide here to arrive at the call appearance indicated by the index parameter. You can use one of the constants described in "Call Origination Types" (page 4-13).

index

The index of the call appearance whose call appearance structure handle you want to get. Valid index values start at 1.

hTELCA

On exit, a handle to the call appearance structure for the call appearance you requested. The function returns the handle.

function result

A result code.

DESCRIPTION

The TELCALookup function returns, in the hTELCA parameter, a handle to the call appearance structure for the call appearance having the index specified by the index parameter in the list of call appearances associated with the directory number specified by the hTELDN parameter. As a rule, your application need not call the TELCALookup function to obtain a handle to a call appearance. When your application places a call, it gets a handle from the TELSetupCall function (page 4-24). If the user manually initiates a call or if another application calls TELSetupCall, you get a handle to the new call appearance structure from an telCAOutgoingMsg message. For an incoming call, you get a handle from a telCAOfferMsg message or a telCAAlertingMsg message.

However, when your application starts, one or more call appearances may already be in use. The TELCALookup function lets you obtain handles for those call appearances. First call the TELCountCAs function (page 4-57) to get the number of non-idle call appearances on a given directory number. If any exist, use the same directory number and the same value in the internalExternal parameter and call TELCALookup repeatedly to get a handle to the call appearance structure for each call appearance. The range of valid values for the index parameter starts at 1 and goes up to the number returned by TELCountCAs when you specified the same call origination type.