This chapter contains a list of the messages in the Telephony API. Messages are used to notify the application of the occurrence of asynchronous events. They come in two flavors: messages sent to the callback in interrupt context or in application thread context. When an application uses lineInitialize or phoneInitialize, it specifies a callback function and whether it wants the callback to occur in interrupt context or in the application context.
The callback message always contains a handle to the relevant object (phone, line or call). The parameter profile for callbacks contains a handle parameter. A handle to the relevant object (phone, line or call) is passed using this multi-purpose handle parameter. The callback function can determine the type of the handle from the message that was passed to the callback.
For each message, this chapter lists the following items:
The purpose of the message
A description of the message parameters
Optional comments about using the message
Optional references to other functions, messages, and data structures
Certain messages are used to notify the application about a change in an object's status. These messages provide the object handle and an indication of which status item has changed. The application can call the "get status" function of the object to obtain the object's full status.
When an event occurs, messages or callbacks may be sent to zero, one or more applications. The target applications for a message are determined by a number of different factors. Factors are: the meaning of the message, the application's privilege to the object, whether or not the app initiated the request for which the message is a direct result, and message masking set by the application.
Asynchronous reply messages are only sent to the application that originated the request and cannot be masked.
Messages that signal the completion of digit or tone generation, or the gathering of digits are only sent to the application that requested the digit or tone generation.
Messages that indicate line or address state changes are sent to all apps that have opened the line.
Messages that indicate call state and call information changes are always sent to all applications that are owners for the call, and to monitoring apps that have not masked these messages.
Messages that signal a digit detection, tone detection or media mode detection are sent to all apps (owners or monitors) that have not masked the event.
The callback procedure profile for both the line and phone abstractions is as follows:
| Syntax | VOID FAR PASCAL CallbackFunc(hDevice, dwMsg, dwCallbackInstance, dwParam1, dwParam2, dwParam3) CallbackFunc is a placeholder for the application-supplied function name. |
| Parameters | DWORD dwDevice Specified a handle to either a line device, phone device, or a call associated with the callback. The nature of this handle (line handle, phone handle, or call handle) can be determined by the context provided by wMsg. DWORD dwMsg Specifies a line, call, or phone device message. DWORD dwCallbackInstance Specifies the user instance data specified at API initialization time. DWORD dwParam1 Specifies a parameter for the message. DWORD dwParam2 Specifies a parameter for the message. DWORD dwParam3 Specifies a parameter for the message. |
| Comments | The actual parameters passed to the application's callback function are described as the messages in this chapter. |
| All callbacks occur in the application's context. The callback function must reside in a dynamic link library (DLL) or application module and be exported in the module definition file. You must use MakeProcInstance to get a procedure-instance address for the callback function. |
LINE_ADDRESSSTATE
This message is sent to an application's callback when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.
| Parameters | DWORD dwDevice Specifies a handle to the line device. DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. DWORD dwParam1 Specifies the address ID of the address that changed status. DWORD dwParam2 Specifies the address state that changed, of type LINEADDRESSSTATE. Values are: LINEADDRESSSTATE_OTHER An status item or multiple items in the address' status not listed below have changed. The app should check the current address status to determine which items have changed. LINEADDRESSSTATE_DEVSPECIFIC The device specific item of the address status has changed. LINEADDRESSSTATE_INUSEZERO The address has changed to idle; i.e., it is now in use by zero stations. LINEADDRESSSTATE_INUSEONE The address has changed from being idle or from being in use by many bridged stations to being in use by just one station. LINEADDRESSSTATE_INUSEMANY The monitored or bridged address has changed to being in use by one station to being used by more than one station. LINEADDRESSSTATE_NUMCALLS The number of calls on the address has changed. This is the result of either a new inbound call, or an outbound call on the address, a call changing its hold status, etc. LINEADDRESSSTATE_FORWARD The forwarding status of the address has changed including the number of rings for determining a no answer condition. The app should check the address status to determine details about the address' current forwarding status. LINEADDRESSSTATE_TERMINALS The terminal settings for the address have changed. DWORD dwParam3 Unused. |
| Comments | This message is sent to any application that has opened the line device and that has enabled this message. The sending of this message for the various status items can be controlled and queried using lineGetStatusMessages and lineGetStatusMessages. By default, address status reporting is disabled. |
| See Also | Functions: lineGetAddressStatus, lineGetStatusMessages, lineSetStatusMessages |
| Data Types: LINEADDRESSSTATUS |
LINE_CALLINFO
This message is sent to an application's callback when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.
| Parameters | DWORD dwDevice Specifies a handle to the call. DWORD dwCallbackInstance Specifies the callback instance supplied when opening the call's line. DWORD dwParam1 Specifies the call information item that has changed, of type LINECALLINFOSTATE. Values are: LINECALLINFOSTATE_OTHER An other information item in the call information not listed below has changed. LINECALLINFOSTATE_DEVSPECIFIC The device specific field of the call information record. LINECALLINFOSTATE_BEARERMODE The bearer mode field of the call information record. LINECALLINFOSTATE_RATE The rate field of the call information record. LINECALLINFOSTATE_MEDIAMODE The media mode field of the call information record. LINECALLINFOSTATE_APPSPECIFIC The app specific field of the call information record. LINECALLINFOSTATE_CALLID The call ID field of the call information record. LINECALLINFOSTATE_RELATEDCALLID The related call ID field of the call information record. LINECALLINFOSTATE_ORIGIN The origin field of the call information record. LINECALLINFOSTATE_REASON The reason field of the call information record. LINECALLINFOSTATE_COMPLETIONID The completion ID field of the call information record. LINECALLINFOSTATE_NUMOWNERINCR The number of owner field in the call information record was increased. LINECALLINFOSTATE_NUMOWNERDECR The number of owner field in the call information record was decreased. LINECALLINFOSTATE_NUMMONITORS The number of monitors field in the call information record has changed. LINECALLINFOSTATE_TRUNK The trunk field of the call information record. LINECALLINFOSTATE_CALLERID One of the callerID-related fields of the call information record. LINECALLINFOSTATE_CALLEDID One of the calledID-related fields of the call information record. LINECALLINFOSTATE_CONNECTEDID One of the cconnectedID-related fields of the call information record. LINECALLINFOSTATE_REDIRECTIONID One of the redirectionID-related fields of the call information record. LINECALLINFOSTATE_REDIRECTINGID One of the redirectingID-related fields of the call information record. LINECALLINFOSTATE_DISPLAY The display field of the call information record. LINECALLINFOSTATE_USERUSERINFO The user-to-user information of the call information record. LINECALLINFOSTATE_HIGHLEVELCOMP The high level compatibility field of the call information record. LINECALLINFOSTATE_LOWLEVELCOMP The low level compatibility field of the call information record. LINECALLINFOSTATE_CHARGINGINFO The charging information of the call information record. LINECALLINFOSTATE_TERMINAL The terminal mode information of the call information record. LINECALLINFOSTATE_DIALPARAMS The dial parameters of the call information record. LINECALLINFOSTATE_MONITORMODES One or more of the digit, tone, or media monitoring fields in the call information record. DWORD dwParam2 Unused. DWORD dwParam3 Unused. |
| Comments | This message is sent to any application that has a valid handle for the call. |
| See Also | Functions: lineGetCallInfo |
| Data Types: LINECALLINFOSTATE |
LINE_CALLSTATE
This message is sent to an application's callback whenever the status of the specified call has changed. Several such messages will typically be received during the lifetime of a call. Applications are notified of new incoming calls via this message; the new call will be in the offering state. The app can use lineGetCallStatus to find out more detailed information about the current status of the call.
| Parameters | DWORD dwDevice Specifies a handle to the call. DWORD dwCallbackInstance Specifies the callback instance supplied when opening the call's line. DWORD dwParam1 Specifies the new call state, of type LINECALLSTATE. Values are: LINECALLSTATE_IDLE The call is idle - no call actually exists. LINECALLSTATE_OFFERING The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring, it does not affect any call states. LINECALLSTATE_ACCEPTED The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also indicates that alerting to both parties has started. LINECALLSTATE_DIALTONE The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number. LINECALLSTATE_DIALING Destination address information (a phone number) is being sent to the switch via the call. Note that the operation lineGenerateDigits does not place the line into the dialing state. LINECALLSTATE_RINGBACK The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted. LINECALLSTATE_BUSY The call is receiving a busy tone. Busy tone indicates that the call cannot be completed - either a circuit (trunk) or the remote party's station are in use. LINECALLSTATE_SPECIALINFO Special information is sent by the network. Special information is typically sent when the destination cannot be reached. LINECALLSTATE_CONNECTED The call has been established, the connection is made. Information is able to flow over the call between the originating address and the destination address. LINECALLSTATE_PROCEEDING Dialing has completed and the call is proceeding through the switch or telephone network. LINECALLSTATE_ONHOLD The call is on hold by the switch. LINECALLSTATE_CONFERENCED The call is currently a member of a multi-party conference call. LINECALLSTATE_ONHOLDPENDCONF The call is currently on hold while it is being added to a conference. LINECALLSTATE_ONHOLDPENDTRANSF The call is currently on hold awaiting transfer to another number. LINECALLSTATE_DISCONNECTED The remote party has disconnected from the call. LINECALLSTATE_UNKNOWN The state of the call is not known. This may be due to limitations of the call progress detection implementation. DWORD dwParam2 Specifies call state dependent information. If dwParam1 is LINECALLSTATE_BUSY, the dwParam2 contains the details about the busy mode, of type LINEBUSYMODE. Values are: LINEBUSYMODE_STATION The busy signal indicates that the called party's station is busy. This is usually signaled via a "normal" busy tone. LINEBUSYMODE_TRUNK The busy signal indicates that a trunk or circuit is busy. This is usually signaled via a "long" busy tone. LINEBUSYMODE_UNAVAIL The busy signal's specific mode is unavailable and will not become known. If dwParam1 is LINECALLSTATE_DIALTONE, the dwParam2 contains the details about the dialtone mode, of type LINEDIALTONEMODE. Values are: LINEDIALTONEMODE_NORMAL This is a "normal" dialtone which typically is a continuous tone. LINEDIALTONEMODE_SPECIAL This is a special dialtone indicating a certain condition is currently in effect. LINEDIALTONEMODE_INTERNAL This an internal (e.g., PBX) dialtone. LINEDIALTONEMODE_EXTERNAL This is an external (e.g., public network) dialtone. LINEDIALTONEMODE_UNKNOWN The dialtone mode is currently known, but may become known later. LINEDIALTONEMODE_UNAVAIL The dialtone mode is unavailable and will not become known. |
| If dwParam1 is LINECALLSTATE_SPECIALINFO, the dwParam2 contains the details about the special info mode, of type LINESPECIALINFO. Values are: | |
| LINESPECIALINFO_NOCIRCUIT This special information tone preceeds a no circuit or emergency announcement (trunk blockage category). LINESPECIALINFO_CUSTIRREG This special information tone preceeds a vacant number, AIS, Centrex number change and non-working station, access code not dialed or dialed in error, manual intercept operator message (customer irregularity category). LINESPECIALINFO_REORDER This special information tone preceeds a reorder announcement (equipment irregularity category). LINESPECIALINFO_UNKNOWN Specific about the special information tone are currently unknown but may become known later. LINESPECIALINFO_UNAVAIL Specifics about the special information tone are unavailable, and will not become known. | |
| If dwParam1 is LINECALLSTATE_DISCONNECTED, the dwParam2 contains the details about the disconnect mode, of type LINEDISCONNECTMODE. Values are: LINEDISCONNECTMODE_NORMAL This is a "normal" disconnect request by the remote party, the call was terminated normally. LINEDISCONNECTMODE_UNKNOWN The reason for the disconnect request is unknown. LINEDISCONNECTMODE_REJECT The remote user has rejected the call. LINEDISCONNECTMODE_PICKUP The call was picked up from elsewhere. LINEDISCONNECTMODE_FORWARDED The call was forwarded by the switch. LINEDISCONNECTMODE_BUSY The remote user's station is busy. LINEDISCONNECTMODE_NOANSWER The remote user's station does not answer. LINEDISCONNECTMODE_BADADDRESS The destination address in invalid. LINEDISCONNECTMODE_UNREACHABLE The remote user could not be reached. LINEDISCONNECTMODE_CONGESTION The network is congested. LINEDISCONNECTMODE_IMCOMPATIBLE The remote user's station equipment is incompatible for the type of call requested. LINEDISCONNECTMODE_UNAVAIL The remote user's station equipment is incompatible for the type of call requested. DWORD dwParam3 This parameter is non-zero and specifies the privilege the application has over the call in the following situations. (1) This is the first time that the app is given a handle to this call; (2) the app is the target of a call handoff (even if the app already was an owner of the call). In all other cases dwParam3 is specified as zero. If non-zero, this parameter is of type LINECALLPRIVILEGE. Values are: LINECALLPRIVILEGE_NONE The app has no privileges for the call. Its handle is void. LINECALLPRIVILEGE_MONITOR The app has monitor privileges. LINECALLPRIVILEGE_OWNER The app has owner privileges. | |
| Comments | This message is sent to any application that has a handle for the call. This message cannot be disabled. |
| See Also | Functions: lineGetCallStatus |
| Data Types: LINECALLSTATE, LINECALLSTATUS |
LINE_CLOSE
This message is sent to an application's callback when the specified line device has forcibly closed. The line device handle or any call handles for calls on the line are no longer valid once this message has been sent.
| Parameters | DWORD dwDevice Specifies a handle to the line device that was closed. This handle is no longer valid. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Unused. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is only sent to any application after a open line has been forcibly closed. This may be done to prevent a single application from monopolizing a line device for too long. Whether or not the line can be reopened immediately after a forced close is device specific. |
| See Also | None. |
LINE_DEVSPECIFIC
This message is sent to an application's callback to notify the application about device specific events occurring a line, address or call. The meaning of the message and the interpretation of the parameters is device specific.
| Parameters | DWORD dwDevice Specifies a handle to either a line device or call. This is device specific. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Device specific. | |
| DWORD dwParam2 Device specific. | |
| DWORD dwParam3 Device specific. | |
| Comments | This message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific |
| See Also | Functions: lineDevSpecific |
LINE_DEVSPECIFICFEATURE
This message is sent to an application's callback to notify the application about device specific events occurring a line, address or call. The meaning of the message and the interpretation of the parameters is device specific.
| Parameters | DWORD dwDevice Specifies a handle to either a line device or call. This is device specific. | |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | ||
| DWORD dwParam1 Device specific. | ||
| DWORD dwParam2 Device specific. | ||
| DWORD dwParam3 Device specific. | ||
| Comments | This message is used by a service provider in conjunction with the lineDevSpecificFeature function. Its meaning is device specific | |
| See AlsoFunctions: | lineDevSpecificFeature |
LINE_GATHERDIGITS
This message is sent to an application's window when the current buffered digit gathering request has terminated or is canceled. The digit buffer may be examined after this message has been received by the application.
| Parameters | DWORD dwDevice Specifies a handle to the call. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Specifies the reason why digit gathering was terminated, of type LINEGATHERTERM. Values are: | |
| LINEGATHERTERM_BUFFERFULL The requested number of digits has been gathered. The buffer is full. | |
| LINEGATHERTERM_TERMDIGIT One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer. | |
| LINEGATHERTERM_FIRSTTIMEOUT The first digit timeout expired. The buffer contains no digits. | |
| LINEGATHERTERM_INTERTIMEOUT The inter digit timeout expired. The buffer contains at least one digit. | |
| LINEGATHERTERM_CANCEL The request was canceled by this application, by another application, or because the call terminated. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is only sent to the application that initiated the digit gathering on the call using lineGatherDigits. |
| See Also | Functions: lineGatherDigits |
LINE_GENERATE
This message is sent to an application's callback to notify the application that the current digit or tone generation has terminated. Note that only one such generation request can be in progress an a given call at any time. This message is also sent when digit or tone generation is canceled.
| Parameters | DWORD dwDevice Specifies a handle to the call. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Specifies the reason why digit or tone generation was terminated, of type LINEGENERATETERM. Values are: | |
| LINEGENERATETERM_DONE The requested number of digits have been generated, or the requested tones have been generated for the requested duration. | |
| LINEGENERATETERM_CANCEL The digit or tone generation request was canceled by this application, by another application, or because the call terminated. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is only sent to the application that requested the digit or tone generation. |
| See Also | Functions: lineGenerateDigits, lineGenerateTone |
LINE_LINEDEVSTATE
This message is sent to an application's window when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.
| Parameters | DWORD dwDevice Specifies a handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Specifies the line device status item that has changed, of type LINEDEVSTATE. Values are: | |
| LINEDEVSTATE_OTHER An other status item than those listed below has changed. | |
| LINEDEVSTATE_RINGING The switch tells the line to alert the user. | |
| LINEDEVSTATE_CONNECTED The line was previously disconnected and is now connected to the API. | |
| LINEDEVSTATE_DISCONNECTED This line was previously connected and is now disconnected from the API. | |
| LINEDEVSTATE_MSGWAITON The message waiting indicator is turned on. | |
| LINEDEVSTATE_MSGWAITOFF The message waiting indicator is turned off. | |
| LINEDEVSTATE_INSERVICE The line is connected to the API. This happens when the API is first activated, or when the line wire is physically plugged in and in service at the switch while the API is active. | |
| LINEDEVSTATE_OUTOFSERVICE The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device. | |
| LINEDEVSTATE_MAINTENANCE Mainatenance is being performed on the line at the switch. The API cannot be used to operate on the line device. | |
| LINEDEVSTATE_OPEN The line has been opened. | |
| LINEDEVSTATE_CLOSE The line has been closed. | |
| LINEDEVSTATE_NUMCALLS The number of calls on the line device has changed. | |
| LINEDEVSTATE_TERMINALS The terminal settings have changed. | |
| LINEDEVSTATE_ROAMING The roaming state of the line device has changed. | |
| LINEDEVSTATE_BATTERY The battery level has changed significantly (cellular). | |
| LINEDEVSTATE_SIGNAL The signal level has changed significantly (cellular). | |
| LINEDEVSTATE_DEVSPECIFIC The line's device specific information has changed. | |
| LINEDEVSTATE_REINIT Items have changed in the configuration of line devices. To become aware of these changes (e.g., new line devices) the app should reinitialize its use of the API. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system. | |
| LINEDEVSTATE_LOCK The locked status of the line device has changed. | |
| DWORD dwParam2 The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING then dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability. | |
| DWORD dwParam3 The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING then dwParam3 contains the ring count for this ring event. Ring count starts at zero. | |
| Comments | The sending of this message can be controlled via lineSetStatusMessages. An application can indicate which status item changes it wants to be notified about. By default all status reporting will be disabled. |
| See Also | Functions: lineGetLineDevStatus, lineSetStatusMessages, lineGetStatusMessages |
| Data Types: LINEDEVSTATUS |
LINE_MONITORDIGITS
This message is sent to an application's callback whenever a digit is detected. The sending of this message is controlled via the lineMonitorDigits function.
| Parameters | DWORD dwDevice Specifies a handle to the call. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the call's line. | |
| DWORD dwParam1 The low order byte contains the last digit received in ASCII. | |
| DWORD dwParam2 Specifies the digit mode that was detected, of type LINEDIGITMODE. Values are: | |
| LINEDIGITMODE_PULSE Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'. | |
| LINEDIGITMODE_DTMF Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. | |
| LINEDIGITMODE_DTMFEND Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is sent to the application that has enabled digit monitoring. |
| See Also | Functions: lineMonitorDigits |
LINE_MONITORMEDIA
This message is sent to an application's callback whenever a change in the call's media mode is detected. The sending of this message is controlled via the lineMonitorMedia function.
| Parameters | DWORD dwDevice Specifies a handle to the call. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the line. | |
| DWORD dwParam1 Specifies the new media mode, of type LINEMEDIAMODE. Values are: | |
| LINEMEDIAMODE_NONE No media stream. This value is mainly used as a NULL value. | |
| LINEMEDIAMODE_UNKNOWN A media stream exists but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call has been answered and the media stream filtered to make a determination. | |
| LINEMEDIAMODE_INTERACTIVEVOICE The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends. | |
| LINEMEDIAMODE_DIGITALDATA Digital data being sent or received over the call. | |
| LINEMEDIAMODE_G3FAX A group 3 fax is being sent or received over the call. | |
| LINEMEDIAMODE_G4FAX A group 4 fax is being sent or received over the call. | |
| LINEMEDIAMODE_DATAMODEM A data modem session on the call. | |
| LINEMEDIAMODE_TELETEX A teletex session on the call. Teletex is one of the telematic services. | |
| LINEMEDIAMODE_VIDEOTEX A videotex session on the call. Videotex is one the telematic services. | |
| LINEMEDIAMODE_TELEX A telex session on the call. Telex is one the telematic services. | |
| LINEMEDIAMODE_MIXED A mixed session on the call. Mixed is one the telematic services. | |
| LINEMEDIAMODE_TDD A TDD session on the call. TDD stands for Telephony Devices for the Deaf. | |
| LINEMEDIAMODE_ADSI An ADSI session on the call. ADSI stands for Analog Display Services Interface. | |
| LINEMEDIAMODE_UNAVAIL The media mode of the call is unavailable and will not be known.. | |
| DWORD dwParam2 Unused | |
| DWORD dwParam3 Unused. | |
| Comments | This message is sent to the application that has enabled media monitoring for the media mode detected. |
| See Also | Functions: lineMonitorMedia |
| Data Types: LINEMEDIAMODE |
LINE_MONITORTONE
This message is sent to an application's callback whenever a tone is detected. The sending of this message is controlled via the lineMonitorTone function.
| Parameters | DWORD dwDevice Specifies a handle to the call. |
| DWORD dwCallbackInstance Specifies the callback instance supplied when opening the call's line. | |
| DWORD dwParam1 Specifies the app specific field dwAppSpecific of the LINEMONITORTONE structure for the tone that was detected. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is only sent to the application that has requested the tone be monitored. |
| See Also | Functions: lineMonitorTones |
| Data Types: LINEMONITORTONE |
LINE_REPLY
This message is sent to an application's callback to report the results of function call that completed asynchronously.
| Parameters | DWORD dwDevice Not used. |
| DWORD dwCallbackInstance Not used. | |
| DWORD dwParam1 Specifies the request ID for which this is the reply. | |
| DWORD dwParam2 Specifies the success or error indication. The application should cast this parameter into a LONG. Zero indicates success, a negative number indicates an error. | |
| DWORD dwParam3 Unused. | |
| Comments | Functions that operate asynchronously return a positive request ID value to the application. This request ID is returned with the reply message to identify the request that was completed. The other parameter for this message carries the success of failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled. |
| See Also | Data Types: LINEERR |
LINE_REQUEST
This message is sent to an application's callback to report the arrival of a new request from another application.
| Parameters | DWORD dwDevice Not used. |
| DWORD dwCallbackInstance Specifies the registration instance of the application specified on lineRegisterRequestRecipient. | |
| DWORD dwParam1 Specifies the request mode of the newly pending request, of type LINEREQUESTMODE. Values are: | |
| LINEREQUESTMODE_MAKECALL A tapiRequestMakeCall request. | |
| LINEREQUESTMODE_MEDIACALL A tapiRequestMediaCall request. | |
| LINEREQUESTMODE_DROP A tapiRequestDrop request. | |
| LINEREQUESTMODE_LOGENTRY A lineRequestLogEntry request. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is sent to the highest priority application that has registered for the corresponding request mode. This callback message indicates the arrival of a message of the specified request mode. The application can invoke lineGetRequest using the corresponding request mode to receive the request. |
| See Also | Functions: lineRegisterRequestRecipient, lineGetRequest, |
| tapiRequestMakeCall, tapiRequestMediaCall, tapiRequestDrop, | |
| tapiRequestLogEntry | |
| Data Types: LINEREQUESTMODE |
The implementation sends this message to an application's callback to notify the application that it has detected a button press on the local phone, provided button press monitoring is enabled.
| Parameters | HPHONE hPhone Specifies a handle to the phone device. |
| DWORD dwCallbackInstance Specifies the application's callback instance provided when opening the phone device. | |
| DWORD dwParam1 Specifies the button/lamp ID of the button that was pressed. Note that button IDs 0 through 11 are always the KEYPAD buttons. '0' being button ID 0, '1' being button ID 1, etc., through button ID 9. '*' being button ID 10, and '#' being button ID 11. Additional information about a button ID is available via phoneGetDevCaps, and phoneGetButtonInfo. | |
| DWORD dwParam2 Specifies the button mode of the button, of type PHONEBUTTONMODE. Values are: | |
| PHONEBUTTONMODE_CALL The button is assigned to a call appearance. | |
| PHONEBUTTONMODE_FEATURE The button is assigned to requesting features from the switch, such as hold, conference, transfer, etc. | |
| PHONEBUTTONMODE_KEYPAD The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'. | |
| PHONEBUTTONMODE_LOCAL The button is a local function button, such as mute or volume control. | |
| PHONEBUTTONMODE_DISPLAY The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons. | |
| DWORD dwParam3 Specifies whether this is a button down event or a button up event, of type PHONEBUTTONSTATE. Values are: | |
| PHONEBUTTONSTATE_UP The button is in the "up" state. | |
| PHONEBUTTONSTATE_DOWN The button is in the "down" state (i.e., pressed down). | |
| Comments | None. |
| See Also | Data Types: PHONESTATUS, PHONEBUTTONMODE, PHONEBUTTONSTATE, PHONEBUTTONFUNCTION |
The implementation sends this message to an application's callback when an open phone device has been forcibly closed as part of resource reclamation. The device handle is no longer valid once this message has been sent.
| Parameters | HPHONE hPhone Specifies a handle to the open phone device that was closed. The handle is no longer valid after this message has been sent |
| DWORD dwCallbackInstance Specifies the application's callback instance provided when opening the phone device. | |
| DWORD dwParam1 Unused. | |
| DWORD dwParam2 Unused. | |
| DWORD dwParam3 Unused. | |
| Comments | This message is only sent to any application after a open phone has been forcibly closed. This may be done to prevent a single application from monopolizing a phone device for too long. Whether or not the phone can be reopened immediately after a forced close is device specific. |
| See Also | Functions: phoneClose |
The implementation sends this message to an application's callback to notify the application about device specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation-defined.
| Parameters | HPHONE hPhone Specifies a handle to the phone device. |
| DWORD dwCallbackInstance Specifies the application's callback instance provided when opening the phone device. | |
| DWORD dwParam1 Device specific. | |
| DWORD dwParam2 Device specific. | |
| DWORD dwParam3 Device specific. | |
| Comments | None. |
| See Also | Functions: phoneDevSpecific |
This message is sent to an application's callback to report the results of function call that completed asynchronously.
| Parameters | HANDLE hDevice Unused. DWORD dwCallbackInstance Unused. DWORD dwParam1 Specifies the request ID for which this is the reply. DWORD dwParam2 Specifies the success or error indication. The application should cast this parameter into a LONG. Zero indicates success, a negative number indicates an error. DWORD dwParam3 Unused. |
| Comments | Functions that operate asynchronously return a positive request ID value to the application. This request ID is returned with the reply message to identify the request that was completed. The other parameter for this message carries the success of failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled. |
| See Also | Data Types: PHONEERR |
The implementation sends this message to an application's callback whenever a phone device's status changes.
| Parameters | HPHONE hPhone Specifies a handle to the phone device. |
| DWORD dwCallbackInstance Specifies the application's callback instance provided when opening the phone device. | |
| DWORD dwParam1 Specifies the phone state that has changed, of type PHONESTATE. Values are: PHONESTATE_OTHER An other phone status information item not listed below has changed. PHONESTATE_CONNECTED The connection between the phone device and the API was just made. This happens when the API is first invoked, or when the wire connection the phone to the PC is plugged in with the API active. PHONESTATE_DISCONNECTED The connection between the phone device and the API was just broken. This happens when the wire connecting the phone set to the PC is unplugged while the API is active. PHONESTATE_OWNER The number of owners for the phone device has changed. PHONESTATE_MONITORS The number of monitors for the phone device has changed. PHONESTATE_DISPLAY The display of the phone has changed. PHONESTATE_LAMP A lamp of the phone has changed. PHONESTATE_RINGMODE The ring mode of the phone has changed. PHONESTATE_RINGVOLUME The ring volume of the phone has changed. PHONESTATE_HANDSETHOOKSWITCH The handset hookswitch state has changed. PHONESTATE_HANDSETVOLUME The handset's speaker volume setting has changed. PHONESTATE_HANDSETGAIN The handset's mic gain setting has changed. PHONESTATE_SPEAKERHOOKSWITCH The speakerphone's hookswitch state has changed. PHONESTATE_SPEAKERVOLUME The speakerphone's speaker volume setting has changed. PHONESTATE_SPEAKERGAIN The speakerphone's mic gain setting state has changed. PHONESTATE_HEADSETHOOKSWITCH The headset's hookswitch state has changed. PHONESTATE_HEADSETVOLUME The headset's speaker volume setting has changed. PHONESTATE_HEADSETGAIN The headset's mic gain setting has changed. PHONESTATE_SUSPEND The app's use of the phone is temporarily suspended. PHONESTATE_RESUME The app's use of the phone device is resumed after having been suspended for some time. PHONESTATE_DEVSPECIFIC The phone's device specific information has changed. DWORD dwParam2 Specifies phone state dependent information detailing the status change. This field is not used if multiple flags are set in dwParam1, since multiple status items have changed. The app should invoke phoneGetStatus to obtain complete set of information. | |
| If dwParam1 is PHONESTATE_OWNER, then dwParam2 contains the new number of owners. | |
| If dwParam1 is PHONESTATE_MONITORS, then dwParam2 contains the new number of monitors. | |
| If dwParam1 is PHONESTATE_LAMP, then dwParam2 contains the button/lamp ID of the lamp that has changed. | |
| If dwParam1 is PHONESTATE_RING, then dwParam2 contains the new ring mode. | |
| If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, then dwParam2 contains the new hookswitch mode of that hookswitch device, of type PHONEHOOKSWITCHMODE. Values are: | |
| PHONEHOOKSWITCHMODE_ONHOOK The device's mic and speaker are both onhook. PHONEHOOKSWITCHMODE_MIC The devicer's mic is active, the speaker is mute. PHONEHOOKSWITCHMODE_SPEAKER The device's speaker is active, the mic is mute. PHONEHOOKSWITCHMODE_MICSPEAKER The device's mic and speaker are both active. DWORD dwParam3 Unused. | |
| Comments | The sending of this message to one's callback can be controlled and queried using phoneSetStatusMessages and phoneGetStatusMessages. By default, this message is disabled for all state changes. |
| See Also | Functions: phoneGetStatus, phoneGetStatusMessages, |
| phoneSetStatusMessages | |
| Data Types: PHONESTATE |