Main Code Resource Messages (IM: Telephony)

Chapter 6 - Telephone Tools / Telephone Tools Reference

Main Code Resource Messages
A telephone tool's main code resource must be able to handle a large number of messages. For all messages passed to your tool, the hTEL parameter is a handle to a telephone record for the user's telephone terminal, and pTELTerm is a pointer to a telephone terminal record for that terminal. In addition, hDN is a handle to a directory number structure, and hCA is a handle to a call appearance structure. The msg parameter is one of the following constants. The meanings of the other parameters (namely, p1, p2, and p3) differ according to the type of message passed.

Note
This section describes the messages sent from the Telephone Manager to your telephone tool. For a description of the messages that your tool can send to the Telephone Manager (and hence to an application), see the chapter "Telephone Manager Messages."
enum {
   telNewMsg                    = 0,
   telDisposeMsg                = 1,
   telSuspendMsg                = 2,
   telResumeMsg                 = 3,
   telMenuMsg                   = 4,
   telEventMsg                  = 5,
   telActivateMsg               = 6,
   telDeactivateMsg             = 7,

   telIdleMsg                   = 50,
   telOpenTermMsg               = 51,
   telResetTermMsg              = 52,
   telCloseTermMsg              = 53,
   telTermMsgHandMsg            = 54,
   telClrTermMsgHandMsg         = 55,
   telTermEventsSuppMsg         = 56,
   telGetInfoMsg                = 57,

   telCountDNsMsg               = 60,
   telDNLookupByIndexMsg        = 61,
   telDNLookupByNameMsg         = 62,
   telCallbackClearMsg          = 63,
   telOtherFeatListMsg          = 64,
   telOtherFeatImplMsg          = 65,
   telToolFunctionsMsg          = 66,
   telOtherFunctionMsg          = 67,

   telGetHookswMsg              = 70,
   telSetHookswMsg              = 71,
   telGetVolumeMsg              = 72,
   telSetVolumeMsg              = 73,
   telAlertMsg                  = 74,
   telGetDisplayMsg             = 75,
   telSetDisplayMsg             = 76,

   telDNSelectMsg               = 100,
   telDNDisposeMsg              = 101,
   telGetDNInfoMsg              = 102,
   telGetDNFlagsMsg             = 103,
   telDNMsgHandMsg              = 104,
   telClrDNMsgHandMsg           = 105,
   telDNEventsSuppMsg           = 106,

   telCountCAsMsg               = 110,
   telCALookupMsg               = 111,
   telCAMsgHandMsg              = 112,
   telClrCAMsgHandMsg           = 113,
   telCAEventsSuppMsg           = 114,
   telSetupCallMsg              = 115,

   telForwardSetMsg             = 120,
   telForwardClearMsg           = 121,
   telDNDSetMsg                 = 122,
   telDNDClearMsg               = 123,

   telCADisposeMsg              = 200,
   telGetCAStateMsg             = 201,
   telGetCAFlagsMsg             = 202,
   telGetCAInfoMsg              = 203,
   telConnectMsg                = 204,
   telDialDigitsMsg             = 205,
   telAcceptCallMsg             = 206,
   telRejectCallMsg             = 207,
   telDeflectCallMsg            = 208,
   telAnswerCallMsg             = 209,
   telDropMsg                   = 210,
   telHoldMsg                   = 211,
   telRetrieveMsg               = 212,
   telConfSplitMsg              = 213,
   telTransfBlindMsg            = 214,
   telCallbackSetMsg            = 215,
   telCallbackNowMsg            = 216,
   telCallPickupMsg             = 217,
   telParkCallMsg               = 218,
   telRetrieveParkedCallMsg     = 219,
   telVoiceMailAccessMsg        = 220,
   telPagingMsg                 = 221,
   telIntercomMsg               = 222,

   telConfPrepMsg               = 230,
   telConfEstMsg                = 231,
   telTransfPrepMsg             = 232,
   telTransfEstMsg              = 233,
   
   telGetDNSoundInputMsg        = 240,
   telDisposeDNSoundInputMsg    = 241,
   telGetDNSoundOutputMsg       = 242,
   telDisposeDNSoundOutputMsg   = 243,
   telGetHSSoundInputMsg        = 244,
   telDisposeHSSoundInputMsg    = 245,
   telGetHSSoundOutputMsg       = 246,
   telDisposeHSSoundOutputMsg   = 247,
   telDNSetDTMFMsg              = 248,
   telDNGetDTMFMsg              = 249,
   telHSSetDTMFMsg              = 250,
   telHSGetDTMFMsg              = 251,
   telGetDNStatusMsg            = 252,
   telGetDNProgressDetMsg       = 253,
   telSetDNProgressDetMsg       = 254,
   
   telDNSetAutoAnswerMsg        = 260,
   telDNTollSaverControlMsg     = 261,
   telSetIndHSConnectMsg        = 262,
   telGetIndHSConnectMsg        = 263,
   
   telCAVoiceDetectMsg          = 270,
   telCASilenceDetectMsg        = 271
};
Constant descriptions

telNewMsg
Your tool receives this message when an application requests that the Telephone Manager create a new telephone record associated with your tool. The parameter p1 is the tool ID. Your tool should use this ID when sending messages to the Telephone Manager. Parameters hDN, hCA, p2, and p3 are unused.

In response to this message, your tool should fill in any fields that it can in the structures specified by hTEL and pTELTerm. Your tool may need to open the terminal driver now, before receiving the message telOpenTermMsg, to get the configuration information needed to fill in the telephone record. When done, your tool should return 0 if the request was handled.

It's possible to receive telNewMsg more than once (for instance, if more than one application is using the Telephone Manager). As a convenience, in all telNewMsg messages except the first, the Telephone Manager places a pointer to your tool's private storage in the telPrivate field of telephone record hTEL. But in the first telNewMsg message, telPrivate is set to 0. Thus, instead of initializing private storage for each telNewMsg message, your tool can check the telPrivate field and initialize the private storage only if telPrivate is zero.
telDisposeMsg
Your tool receives this message when an application requests that the Telephone Manager dispose of a handle to a telephone record associated with your tool. In response to this message, your tool should perform any necessary cleanup. When done, your tool should return 0 if the request was handled. You cannot prevent the Telephone Manager from disposing of the handle once your message handler returns. Note that your tool should not drop any existing call appearances unless it receives a telDropMsg or telDNSelectMsg message. Parameters hDN, hCA, p1, p2, and p3 are unused.
telSuspendMsg
Your tool receives this message when an application calls TELResume to have your tool perform some action in response to a suspend event. For instance, your tool might need to remove a tool-specific menu from the menu bar. Parameters hDN, hCA, p1, p2, and p3 are unused.
telResumeMsg
Your tool receives this message when an application calls TELResume to have your tool perform some action in response to a resume event. For instance, your tool might need to install a tool-specific menu in the menu bar. Parameters hDN, hCA, p1, p2, and p3 are unused.
telMenuMsg
Your tool receives this message when an application calls TELMenu to have your tool process an event generated when a user chooses an item from a menu installed by a telephone tool. On entry, parameter p1 contains the menu ID associated with the menu, and parameter p2 contains the number of the selected menu item. Parameters hDN, hCA, and p3 are unused. On exit, your tool should return 1 if it handled the menu event and 0 otherwise.
telEventMsg
Your tool receives this message when an application calls TELEvent to have your tool process an event in a window associated with your tool. On entry, parameter p1 contains a pointer to an event record (of type EventRecord) that describes the event. In addition, the refcon field of the window record contains a handle to the telephone record for your tool. Parameters hDN, hCA, p2, and p3 are unused.
telActivateMsg
Your tool receives this message when an application calls TELActivate to have your tool perform some action in response to an activate event. For instance, your tool might need to install a tool-specific menu in the menu bar. Parameters hDN, hCA, p1, p2, and p3 are unused.
telDeactivateMsg
Your tool receives this message when an application calls TELActivate to have your tool perform some action in response to a deactivate event. For instance, your tool might need to remove a tool-specific menu from the menu bar. Parameters hDN, hCA, p1, p2, and p3 are unused.
telIdleMsg
Your tool receives this message when an application calls TELIdle to give your tool time to do idle processing. For instance, your tool might need to check on the progress of existing calls or check for any new incoming calls. If any such activities occur, your tool should send an appropriate message to the Telephone Manager. Parameters hDN, hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully, or telTermErrorMsg if it encounters some problem during execution.
telOpenTermMsg
Your tool receives this message when an application calls TELOpenTerm to open a telephone terminal. Your tool should open any associated terminal drivers and make the terminal ready for use. If necessary, your tool can update the information in the pTELTerm parameter. Parameters hDN, hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. In addition, your tool should send a telTermOpenMsg and a telTermEnableMsg message to the Telephone Manager and increment any use-count variables the tool maintains internally. If your tool encounters any problems while opening a terminal, it should send telTermErrorMsg.
telResetTermMsg
Your tool receives this message when an application calls TELResetTerm to reset a telephone terminal. Your tool should close and then reopen any associated terminal drivers and make the terminal ready for use by clearing the state of the terminal, its directory numbers, and their call appearances. Your tool can also reboot any underlying hardware. If necessary, your tool should update the information in the hTEL parameter. Parameters hDN, hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. In addition, your tool should send a telTermResetMsg to the Telephone Manager. If your tool encounters any problems while resetting a terminal, it should send telTermErrorMsg.
telCloseTermMsg
Your tool receives this message when an application calls TELCloseTerm to close a telephone terminal. Your tool should close any associated terminal drivers if the use count falls to 0. If necessary, your tool should update the information in the hTEL parameter, but it should not disconnect any existing calls. Parameters hDN, hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. In addition, your tool should send a telTermCloseMsg to the Telephone Manager. If your tool encounters any problems while resetting a terminal, it should send telTermErrorMsg.
telTermMsgHandMsg
Your tool receives this message when an application calls TELTermMsgHand to register a telephone terminal message handler. On entry, parameter p1 is a mask of events about which the application wants to be notified. See "Terminal Messages" on page 5-9 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master terminal message handler, and parameter p3 is a pointer to the global data for that master message handler. Parameters hDN and hCA are unused. Your tool should return 0 if it completes successfully.
telClrTermMsgHandMsg
Your tool receives this message when an application calls TELClrTermMsgHand to clear the telephone terminal message handler installed by that application. On entry, parameter p1 is a new mask of events about which other applications want to be notified; if no other applications have installed a terminal message handler for your tool, p1 is 0. See "Terminal Messages" on page 5-9 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master terminal message handler. If p1 is 0, p2 is also 0. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully.
telTermEventsSuppMsg
Your tool receives this message when an application calls TELTermEventsSupp to determine which terminal messages your telephone tool supports. On entry, parameter p1 is a pointer to a 4-byte area of memory; your tool should fill in that memory with an event mask indicating which terminal messages it supports. See "Terminal Messages" on page 5-9 for complete information about message masks. Parameters hDN, hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telGetInfoMsg
Your tool receives this message when an application calls TELGetInfo to get information about a telephone terminal. In response to this message, your tool should update the telPrivate field of the telephone record specified by the hTEL parameter and all the fields of the telephone terminal record specified by the pTELTerm parameter. Your tool should keep the information for each telephone record in its private storage and update the record only when requested to do so. Parameters hDN, hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If the hTEL parameter is invalid, your tool should set the tRef field of pTELTerm to -1 and return telBadTermErr.
telCountDNsMsg
Your tool receives this message when an application calls TELCountDNs to count the directory numbers associated with a telephone terminal. On entry, parameter p1 specifies the types of directory numbers to count. See "Directory Number Types" on page 3-6 for a description of the available directory number types. Parameter p2 specifies whether to count all directory numbers (true) or only those to which commands can be sent (false). Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully. If your tool does not support directory numbers of the specified type, your tool should return telBadDNType.
telDNLookupByIndexMsg
Your tool receives this message when an application calls TELDNLookupByIndex to find a directory number by index in a terminal's list of directory numbers. On entry, parameter p1 specifies the types of directory numbers to search. See "Directory Number Types" on page 3-6 for a description of the available directory number types. Parameter p2 specifies whether to search all directory numbers (true) or only those to which commands can be sent (false). Parameter p3 is the index. Parameter hCA is unused. If the specified index is valid, your tool should fill in these fields of the directory number structure specified by the hDN parameter: dn, dnRef, dnPartyName, dnSubaddress, maxAllocCA, curAllocCA, dnType, featureFlags, forwardFlags, numPageIDs, numIntercomIDs, numPickupIDs, and telDNPrivate. Your tools should not update the fields relating to forwarding numbers, subaddresses, or party names. (These fields are updated each time the Telephone Manager receives the message telDNForwardMsg from your tool.) Your tool should return 0 if it completes successfully. If the specified index is invalid, your tools should return telBadIndexErr. If your tool does not support directory numbers of the specified type, your tool should return telDNTypeNotSupp. When any error occurs, your tool should set the dnRef field of hDN to -1. The Telephone Manager will then dispose of hDN.
telDNLookupByNameMsg
Your tool receives this message when an application calls TELDNLookupByName to find a directory number by name. On entry, parameter p1 points to a Pascal-style string that contains the name of a directory number. Parameters hCA, p2, and p3 are unused. If the specified name is valid, your tool should fill in these fields of the directory number structure specified by the hDN parameter: dn, dnRef, dnPartyName, dnSubaddress, maxAllocCA, curAllocCA, dnType, featureFlags, forwardFlags, numPageIDs, numIntercomIDs, numPickupIDs, and telDNPrivate. Your tools should not update the fields relating to forwarding numbers, subaddresses, or party names. (These fields are updated each time the Telephone Manager receives the message telDNForwardMsg from your tool.) Your tool should return 0 if it completes successfully. If the specified name is invalid, your tool should set the dnRef field of hDN to -1 and return telBadDNErr. The Telephone Manager will then dispose of hDN.
telCallbackClearMsg
Your tool receives this message when an application calls TELCallbackClear to clear a callback request. On entry, parameter p1 is a value that identifies the callback request to be cleared. Parameters hCA, p2, and p3 are unused. If the specified callback request is valid, your tool should clear the request. Your tool should return 0 if it completes successfully. If the specified callback request is invalid, your tool should return telNoCAllbackRef. If no callback is set, your tool should return telCBErr.
telOtherFeatListMsg
Your tool receives this message when an application calls TELOtherFeatureList to get a list of network-switch features that can be accessed without passing any tool-specific parameters. On exit, parameter p1 is a pointer to a linked list of FeatureList structures that describe those features. These features should be simple ones that require only feature descriptor and a handle to a telephone record, directory number structure, or call appearance structure. Parameters hDN, hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully and a Telephone Manager result code otherwise.
telOtherFeatImplMsg
Your tool receives this message when an application calls TELOtherFeatureImplement to invoke a network-switch feature returned by the TELOtherFeatureList function. On entry, parameter p1 is a handle to a structure needed to pass information needed by your tool and parameter p2 is the feature ID of the requested feature. The calling application can determine which type of structure to use by inspecting the handleType field of a feature list structure. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully and a Telephone Manager result code otherwise.
telToolFunctionsMsg
Your tool receives this message when an application calls TELToolFunctions to determine whether your telephone tool supports a specified Telephone Manager function. On entry, parameter p1 is a message code associated with a particular Telephone Manager function, and p2 points to a Boolean value. Your tool should set that Boolean value to true if it supports the specified function and to false otherwise. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully.
telOtherFunctionMsg
Your tool receives this message when an application calls TELOtherFunction to invoke a tool-specific feature. On entry, parameter p1 is a pointer to a parameter block and parameter p2 is the size, in bytes, of that parameter block. You are responsible for documenting the structure and size of that parameter block. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully.
telGetHookswMsg
Your tool receives this message when an application calls TELGetHooksw to get the state of a terminal's hookswitch. On entry, parameter p1 is the hookswitch type; see "Hookswitch Types and States" on page 2-11 for the available hookswitch types. Parameter p2 points to a Boolean value. Your tool should set that Boolean value to telDeviceOnHook if the device is on hook and to telDeviceOffHook otherwise. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully.
telSetHookswMsg
Your tool receives this message when an application calls TELSetHooksw to set the state of a terminal's hookswitch. On entry, parameter p1 is the hookswitch type; see "Hookswitch Types and States" on page 2-11 for the available hookswitch types. Parameter p2 is telDeviceOnHook if the device is to be on hook and telDeviceOffHook otherwise. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully. In addition, if the hookswitch state has changed, your tool should send the message telTermHookswMsg. If your tool does not support the value passed in p1, it should return telHTypeNotSupp. Note that your tool should support the telSetHookswMsg message only if it can change the physical state of the specified device (for example, if it can turn on a speakerphone).
telGetVolumeMsg
Your tool receives this message when an application calls TELGetVolume to get the volume and state of a terminal device. On entry, parameter p1 is the terminal device type. Parameter p2 is a pointer to a 2-byte area of memory into which your tool should copy the current volume level of the specified terminal device. Parameter p3 is a pointer to a 2-byte area of memory into which your tool should copy the current volume state of the specified terminal device. See "Volume Controls" on page 2-12 for the available device types and volume states. Parameters hDN and hCA are unused. Your tool should return 0 if it completes successfully. If your tool does not support the device type passed in p1, it should return telVolTypeNotSupp.
telSetVolumeMsg
Your tool receives this message when an application calls TELSetVolume to set the volume and state of a terminal device. On entry, parameter p1 is the terminal device type. Parameter p2 is a pointer to a 2-byte area of memory that contains the desired volume level of the specified terminal device. If this level is greater than the maximum volume level your tool supports, you should set the volume to the maximum level and return that level in the memory pointed to by p2. Parameter p3 is a pointer to a 2-byte area of memory that contains the desired volume state of the specified terminal device. See "Volume Controls" on page 2-12 for the available device types and volume states. Parameters hDN and hCA are unused. Your tool should return 0 if it completes successfully. If your tool does not support the device type passed in p1, it should return telVolTypeNotSupp. Note that your tool should support the telSetVolumeMsg message only if it can change the volume of the specified device.
telAlertMsg
Your tool receives this message when an application calls TELAlert to ring a terminal device. On entry, parameter p1 is a pointer to a 2-byte area of memory that contains the desired volume level of the ringer. If this level is 0, your tool should leave the volume level unchanged. If this level is greater than the maximum volume level your tool supports, you should set the volume to the maximum level and return that level in the memory pointed to by p1. Parameter p2 is an alerting pattern. See "Alerting Patterns" on page 2-15 for the available alerting patterns. If your tool does not support the requested alerting pattern, it should return telAPattNotSupp. Parameters hDN, hCA, and p3 are unused. Your tool should return 0 if it completes successfully.
telGetDisplayMsg
Your tool receives this message when an application calls TELGetDisplay to get the text displayed on a terminal and the display mode of the terminal. On entry, parameter p1 is the index of the item of the displayed text to get; see "Display Items" on page 2-10 for a description of the available display items. On exit, parameter p2 is a pointer to a Pascal-style string that contains the text of the specified item on the display of the specified terminal. Your tool is responsible for allocating this string, but the calling application is responsible for disposing of it. On exit, parameter p3 is a pointer to a 2-byte value that is the current display mode of the specified terminal. If your tool does not support the specified display item, it should return telIndexNotSupp. Parameters hDN and hCA are unused. Your tool should return 0 if it completes successfully.
telSetDisplayMsg
Your tool receives this message when an application calls TELSetDisplay to set the text displayed on a terminal and the display mode of the terminal. On entry, parameter p1 is the index of the item of the displayed text to set; see "Display Items" on page 2-10 for a description of the available display items. Parameter p2 is a pointer to a Pascal-style string that contains the desired text of the specified item on the display of the specified terminal. Parameter p3 is a pointer to a 2-byte value that is the desired display mode of the specified terminal. If your tool does not support the specified display item, it should return telIndexNotSupp. If your tool does not support the specified display mode, it should return telDisplayModeNotSupp. Parameters hDN and hCA are unused. Your tool should return 0 if it completes successfully and, if the display has changed, send the telTermDisplayMsg message to the Telephone Manager.
telDNSelectMsg
Your tool receives this message when an application calls TELDNSelect to select or deselect a directory number. On entry, parameter p1 is a Boolean value that indicates whether to select (true) or deselect (false) the specified directory number. Parameters hDN, hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telDNDisposeMsg
Your tool receives this message when an application requests that the Telephone Manager dispose of a handle to a directory number structure associated with your tool. In response to this message, your tool should perform any necessary cleanup. Your tool should dispose of the string pointers dn, dnSubaddress, and dnPartyName, but no others. When done, your tool should return 0 if the request was handled. You cannot prevent the Telephone Manager from disposing of the handle once your message handler returns. Note that your tool should not drop any existing call appearances unless it receives a telDropMsg or telDNSelectMsg message. Parameters hCA, p1, p2, and p3 are unused.
telGetDNInfoMsg
Your tool receives this message when an application calls TELGetDNInfo to update the information in a directory number structure. In response to this message, your tool should fill in the following fields of the directory number structure specified by the hDN parameter: dn, dnRef, dnPartyName, dnSubaddress, maxAllocCA, curAllocCA, dnType, featureFlags, forwardFlags, numPageIDs, numIntercomIDs, numPickupIDs, and telDNPrivate. Your tool should keep the information for each directory number structure in its private storage and update the structure only when requested to do so. Parameters hCA, p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If the hDN parameter is invalid, your tool should set the dnRef field to -1 and return telBadDNErr.
telGetDNFlagsMsg
Your tool receives this message when an application calls TELGetDNFlags to update the current flags information for a directory number. In response to this message, your tool should fill in the featureFlags and forwardFlags fields of the directory number structure specified by the hDN parameter. On entry, p1 points to 4-byte field into which you should copy the current feature flags of the specified directory number, and p2 points to 4-byte field into which you should copy the current forwarding flags of that directory number. Parameters hCA and p3 are unused. Your tool should return 0 if it completes successfully. If the hDN parameter is invalid, your tool should return telBadDNErr.
telDNMsgHandMsg
Your tool receives this message when an application calls TELDNMsgHand to register a directory number message handler. On entry, parameter p1 is a mask of events about which any application using your tool wants to be notified. See "Directory Number Messages" on page 5-12 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master directory number message handler, and parameter p3 is a pointer to the global data for that master message handler. Parameter hCA is unused. Your tool should return 0 if it completes successfully.
telClrDNMsgHandMsg
Your tool receives this message when an application calls TELClrDNMsgHand to clear the directory number message handler installed by that application. On entry, parameter p1 is a new mask of events about which other applications want to be notified; if no other applications have installed a directory number message handler for your tool, p1 is 0. See "Directory Number Messages" on page 5-12 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master directory number message handler. If p1 is 0, p2 is also 0. Parameters hCA and p3 are unused. Your tool should return 0 if it completes successfully.
telDNEventsSuppMsg
Your tool receives this message when an application calls TELDNEventsSupp to determine which directory number messages your telephone tool supports. On entry, parameter p1 is a pointer to a 4-byte area of memory; your tool should fill in that memory with an event mask indicating which directory number messages it supports. See "Directory Number Messages" on page 5-12 for complete information about message masks. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telCountCAsMsg
Your tool receives this message when an application calls TELCountCAs to count the non-idle call appearances currently associated with a directory number. On entry, parameter p1 specifies the types of call appearances to count. See "Call Origination Types" on page 4-13 for a description of the available call appearances types. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If your tool does not support call appearances of the specified type, your tool should return telIntExtNotSupp.
telCALookupMsg
Your tool receives this message when an application calls TELCALookup to obtain a handle to a call appearance of a specified type and index associated with a directory number. On entry, parameter p1 is the type of call appearance to consider; see "Call Origination Types" on page 4-13 for a description of the available call appearance types. Parameter p2 is the 1-based index in the list of call appearances of that type associated with the directory number specified by the hDN parameter. Parameter p3 is unused. If the specified index is valid, your tool should fill in these fields of the call appearance structure specified by the hCA parameter: caState, intExt, callType, dialType, bearerType, rate, conferenceLimit, featureFlags, otherFeatures, and telCAPrivate. Your tool should not update any of the fields of type StringPtr. (These fields are updated each time the Telephone Manager receives the message telCAProgressMsg with value set to telCAPUpdate or telCARouted from your tool.) In addition, your tool should not change the caRef field, except as warranted by error conditions. Your tool should return 0 if it completes successfully. If the specified index is invalid, your tool should return telBadIndexErr. If your tool does not support call appearances of the specified type, your tool should return telIntExtNotSupp or telBadCAType. When any error occurs, your tool should set the caRef field of hCA to -1.
telCAMsgHandMsg
Your tool receives this message when an application calls TELCAMsgHand to register a call appearance message handler. On entry, parameter p1 is a mask of events about which any application using your tool wants to be notified. See "Call Appearance Messages" on page 5-14 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master call appearance message handler, and parameter p3 is a pointer to the global data for that master message handler. Parameter hCA is unused. Your tool should return 0 if it completes successfully.
telClrCAMsgHandMsg
Your tool receives this message when an application calls TELClrCAMsgHand to clear the call appearance message handler installed by that application. On entry, parameter p1 is a new mask of events about which other applications want to be notified; if no other applications have installed a call appearance message handler for your tool, p1 is 0. See "Call Appearance Messages" on page 5-14 for complete information about message masks. Parameter p2 is a pointer to the Telephone Manager's master call appearance message handler. If p1 is 0, p2 is also 0. Parameters hCA and p3 are unused. Your tool should return 0 if it completes successfully.
telCAEventsSuppMsg
Your tool receives this message when an application calls TELCAEventsSupp to determine which call appearance messages your telephone tool supports. On entry, parameter p1 is a pointer to a 4-byte area of memory; your tool should fill in that memory with an event mask indicating which call appearance messages it supports. See "Call Appearance Messages" on page 5-14 for complete information about message masks. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telSetupCallMsg
Your tool receives this message when an application calls TELSetupCall to create a call appearance structure for an outgoing call. On entry, parameter hCA is a handle to a call appearance record in which the Telephone Manager has already filled in the rmtDN, rmtPartyName, and rmtSubaddress fields. Your tool should fill in these fields: caState, intExt, callType, dialType, bearerType, rate, conferenceLimit, featureFlags, otherFeatures, and telCAPrivate. Parameter p1 is a pointer to a Pascal-style string containing user-to-user information, as defined by certain telephone networks. If your tool doesn't support user-to-user information, it should ignore this parameter. Parameters p2 and p3 specify the bearer type and rate; currently, however, these parameters should always be 0. Your tool should return 0 if it completes successfully. If any error occurs, your tool should set the caRef field of hCA to -1.
telForwardSetMsg
Your tool receives this message when an application calls TELForwardSet to cause incoming calls for one directory number to be forwarded to another. On entry, parameter p1 is a pointer to a call forwarding message parameter block (page 6-60) describing the destination directory number and type of call forwarding. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully or telFwdTypeNotSupp if it doesn't support the specified type of call forwarding. Your tool should not update the fields in hDN that relate to call forwarding (they are updated each time the Telephone Manager receives the message telDNForwardMsg from your tool).
telForwardClearMsg
Your tool receives this message when an application calls TELForwardClear to stop call forwarding on a directory number. On entry, parameter p2 is a the type of call forwarding to stop; see "Call Forwarding Types" on page 3-11 for a description of the available forwarding types. Parameters hCA, p1, and p3 are unused. Your tool should return 0 if it completes successfully or telFwdTypeNotSupp if it doesn't support the specified type of call forwarding. Your tool should not clear any strings in hDN that relate to call forwarding (the Telephone Manager clears them).
telDNDSetMsg
Your tool receives this message when an application calls TELDNDSet to activate a Do Not Disturb feature for a directory number. On entry, parameter p1 specifies the type of Do Not Disturb feature to activate; see "Do Not Disturb Types" on page 3-11 for a description of the available types. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully or telDNDTypeNotSupp if it doesn't support the specified type of Do Not Disturb feature.
telDNDClearMsg
Your tool receives this message when an application calls TELDNDClear to clear a Do Not Disturb feature for a directory number. On entry, parameter p1 specifies the type of Do Not Disturb feature to clear; see "Do Not Disturb Types" on page 3-11 for a description of the available types. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully or telDNDTypeNotSupp if it doesn't support the specified type of Do Not Disturb feature.
telCADisposeMsg
Your tool receives this message when an application requests that the Telephone Manager dispose of a handle to a call appearance structure associated with your tool. In response to this message, your tool should perform any necessary cleanup. Your tool should not dispose of the call appearance structure specified by the hCA parameter, nor should your tool dispose of any string pointers in that structure. When done, your tool should return 0 if the request was handled. You cannot prevent the Telephone Manager from disposing of the handle once your message handler returns. Note that your tool should not drop any existing call appearances unless it receives a telDropMsg or telDNSelectMsg message. Parameters p1, p2, and p3 are unused.
telGetCAStateMsg
Your tool receives this message when an application calls TELGetCAState to retrieve the current state of a call appearance. On entry, parameter p1 is a pointer to a 2-byte value into which your tool should copy the current state of the call appearance specified by the hCA parameter. Your tool should also update the caState field of the hCA structure. See "Call Appearance States" on page 4-10 for a description of the available call appearance states. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully. If the hCA parameter references an idle call appearance, your tool should set the caRef field to -1 and return telBadCAErr.
telGetCAFlagsMsg
Your tool receives this message when an application calls TELGetCAFlags to retrieve the current feature settings of a call appearance. On entry, parameter p1 is a pointer to a 4-byte value into which your tool should copy the current feature settings of the call appearance specified by the hCA parameter. Parameter p2 is a pointer to a 4-byte value into which your tool should copy the current other feature settings of that call appearance. Your tool should also update the featureFlags and otherFeatures fields of the hCA structure. See "Call Appearance Feature Flags" on page 4-14 and "Other Call Appearance Feature Flags" on page 4-16 for a description of the available call appearance features. Parameter p3 is unused. Your tool should return 0 if it completes successfully. If the hCA parameter is invalid, your tool should return telBadCAErr.
telGetCAInfoMsg
Your tool receives this message when an application calls TELGetCAInfo to update the fields of a call appearance structure. Your tool should update these fields of the hCA structure, based on information about the call appearance that it maintains privately: caState, intExt, callType, dialType, bearerType, rate, conferenceLimit, featureFlags, otherFeatures, and telCAPrivate. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If the hCA parameter references an idle call appearance, your tool should set the caRef field to -1 and return telBadCAErr.
telConnectMsg
Your tool receives this message when an application calls TELConnect to place an outgoing call using the information in the call appearance structure to which hCA is a handle. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If the hCA parameter is invalid, your tool should set the caRef field to -1 and return telBadCAErr.
telDialDigitsMsg
Your tool receives this message when an application calls TELDialDigits to dial a sequence of digits using dual-tone multifrequency (DTMF) tones. On entry, parameter p1 is a pointer to a Pascal-style string that contains a sequence of ASCII digits. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telAcceptCallMsg
Your tool receives this message when an application calls TELAcceptCall to accept an incoming call. The call must be in the telCAOfferState state. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telRejectCallMsg
Your tool receives this message when an application calls TELRejectCall to reject an incoming call. The state of the incoming call must be telCAAlertingState or telCAOfferState. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully. If the call appearance is not in an alerting state, your tool should not reject the call; instead, it should return telCANotRejectable.
telDeflectCallMsg
Your tool receives this message when an application calls TELDeflectCall to deflect an incoming call to another directory number. The call must be in the telCAAlertingState or telCAOfferState state. On entry, parameter p1 is a pointer to a Pascal-style string containing the directory number to which the call is to be deflected. Parameter p2 is a pointer to a Pascal-style string containing the subaddress, as defined by the ISDN S-Bus specification, of the directory number to which the call is to be deflected; if your tool does not support subaddressing, it can ignore p2. Parameter p3 is a pointer to a Pascal-style string containing the name of the party associated with the directory number to which the call is to be deflected. Your tool should save the vales passed in the p1, p2, and p3 parameters and pass them back in the telCADeflectMsg message. Your tool should return 0 if it completes successfully. If your telephone network switch doesn't support call deflection, your tool can mimic this feature by performing a blind transfer by first answering the call and then immediately transferring it to the destination directory number.
telAnswerCallMsg
Your tool receives this message when an application calls TELAnswerCall to answer an incoming call. The state of the incoming call must be telCAAlertingState or telCAOfferState. If the state is telCAOfferState, your tool should both accept the incoming call and answer it. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telDropMsg
Your tool receives this message when an application calls TELDrop to drop a call. On entry, parameter p1 is a pointer to a Pascal-style string containing user-to-user information, as defined by certain telephone networks. If your tool doesn't support user-to-user information, it should ignore this parameter. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telHoldMsg
Your tool receives this message when an application calls TELHold to put a call on hold. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telRetrieveMsg
Your tool receives this message when an application calls TELRetrieve to retrieve a call that is on hold. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telConfSplitMsg
Your tool receives this message when an application calls TELConferenceSplit to split a call from a conference. Your tool should remove the call from the conference but it should not drop the call. Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telTransfBlindMsg
Your tool receives this message when an application calls TELTransferBlind to transfer a call immediately without first connecting the user to the destination party. On entry, parameter p1 is a pointer to a Pascal-style string containing the directory number to which the call is to be transferred. Parameter p2 is a pointer to a Pascal-style string containing the subaddress, as defined by the ISDN S-Bus specification, of the directory number to which the call is to be transferred; if your tool does not support subaddressing, it can ignore p2. Parameter p3 is a pointer to a Pascal-style string containing the name of the party associated with the directory number to which the call is to be transferred. Your tool should save the vales passed in the p1, p2, and p3 parameters and pass them back in the telCATransferMsg message. Your tool should return 0 if it completes successfully.
telCallbackSetMsg
Your tool receives this message when an application calls TELCallbackSet to make a callback request. On entry, parameter p1 is a value that identifies the callback request to be made. If the telephone network switch returns a callback reference, your tool should return it in the p1 parameter. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telCallbackNowMsg
Your tool receives this message when an application calls TELCallbackNow to place a call in response to a local or remote callback request. On entry, parameter p1 is a value that identifies the callback request to be placed. If there is more than one callback request for your tool, p1 specifies the destination to be called back. (Your tool specified this value previously, when processing the corresponding telCallbackSetMsg message.) Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully. If the specified callback request is invalid, your tool should return telNoCAllbackRef. If no callback is set, your tool should return telCBErr.
telCallPickupMsg
Your tool receives this message when an application calls TELCallPickup to answer a call that is alerting either in a predefined pickup group or at a specified directory number. On entry, parameter p1 is a pointer to a Pascal-style string containing a remote directory number. Parameter p2 is a pointer to a Pascal-style string containing a pickup group identifier. Your tool should use either p1 or p2, depending on the kind of network switch your tool supports. Parameters hCA and p3 are unused. Your tool should return 0 if it completes successfully.
telParkCallMsg
Your tool receives this message when an application calls TELParkCall to park a call, making it available for retrieval at another directory number. On entry, parameter p1 is a pointer to a Pascal-style string; your tool should put an identifier for the parked call. Parameter p2 is a pointer to a Pascal-style string containing a the directory number at which the call will be parked. Parameter p3 is unused. Your tool should return 0 if it completes successfully.
telRetrieveParkedCallMsg
Your tool receives this message when an application calls TELRetrieveParkedCall to retrieve a parked call. The Telephone Manager sends your tool a telSetupCallMsg message before sending it the telRetrieveParkedCallMsg message. On entry, parameter p1 is a pointer to a Pascal-style string containing an identifier for the parked call. Parameters hCA, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telVoiceMailAccessMsg
Your tool receives this message when an application calls TELVoiceMailAccess to access the voice-mail system of a private branch exchange (PBX). Parameters p1, p2, and p3 are unused. Your tool should return 0 if it completes successfully.
telPagingMsg
Your tool receives this message when an application calls TELPaging to access a paging feature defined by the telephone system. On entry, parameter p1 contains an identifier for a specific paging feature. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully. If p1 specifies an invalid page ID, your tool should return telBadPageID.
telIntercomMsg
Your tool receives this message when an application calls TELIntercom to access an intercom feature defined by the telephone system. On entry, parameter p1 contains an identifier for a specific intercom feature. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully. If p1 specifies an invalid intercom ID, your tool should return telBadIntercomID.
telConfPrepMsg
Your tool receives this message when an application calls TELConferencePrep to place a call in preparation for adding a party to a conference. On entry, parameter hCA contains a handle to a call appearance structure for the conference initiator. Parameter p1 contains a handle to a call appearance structure for the call being added to the conference. Parameters p2 specifies the total number of parties, including the conference initiator, that will be part of the conference call after all parties are added. Parameter p3 is unused. Your tool should return 0 if it completes successfully. If p1 specifies a call appearance that is not active, your tool should proceed (as with telConnectMsg) to put the call appearance into an active state.
telConfEstMsg
Your tool receives this message when an application calls TELConferenceEstablish to add a new party to a conference. On entry, parameter hCA contains a handle to a call appearance structure for the conference initiator. Parameter p1 contains a handle to a call appearance structure for the call being added to the conference. Parameters p2 and p3 are unused. Your tool should ensure that this telConfEstMsg message was preceded by a telConfPrepMsg message for the call appearances hCA and p1. If it was, your tool can unite the two call appearances in a conference; if not, your tool can return the error message telConfRej. Your tool should return 0 if it completes successfully.
telTransfPrepMsg
Your tool receives this message when an application calls TELTransferPrep to place a call in preparation for a supervised transfer. On entry, parameter hCA contains a handle to a call appearance structure for the call to be transferred. Parameter p1 contains a handle to a call appearance structure for the new destination number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully. If p1 specifies a call appearance that is not active, your tool should proceed (as with telConnectMsg) to put the call appearance into an active state.
telTransfEstMsg
Your tool receives this message when an application calls TELTransferEstablish to complete a supervised transfer by connecting the party to be transferred with the new destination party. On entry, parameter hCA contains a handle to a call appearance structure for the call to be transferred. Parameter p1 contains a handle to a call appearance structure for the new destination number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetDNSoundInputMsg
Your tool receives this message when an application calls TELGetDNSoundInput to get the name of the current sound input driver for the directory number specified by the hDN parameter. On entry, parameter p1 is a pointer to a Pascal-style string. Your tool should copy the name of the current sound input driver into that string. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDisposeDNSoundInputMsg
Your tool receives this message when an application calls TELDisposeDNSoundInput to dispose of the sound input driver associated with a directory number. On entry, parameter p1 is a pointer to a Pascal-style string that contains the name of the current sound input driver into that string. Your tool should dispose of that driver. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetDNSoundOutputMsg
Your tool receives this message when an application calls TELGetDNSoundOutput to get a component reference to the sound output stream associated with a directory number. On entry, parameter p1 is a pointer to 4-byte area of memory. Your tool should copy a component reference to the sound output stream into that memory. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDisposeDNSoundOutputMsg
Your tool receives this message when an application calls TELDisposeDNSoundOutput to dispose of a sound output component associated with a directory number. On entry, parameter p1 is a reference to the sound output component. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetHSSoundInputMsg
Your tool receives this message when an application calls TELGetHSSoundInput to get the name of the current sound input driver for the telephone handset specified by the hTEL parameter. On entry, parameter p1 is a pointer to a Pascal-style string. Your tool should copy the name of the current sound input driver into that string. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDisposeHSSoundInputMsg
Your tool receives this message when an application calls TELDisposeHSSoundInput to dispose of the sound input driver associated with a telephone handset. On entry, parameter p1 is a pointer to a Pascal-style string that contains the name of the current sound input driver into that string. Your tool should dispose of that driver. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetHSSoundOutputMsg
Your tool receives this message when an application calls TELGetHSSoundOutput to get a component reference to the sound output stream associated with a telephone handset. On entry, parameter p1 is a pointer to 4-byte area of memory. Your tool should copy a component reference to the sound output stream into that memory. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDisposeHSSoundOutputMsg
Your tool receives this message when an application calls TELDisposeHSSoundOutput to dispose of a sound output component associated with a telephone handset. On entry, parameter p1 is a reference to the sound output component. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDNSetDTMFMsg
Your tool receives this message when an application calls TELDNSetDTMF to set the current state of DTMF detection for a directory number. On entry, parameter p1 is a pointer to a Boolean value that indicates the desired DTMF detection state, enabled (true) or disabled (false). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDNGetDTMFMsg
Your tool receives this message when an application calls TELDNGetDTMF to get the current state of DTMF detection for a directory number. On entry, parameter p1 is a pointer to a Boolean value; your tool should set that value to indicate the current DTMF detection state, enabled (true) or disabled (false). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telHSSetDTMFMsg
Your tool receives this message when an application calls TELHSSetDTMF to set the current state of DTMF detection for a telephone handset. On entry, parameter p1 is a pointer to a Boolean value that indicates the desired DTMF detection state, enabled (true) or disabled (false). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telHSGetDTMFMsg
Your tool receives this message when an application calls TELHSGetDTMF to get the current state of DTMF detection for a telephone handset. On entry, parameter p1 is a pointer to a Boolean value; your tool should set that value to indicate the current DTMF detection state, enabled (true) or disabled (false). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetDNStatusMsg
Your tool receives this message when an application calls TELGetDNStatus to get the current status of a directory number. On entry, parameter p1 is a pointer to a 4-byte value; your tool should set that value to indicate the current directory number status. See "Directory Number States" on page 3-6 for a description of the available states. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetDNProgressDetMsg
Your tool receives this message when an application calls TELGetDNProgressDet to get the state of the call progress indicator for a directory number. On entry, parameter p1 is a pointer to a Boolean value; your tool should set that value to indicate whether the call progress indicator is on (true) or off (false) for the specified directory number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telSetDNProgressDetMsg
Your tool receives this message when an application calls TELSetDNProgressDet to set the state of the call progress indicator for a directory number. On entry, parameter p1 is a pointer to a Boolean value that indicates whether the call progress indicator is to be on (true) or off (false) for the specified directory number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDNSetAutoAnswerMsg
Your tool receives this message when an application calls TELDNSetAutoAnswer to enable or disable routing of auto-answered incoming calls to that application. On entry, parameter p1 is a pointer to a Boolean value that indicates whether to enable (true) or disable (false) routing of auto-answered incoming calls for the specified directory number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telDNTollSaverControlMsg
Your tool receives this message when an application calls TELDNSetAutoAnswer to enable or disable the Call Saver feature for a directory number. On entry, parameter p1 is a pointer to a Boolean value that indicates whether to enable (true) or disable (false) the Call Saver feature for the specified directory number. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telSetIndHSConnectMsg
Your tool receives this message when an application calls TELSetIndHSConnect to set the connection state of a telephone handset. On entry, parameter p1 is a pointer to a Boolean value that indicates whether the specified telephone handset is to be connected (telIndHSConnected) or disconnected (telIndHSDisconnected). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telGetIndHSConnectMsg
Your tool receives this message when an application calls TELGetIndHSConnect to get the connection state of a telephone handset. On entry, parameter p1 is a pointer to a Boolean value; your tool should copy a value that indicates whether the specified telephone handset is connected (telIndHSConnected) or disconnected (telIndHSDisconnected). Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telCAVoiceDetectMsg
Your tool receives this message when an application calls TELCAVoiceDetect to activate or deactivate voice detection on a call appearance. On entry, parameter p1 is a pointer to a Boolean value that indicates whether to activate (true) or deactivate (false) voice detection for the specified call appearance. Parameters p2 and p3 are unused. Your tool should return 0 if it completes successfully.
telCASilenceDetectMsg
Your tool receives this message when an application calls TELCASilenceDetect to activate or deactivate silence detection on a call appearance. On entry, parameter p1 is a pointer to a Boolean value that indicates whether to activate (true) or deactivate (false) silence detection for the specified call appearance. Parameter p2 is a pointer to a 4-byte value that indicates the duration of silence on the telephone line, in seconds, that qualifies as silence detection. Parameter p3 is unused. Your tool should return 0 if it completes successfully.