LINE_LINEDEVSTATE

The LINE_LINEDEVSTATE message is sent to the LINEEVENT callback function when the state of a line device has changed. TAPI can invoke TSPI_lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_LINEDEVSTATE;
dwParam1 = (DWORD) LineDevState;
dwParam2 = (DWORD) DevStateData1;
dwParam3 = (DWORD) DevStateData2;

Parameters

htLine

The TAPI opaque object handle to the line device.

htCall

Unused.

dwMsg

The value LINE_LINEDEVSTATE.

Specifies the callback instance supplied when opening the line.

dwParam1

Specifies the line device status item that has changed. This parameter can have multiple flags set and uses the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER: Device-status items other than those listed below have changed.
LINEDEVSTATE_RINGING: The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
LINEDEVSTATE_CONNECTED: The line was previously disconnected and is now connected to the API.
LINEDEVSTATE_DISCONNECTED: This line was previously connected and is now disconnected from the API.
LINEDEVSTATE_MSGWAITON: The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF: The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE: The line is connected to the API. This happens when the API is first activated, or when the line wire is physically plugged in and in service at the switch while the API is active.
LINEDEVSTATE_OUTOFSERVICE: The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE: Maintenance is being performed on the line at the switch. The API cannot be used to operate on the line device.
LINEDEVSTATE_NUMCALLS: The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS: The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS: The terminal settings have changed.
LINEDEVSTATE_ROAMMODE: The roaming state of the line device has changed.
LINEDEVSTATE_BATTERY: The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL: The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC: The line's device-specific information has changed.
LINEDEVSTATE_REINIT: Items have changed in the configuration of line devices. Except in extreme cases, the service provider should use the normal configuration change notification mechanism as described in the Overviews section instead of this message. Note that when dwParam1 is LINEDEVSTATE_REINIT, htLine is unused, and should be set to NULL.
LINEDEVSTATE_LOCK: The locked status of the line device has changed.
LINEDEVSTATE_CAPSCHANGE: Due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEDEVCAPS structure for the address have changed. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a subsequent API version; applications negotiating an earlier API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
LINEDEVSTATE_CONFIGCHANGE: Indicates that configuration changes have been made to one or more of the media devices associated with the line device. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version do not receive any notification.
LINEDEVSTATE_COMPLCANCEL: The call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally cancelled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version do not receive any notification.
LINEDEVSTATE_REMOVED: The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a subsequent API version; applications negotiating a previous API version do not receive any notification.

dwParam2

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.

dwParam3

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

Remarks

The sending of this message can be controlled through TSPI_lineSetStatusMessages. The service provider must send LINE_LINEDEVSTATE messages for at least the set of status changes selected through that procedure. The service provider can send more than this set, however, it should try to limit its messages to this set for performance reasons. By default all status reporting is disabled.

At the TSPI level, the service provider does not report state changes when the line is opened and closed, since there is only ever one Open outstanding for the device.

For backward compatibility, older service providers would not be expected to generate these values. If they do, TAPI treats them the same as if the service provider were using API version 1.4 or later (as described earlier).

LINE_LINEDEVSTATE

Parameters

Remarks

See Also