Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This message is sent to the LINEEVENTcallback 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_lineGetCallStatusto find out more detailed information about the current status of the call.

Syntax 

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 dwParam1is LINECALLSTATE_BUSY, the dwParam2parameter contains the details about the busy mode, and uses the LINEBUSYMODE_ constants.

If dwParam1is LINECALLSTATE_DIALTONE, the dwParam2parameter contains the details about the dial tone mode, and uses the LINEDIALTONEMODE_ constants.

If dwParam1is LINECALLSTATE_SPECIALINFO, the dwParam2parameter contains the details about the special info mode and uses the LINESPECIALINFO_ constants.

If dwParam1is LINECALLSTATE_DISCONNECTED, the dwParam2parameter contains the details about the disconnect mode, and uses the LINEDISCONNECTMODE_ constants.

If dwParam1is LINECALLSTATE_CONFERENCED, dwParam2contains the htCallof the parent call of the conference of which the subject htCallis a member. If the call specified in dwParam2was not previously considered by TAPI to be a parent conference call, this message causes it to be so treated. The call specified in dwParam2must already exist; it was most likely previously created by a LINE_NEWCALLmessage 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 dial tone 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 dwParam3parameter 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 htCallin 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

Header tapi.h
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also