LINE_CALLSTATE message
The TSPI LINE_CALLSTATE message is sent to the LINEEVENT callback function whenever the status of the specified call has changed. Several such messages are typically sent during the lifetime of a call. The first such message for an incoming call indicates the offering state. TAPI can use TSPI_lineGetCallStatus to find out more detailed information about the current status of the call.
LINE_CALLSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLSTATE;
dwParam1 = (DWORD) LineCallState;
dwParam2 = (DWORD) StateData;
dwParam3 = (DWORD) MediaMode;
Parameters
htLine
The TAPI opaque object handle to the line device.htCall
The TAPI opaque object handle to the call device.dwMsg
The value LINE_CALLSTATE.dwParam1
The new call state. This parameter is one of the LINECALLSTATE_ constants.dwParam2
Specifies call-state-dependent information.If dwParam1 is LINECALLSTATE_BUSY, the dwParam2 parameter contains the details about the busy mode, and uses the LINEBUSYMODE_ constants.
If dwParam1 is LINECALLSTATE_DIALTONE, the dwParam2 parameter contains the details about the dial tone mode, and uses the LINEDIALTONEMODE_ constants.
If dwParam1 is LINECALLSTATE_SPECIALINFO, the dwParam2 parameter contains the details about the special info mode and uses the LINESPECIALINFO_ constants.
If dwParam1 is LINECALLSTATE_DISCONNECTED, the dwParam2 parameter contains the details about the disconnect mode, and uses the LINEDISCONNECTMODE_ constants.
If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the htCall of the parent call of the conference of which the subject htCall is a member. If the call specified in dwParam2 was not previously considered by TAPI to be a parent conference call, this message causes it to be so treated. The call specified in dwParam2 must already exist; it was most likely previously created by a LINE_NEWCALL message and set to LINECALLSTATE_ONHOLDPENDCONF.
dwParam3
The media type of the call, as far as it is known. This is a combination of one or more LINEMEDIAMODE_ constants. If the service provider does not know the media type, it should include the "UNKNOWN" bit with all media types currently being monitored for.
Remarks
The LINE_CALLSTATE message (with LINECALLSTATE_OFFERING) should be sent as the next message for an incoming call after LINE_NEWCALL. Other call state changes are reported whenever they occur; the message cannot be disabled.
The LINE_CALLSTATE message also notifies TAPI about the existence and state of outbound calls established as a side effect of other calls (for example, when an active call is put on hold and replaced by a new call in the dialtone state) or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, TAPI can determine whether the call is an inbound call that needs to be answered.
The corresponding message at the TAPI level is used to inform applications of new incoming calls. This is not the case at the TSPI level; the LINE_NEWCALL message informs TAPI of new incoming calls. The LINE_NEWCALL message must precede this message.
The dwParam3 parameter is used at the TAPI level to inform the recipient of the privilege level it has over the call.
For backward compatibility, older service providers do not pass a valid htCall in dwParam2. TAPI must check the value passed, and ignore it if it is not a valid htCall. If the value is a valid htCall, TAPI also checks the API version in use on the line device, and establishes a conference call internally only if the API version is 1.4 or later (for example, if the API version on the line is later than 1.4, this parameter should be ignored).
Requirements
TAPI version |
Requires TAPI 2.0 or later |
Header |
Tapi.h |