Call Appearance Messages (IM: Telephony)

Chapter 5 - Telephone Manager Messages / Telephone Manager Message Reference

Call Appearance Messages
The following bit masks specify the messages that the Telephone Manager passes to your application for a given call appearance activity. You also use these constants when you call TELCAMsgHand to specify which messages you want your message handler to receive.
When your call appearance message handler receives a message, the hTELCA parameter is a handle to the call appearance structure for the call appearance that originated the message. The msg parameter is one of the following constants. The globals parameter is the value you specified when you called the TELDNMsgHand function to register the message handling routine. The other parameters vary in meaning according to the message type.
enum {
   telCAAlertingMsg        = 0x00000001,
   telCAOfferMsg           = 0x00000002,
   telCAProgressMsg        = 0x00000004,
   telCAOutgoingMsg        = 0x00000008,
   telCADisconnectMsg      = 0x00000010,
   telCAActiveMsg          = 0x00000020,
   telCAConferenceMsg      = 0x00000040,
   telCATransferMsg        = 0x00000080,
   telCAHoldMsg            = 0x00000100,
   telCADigitsMsg          = 0x00000200,
   telCACallParkMsg        = 0x00000400,
   telCACallbackMsg        = 0x00000800,
   telCARejectMsg          = 0x00001000,
   telCADeflectMsg         = 0x00002000,
   telCAForwardMsg         = 0x00004000,
   telCAConferenceSplitMsg = 0x00008000,
   telCAConferenceDropMsg  = 0x00010000,
   telCAQueuedMsg          = 0x00020000,
   telCAInUseMsg           = 0x00040000,
   telCACallPickupMsg      = 0x00080000,
   telCAPagingMsg          = 0x00100000,
   telCAIntercomMsg        = 0x00200000,
   telCAModemToneMsg       = 0x00400000,
   telCAFaxToneMsg         = 0x00800000,
   telCAIdleMsg            = 0x01000000,
   telCASuccessiveAlertMsg = 0x02000000,
   telCAUserUserInfoMsg    = 0x04000000,
   telCAHandOffMsg         = 0x08000000,
   telCAVoiceDetectedMsg   = 0x10000000,
   telCASilenceDetectedMsg = 0x20000000,
   telCADigitsImmMsg       = 0x40000000,
   telCAOtherMsg           = 0x80000000,
   telAllCAMsgs            = 0x7fffffff
};
Constant descriptions

telCAAlertingMsg
Your application receives this message when an incoming call is alerting (that is, ringing) at a telephone terminal. In response, you can call the TELAnswerCall function to answer the call. The mtype parameter is not used and is set to 0. The value parameter is a constant that indicates the alerting pattern of the incoming call. The possible values for this constant are described in "Alerting Patterns" on page 2-15. The msgInfo parameter is not used and is set to 0.
telCAOfferMsg
Your application receives this message when an incoming call is being offered to the local terminal. You can call the TELAcceptCall function to accept the call. At that point, the call enters the telCAAlertingState state and your call appearance message handler gets the telCAAlertingMsg message. You can then call TELAnswerCall function to answer the call. Alternatively, you can call TELRejectCall to reject the offered call. The mtype, value, and msgInfo parameters are not used and are set to 0.
telCAProgressMsg
Your application receives this message when there is a change in the status of an outgoing call appearance. If the progressHasDuration bit in the otherFeatures field of the call appearance record is set, then the mType parameter may contain a duration value, expressed in milliseconds. If the duration value is unknown, if it is not meaningful with a given call progress signal, or if the progressHasDuration bit is not set, mType contains 0. The value parameter is a constant that indicates the current state of the outgoing call appearance. See "Call Progress Signals" on page 5-30 for a description of the constants that can be passed in this parameter. If the value parameter contains the constant telCAPUpdate, the Telephone Manager updates the rmtDN, rmtPartyName, and rmtSubaddress fields in the call appearance structure referenced by the hTELCA parameter. If the value parameter contains the constant telCAPRouted, the Telephone Manager updates the routeDN, routePartyName, and routeSubaddress fields in the call appearance structure referenced by the hTELCA parameter. The msgInfo parameter contains a pointer to a call appearance generic message structure (page 5-44). If the value parameter contains telCAPUpdate, the information in the structure applies to the updated remote directory number, if this information is available. If value contains telCAPRouted, the information applies to the directory number to which the call was routed. Otherwise, the structure is 0-filled.
telCAOutgoingMsg
Your application receives this message when an outgoing call appearance has been initiated (perhaps in response to your calling TELConnect or TELDialDigits). The mtype parameter is not used and is set to 0. The value parameter is a constant that indicates whether the call was initiated manually or programmatically. The possible values for this constant are described in "Outgoing Origination States" on page 5-41. If the value parameter is telPhysical, the call appearance structure specified by the hTELCA parameter is a new structure just allocated by the Telephone Manager. If value is telProgrammatic and your application initiated the telephone call, the handle is identical to the handle returned by the TELSetupCall function. (If your application does not recognize the handle, another application initiated the call). Your application can find out the destination number and name by inspecting the structure specified by the hTELCA parameter. The msgInfo parameter is not used and is set to 0.
telCADisconnectMsg
Your application receives this message when a call has been disconnected. In response, you should dispose of the call appearance structure specified by the hTELCA parameter. The mtype parameter is a constant that indicates whether the local party or the remote party terminated the connection. The constants are described in "Disconnect Location Messages" (page 5-37). The value parameter is a constant that indicates the reason for the disconnect. The possible values for this constant are described in "Disconnect Types" on page 5-37. The msgInfo parameter is not used and is set to 0.
telCAActiveMsg
Your application receives this message when a call appearance has been successfully connected to the destination and conversation or data is free to flow over the connection. The mtype, value, and msgInfo parameters are not used and are set to 0. Note that a telephone tool might automatically send a telCAActiveMsg message after the TELConnect or TELDialDigits function completes successfully, without knowing if a connection is actually established.
telCAConferenceMsg
Your application receives this message when (1) you call the TELConferencePrep function to establish a connection with a party to be added to a conference; (2) you call the TELConferenceEstablish function to add a new party to a conference; or (3) the user manually sets up a conference. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the success or failure of an attempt to prepare for and establish a conference. See "Conference Activity States" on page 5-34 for the constants you can receive in this parameter. The msgInfo parameter is a pointer to a call appearance conference message structure (page 5-44). If the value parameter contains telConferenceEst or telConferenceEstFailed, the structure's relatedCA field contains a handle to the call appearance structure of the conference initiator. Otherwise, the relatedCA field contains nil.
telCATransferMsg
Your application receives this message when (1) you call the TELTransferPrep, TELTransferEstablish, or TELTransferBlind function to transfer a call; (2) a user manually transfers a call; or (3) a call originated by your application is transferred by the remote end. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the outcome of the transfer activity. See "Transfer Constants" on page 5-43 for the constants you can receive in this parameter. The msgInfo parameter is a pointer to a call appearance transfer message structure (page 5-45). If the value parameter contains telTransferEst or telTransferFailed, the structure's prepCA field contains a handle to the prepared call appearance structure and the rmtDN, rmtName, and rmtSubaddress fields specify the directory number, user, and subaddress to which the call is to be or has been transferred. Otherwise, the fields of the message structure are set to 0.
telCAHoldMsg
Your application receives this message when (1) you call the TELHold or TELRetrieve function to hold or retrieve a call appearance, or (2) a user manually puts a call on hold or retrieves a held call. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the outcome of the hold activity. See "Hold States" on page 5-39 for the constants you can receive in this parameter. The msgInfo parameter is unused and is set to 0.
telCADigitsMsg
Your application receives this message when a key is pressed at a remote directory number. (Key presses on a local terminal are handled by your terminal message handler.) The mtype parameter is a constant that indicates whether or not the key press generated an audible tone. These constants are described in "Audible Digit States" (page 5-33). The value parameter is the ASCII character for the keypad digit (0-9, #, *) pressed by the remote party. The msgInfo parameter is unused and is set to 0. Note that both telCADigitsMsg and telCADigitsImmMsg messages are sent for each remote keypress; your application must make sure to respond to only one of each pair of messages. The Telephone Manager immediately calls your message handler with the telCADigitsImmMsg message, whereas it queues the telCADigitsMsg message to be sent at system-task time. See page 5-25 for further information about telCADigitsImmMsg.
telCACallParkMsg
Your application receives this message when (1) you call the TELParkCall or TELRetrieveParkedCall function to park a call or retrieve a parked call, or (2) a user manually parks or retrieves a call. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the outcome of call parking activity. The constants are listed in "Call Parking States" (page 5-42). The msgInfo parameter is a pointer to a call appearance generic message structure (page 5-44) that specifies the remote directory number at which the call is available for retrieving. If the telephone network switch doesn't support parking calls against directory numbers, all fields of that structure contain 0.
telCACallbackMsg
Your application receives this message when there is callback activity for a call appearance--that is when (1) your application calls the TELCallbackSet function in response to either a busy signal or no answer at the destination number (the value parameter contains telCallbackEst or telCallbackFailed); (2) a previously busy destination number becomes available (the value parameter contains telCallbackNowAvail); (3) your application calls the TELCallbackClear function to clear a callback request, regardless of whether the request originated at the local terminal or a remote terminal (the value parameter contains telCallbackCleared); (4) a remote application calls the TELCallbackSet function because a local directory number did not answer (the value parameter contains telCallbackDesired); (5) a remote application calls the TELCallbackClear function to clear a callback desired request, regardless of whether the request originated at the local terminal or a remote terminal (the value parameter contains telCallbackDesiredCleared); or (6) a local or a remote user manually sets or clears a callback request. The value parameter contains a constant that indicates the type of callback activity. The constants are described in "Callback Activity Types" (page 5-33). If the value parameter contains telCallbackNowAvail, the hTELCA parameter is unused and is set to 0. If the value parameter contains telCallbackNowAvail, telCallbackDesired or telCallbackDesiredCleared, and if a callback reference value is used by the switch, then mtype contains a valid callback reference. Otherwise, mtype contains 0. The msgInfo parameter is a pointer to a call appearance generic message structure (page 5-44). If the value parameter contains telCallbackEst, telCallbackFailed or telCallbackCleared, that structure specifies the remote directory number and name to which the callback request applies. If the value parameter contains telCallbackNowAvail, that structure specifies the remote directory number and name to be called back. If the value parameter contains telCallbackDesired or telCallbackDesiredCleared, that structure specifies the remote directory number and name that wants a return call.
telCARejectMsg
Your application receives this message when (1) you call the TELRejectCall function to reject a call; (2) a user manually rejects a call; or (3) a call originated by your application is rejected by the remote end. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the type or outcome of call rejection activity. The constants are described in "Call Rejection States" (page 5-43). The msgInfo parameter is unused and is set to 0.
telCADeflectMsg
Your application receives this message when (1) you call the TELDeflectCall function to deflect an incoming call; (2) a user manually deflects an incoming call; (3) call forwarding is in effect for the local directory number and an incoming call is automatically deflected as a result; or (4) the remote party deflects your outgoing call to a new directory number. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the type and outcome of call-deflect activity. The constants are described in "Call Deflect Messages" (page 5-36). The msgInfo parameter is a pointer to a call appearance generic message structure (page 5-44). The information in the structure applies to the remote directory number to which the call is being deflected.
telCAForwardMsg
Your application receives this message when a call that you originated is forwarded by the remote party to another directory number. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates type of call forwarding in effect at the remote number. The constants are described in "Call Forward Types and States" (page 5-28). The msgInfo parameter is a pointer to a call appearance generic message structure (page 5-44). The information in the structure applies to the remote directory number to which the call is being forwarded.
telCAConferenceSplitMsg
Your application receives this message when it calls the TELConferenceSplit function to split a conference call. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates whether the call appearance was successfully split from the conference. The constants are described in "Conference Split States" (page 5-36). The msgInfo parameter is a pointer to a call appearance conference message structure (page 5-44) whose relatedCA field contains a handle to the call appearance structure of the conference initiator.
telCAConferenceDropMsg
Your application receives this message when it calls the TELDrop function to drop a call appearance from a conference. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates whether the call appearance was successfully dropped from the conference. The constants are described in "Conference Drop States" (page 5-35). The msgInfo parameter is a pointer to a call appearance conference message structure (page 5-44) whose relatedCA field contains a handle to the call appearance structure of the conference initiator.
telCAQueuedMsg
Your application receives this message when an incoming call is queued to be answered. In response, your application should call either TELAcceptCall or TELRejectCall to accept or reject the call. The mtype, value, and msgInfo parameters are not used and are set to 0.
telCAInUseMsg
Your application receives this message when an incoming call to a multiple-access directory number (MADN) is in use, but at another terminal. The mtype and msgInfo parameters are not used and are set to 0. The value parameter is a constant that provides additional information about the call appearance. The constants are described in "MADN In-Use States" (page 5-41).
telCACallPickupMsg
Your application receives this message when (1) you call the TELCallPickup function to pick up a call alerting at a different terminal; (2) a call originated by your application is picked up at the remote end at a directory number other than the one you specified; or (3) a user manually picks a call alerting at a different terminal. The mtype parameter is unused and is set to 0. The value parameter contains a constant that indicates the outcome of the call pickup activity. The constants are listed in "Call Pickup States" (page 5-42). The msgInfo parameter is a pointer to a call appearance generic message structure (page 5-44). If the value parameter contains telCallPickupEst or telCallPickupFailed, the information in the structure refers to the directory number whose call is to be picked up. If value contains telCallPickedUp, the information applies to the remote directory number at which the call was picked up.
telCAPagingMsg
Your application receives this message when (1) you call the TELPaging function to access a paging feature for a call appearance, or (2) a user manually initiates a page. The mtype parameter is a paging ID if the telephone system requires one; otherwise, mtype is 0. The value parameter is a constant that indicates the outcome of the paging activity. The constants are described in "Paging States" (page 5-40). The msgInfo parameter is not used and is set to 0.
telCAIntercomMsg
Your application receives this message when (1) you call the TELIntercom function to access an intercom feature for a call appearance, or (2) a user manually initiates intercom activity. The mtype parameter is an intercom ID if the telephone system requires one; otherwise, mtype is 0. The value parameter is a constant that indicates the outcome of the intercom activity. The constants are listed in "Intercom States" (page 5-40). The msgInfo parameter is not used and is set to 0.
telCAModemToneMsg
Your application receives this message when a modem tone activity has occurred. The mtype parameter is not used and is set to 0. The value parameter is a constant that indicates whether a modem tone has been detected or if it has ceased. The constants are listed in "Modem Tone States" (page 5-39). The msgInfo parameter is not used and is set to 0.
telCAFaxToneMsg
Your application receives this message when a fax tone activity has occurred. The mtype parameter is not used and is set to 0. The value parameter is a constant that indicates whether a fax tone has been detected or if it has ceased. The constants are listed in "Fax Tone States" (page 5-39). The msgInfo parameter is not used and is set to 0.
telCAIdleMsg
Your application receives this message when a call appearance reverts to the idle state (telCAIdleState). This can happen when (1) you call the TELDrop function to drop a call; (2) you call the TELRejectCall function to reject a call; (3) you call the TELDeflectCall function to deflect a call; (4) you call the TELTransferEstablish or TELTransferBlind function to transfer a call; or (5) a user manually hangs up the phone. The mtype, value, and msgInfo parameters are not used and are set to 0. After getting this message, you should dispose of the handle to the call appearance structure. It is recommended that you do not reuse a call appearance structure. Note that you do not get an idle message when a new call appearance is created, even though its starting state is the idle state.
telCASuccessiveAlertMsg
Your application receives this message each time an incoming call rings at the terminal. The mtype, value, and msgInfo parameters are not used and are set to 0.
telCAUserUserInfoMsg
Your application receives this message if the remote end sends user-to-user information at setup or disconnect time. (Not all switches support user-to-user information.) The mtype and value parameters are not used and are set to 0. The msgInfo parameter is a pointer to a call appearance user-to-user information message structure (page 5-46) containing user-to-user information.
telCAHandOffMsg
Your application receives this message when you have registered to receive auto-answered calls (by calling the TELDNSetAutoAnswer function) and an incoming call is auto-answered. When your application gets this message, it is in control of the call and can do whatever is appropriate. For example, you might play a recording telling the caller to leave a message or put the call on a speakerphone. The mtype parameter is a Boolean value that indicates whether the call was answered on the call saver ring count. (The Call Saver feature refers to the ability to auto-answer a call on a greater or lesser number of rings, depending on certain conditions, such as the existence of voice mail messages.) This parameter contains true if the call was answered on toll-saver rings. Otherwise, it contains false. The value parameter is a Boolean value that indicates whether or not voice has been detected in the incoming call. This parameter contains true if voice was detected. Otherwise, it contains false. The msgInfo parameter is not used and is set to 0.
telCAVoiceDetectedMsg
Your application receives this message when you have previously called the TELCAVoiceDetect function to activate voice detection and a telephone tool subsequently detects voice on the line. You can use this message to smoothly handle a situation in which the remote party answers a call before you are notified that the call is ringing at the remote end. The mtype, value, and msgInfo parameters are not used and are set to 0. Not all telephone tools support this message.
telCASilenceDetectedMsg
Your application receives this message when you have previously called the TELCASilenceDetect function to activate silence detection and a telephone tool subsequently detects silence on the line. The value parameter contains the period of time, expressed in seconds, during which silence was detected on the telephone line. The mtype and msgInfo parameters are not used and are set to 0. Not all telephone tools support this message.
telCADigitsImmMsg
Your application receives this message when a key is pressed at a remote directory number. (Key presses on a local terminal are handled by your terminal message handler.) This message conveys the same information as the telCADigitsMsg message (page 5-19), but it is sent to your message handler immediately instead of at system-task time. As a result, your message handler might be called at interrupt time with a telCADigitsImmMsg message. Note that both telCADigitsMsg and telCADigitsImmMsg messages are sent for each remote keypress; your application must make sure to respond to only one of each pair of messages. Getting this message at interrupt time allows your application to more easily implement features involving recording and playing sounds using the Sound Manager. For example, you can implement an answering machine feature that allows a remote caller to skip the recorded greeting and leave a voice message immediately when the caller presses a key that you specify. In this case, you need to be informed of the key press immediately so you can stop playing the greeting and capture the voice message.
telCAOtherMsg
Your application receives this message when a telephone tool needs to send it some information about a call appearance that cannot be provided by the other call appearance messages. The values passed in the mtype, value, and msgInfo parameters are defined by the telephone tool.
telAllCAMsgs
All call appearance events except telCAOtherMsg.