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).

See Also

LINEDEVSTATUS, LINEEVENT, TSPI_lineGetLineDevStatus, TSPI_lineSetStatusMessages