LINE_CALLSTATE

The 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 can be one of the following LINECALLSTATE_ constants:

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. Note that in ISDN, the transition to the accepted state implicitly initiates altering to both parties.
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 through the call. Note that the operation TSPI_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 multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF: The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER: 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 can be due to limitations of the call progress detection implementation.

dwParam2

Specifies call-state-dependent information.

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

LINEBUSYMODE_STATION: The busy signal indicates that the called party's station is busy. This is usually signaled with 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 can become known later.
LINEBUSYMODE_UNAVAIL: The busy signal's specific mode is unavailable and cannot become known.

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

LINEDIALTONEMODE_NORMAL: This is a "normal" dial tone that typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL: This is a special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL: This 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 can become known later.
LINEDIALTONEMODE_UNAVAIL: The dial tone mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_SPECIALINFO, the dwParam2 parameter contains the details about the special info mode and uses the following LINESPECIALINFO_ constants:

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 can become known later.
LINESPECIALINFO_UNAVAIL: Specifics about the special information tone are unavailable, and cannot become known.

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

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_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.
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). This can also occur without a service provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

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 mode of the call, as far as it is known. This is a combination of LINEMEDIAMODE_ constants. If the service provider does not know the media mode, it should include the "UNKNOWN" bit together with all media modes 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).

LINE_CALLSTATE

Parameters

Remarks

See Also