LINE_CALLSTATE (TAPI)

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This message is sent when 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 with this message; the new call will be in the offering state. The application can use the lineGetCallStatus function to retrieve more detailed information about the current status of the call.

Syntax

LINE_CALLSTATE 
    dwDevice = (DWORD) hCall;
    dwCallbackInstance = (DWORD) hCallback; 
    dwParam1 = (DWORD) CallState; 
    dwParam2 = (DWORD) CallStateDetail; 
    dwParam3 = (DWORD) CallPrivilege;

Parameters

  • dwDevice
    Handle to the call.
  • dwCallbackInstance
    Callback instance supplied when opening the call's line.
  • dwParam1
    Value that specifies the new call state. It is only one of the LINECALLSTATE.

  • dwParam2
    Value that specifies call-state-dependent information.

    If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses LINEBUSYMODE.

    If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses LINECONNECTEDMODE.

    If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses one of the LINEDIALTONEMODE.

    If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses LINEOFFERINGMODE.

    If dwParam1 is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the special information mode. This parameter uses LINESPECIALINFO.

    If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses LINEDISCONNECTMODE.

    Note

    In circumstances where a delayed response is appropriate, use LINEDISCONNECTMODE_TEMPFAILURE. Where a blocked response is appropriate, use LINEDISCONNECT_BLOCKED.

    If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall parameter of the parent call of the conference of which the subject hCall is a member. If the call specified in dwParam2 was not previously considered by the application to be a parent conference call (hConfCall), the application must do so as a result of this message. If the application does not have a handle to the parent call of the conference (because it has previously called the lineDeallocateCall function on that handle) dwParam2 is set to NULL.

  • dwParam3
    If zero, this parameter specifies that there has been no change in the application's privilege for the call.

    If nonzero, it specifies the application's privilege to the call. This occurs in the following situations: (1) The first time that the application is given a handle to this call; (2) When the application is the target of a call handoff (even if the application already was an owner of the call). This parameter uses LINECALLPRIVILEGE_ constants. The following table shows the values the parameter can take.

    Value Description

    LINECALLPRIVILEGE_MONITOR

    The application has monitor privilege.

    LINECALLPRIVILEGE_OWNER

    The application has owner privilege.

Return Value

None.

Remarks

This message is sent to any application that has a handle for the call. The LINE_CALLSTATE message also notifies applications that monitor calls on a line about the existence and state of outbound calls established by other applications 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, the application can determine whether the call is an inbound call that needs to be answered or not.

A LINE_CALLSTATE message with an unknown call state can be sent to a monitoring application as the result of a successful lineMakeCall function that has been requested by another application. At the same time that the requesting application is sent a LINE_REPLY message (success) for the requested operation, any monitoring applications on the line are sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE message indicating the real call state of the newly generated call is sent (using information provided by the service provider) to the requesting and monitoring applications shortly thereafter.

A LINE_CALLSTATE (unknown) message is sent to monitoring applications only if the lineCompleteTransfer function causes calls to be resolved into a three-way conference.

For backward compatibility, older applications are not expecting any particular value in dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI therefore passes the parent call hConfCall in dwParam2 regardless of the API version of the application receiving the message. In the case of a conference call initiated by the service provider, the older application is not aware that the parent call has become a conference call unless it happens to spontaneously examine other information, for example, if it calls lineGetConfRelatedCalls)

This message cannot be disabled.

Requirements

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

See Also

Reference

lineCompleteTransfer
lineDeallocateCall
lineGenerateDigits
lineGetCallStatus
lineGetConfRelatedCalls
lineMakeCall
LINE_REPLY