LINE_CALLSTATE

  • Article

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 lineGetCallStatus to retrieve more detailed information about the current status of the call.

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

Parameters

  • dwDevice
    Specifies a handle to the call.

  • dwCallbackInstance
    Specifies the callback instance supplied when opening the call's line.

  • dwParam1
    Specifies the new call state. It is only one of the following LINECALLSTATE_ values:

    Value Description
    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 over the call. Note that 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 and 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 multiparty conference call.
    LINECALLSTATE_ONHOLDPENDCONF The call is currently on hold while it is being added to a conference.
    LINECALLSTATE_ONHOLDPENTRANSFER 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.

  • dwParam2
    Specifies call-state-dependent information.

    If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses the following LINEBUSYMODE_ constants:

    Value Description
    LINEBUSYMODE_STATION The busy signal indicates that the called party's station is busy. This is usually signaled by means of a "normal" busy tone.
    LINEBUSYMODE_TRUNK The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.
    LINEBUSYMODE_UNKNOWN The busy signal's specific mode is currently unknown, but may become known later.
    LINEBUSYMODE_UNAVAIL The busy signal's specific mode is unavailable and cannot become known.

    If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:

    Value Description
    LINECONNECTEDMODE_ACTIVE Indicates that the call is connected at the current station (the current station is a participant in the call).
    LINECONNECTEDMODE_INACTIVE Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

    If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constants:

    Value Description
    LINEDIALTONEMODE_NORMAL This is a "normal" dial tone, which typically is a continuous tone.
    LINEDIALTONEMODE_SPECIAL This is a special dial tone indicating that a certain condition is currently in effect.
    LINEDIALTONEMODE_INTERNAL This is an internal dial tone, as within a PBX.
    LINEDIALTONEMODE_EXTERNAL This is an external (public network) dial tone.
    LINEDIALTONEMODE_UNKNOWN The dial tone mode is currently unknown, but may become known later.
    LINEDIALTONEMODE_UNAVAIL The dial tone mode is unavailable and cannot become known.

    If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:

    Value Description
    LINEOFFERINGMODE_ACTIVE Indicates that the call is alerting at the current station (is accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.
    LINEOFFERINGMODE_INACTIVE Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light).

    If dwParam1 is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the special information mode. This parameter uses the following LINESPECIALINFO_ constants:

    Value Description
    LINESPECIALINFO_NOCIRCUIT This special information tone precedes a "no circuit" or emergency announcement (trunk blockage category).
    LINESPECIALINFO_CUSTIRREG This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
    LINESPECIALINFO_REORDER This special information tone precedes a reorder announcement (equipment irregularity category).
    LINESPECIALINFO_UNKNOWN Specifics about the special information tone are currently unknown but may become known later.
    LINESPECIALINFO_UNAVAIL Specifics about the special information tone are unavailable and cannot become known.

    If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:

    Value Description
    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_NODIALTONE A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string).
    LINEDISCONNECTMODE_BADADDRESS The destination address in invalid.
    LINEDISCONNECTMODE_UNREACHABLE The remote user could not be reached.
    LINEDISCONNECTMODE_CONGESTION The network is congested.
    LINEDISCONNECTMODE_INCOMPATIBLE The remote user's station equipment is incompatible for the type of call requested.
    LINEDISCONNECTMODE_UNAVAIL The reason for the disconnect is unavailable and cannot become known later.

    Note   In circumstances where a delayed response is appropriate, use LINEDISCONNECTMODE_TEMPFAILURE. Where a blacklisted 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 lineDeallocateCall 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 the following LINECALLPRIVILEGE_ constants:

    Value Description
    LINECALLPRIVILEGE_MONITOR The application has monitor privilege.
    LINECALLPRIVILEGE_OWNER The application has owner privilege.

Return Values

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 (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 lineCompleteTransfer 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, call lineGetConfRelatedCalls)

This message cannot be disabled.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later Tapi.h    

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

lineCompleteTransfer, lineDeallocateCall, lineGenerateDigits, lineGetCallStatus, lineGetConfRelatedCalls, lineMakeCall, LINE_REPLY

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.