LINE_LINEDEVSTATE

The LINE_LINEDEVSTATE message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceState;
dwParam2 = (DWORD) DeviceStateDetail1;
dwParam3 = (DWORD) DeviceStateDetail2;

Parameters

dwDevice

A handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.

dwCallbackInstance

The callback instance supplied when opening the line. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.

dwParam1

The line device status item that has changed. The parameter can be a combination of the following LINEDEVSTATE_ constants:

LINEDEVSTATE_OTHER: Device status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING: The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED: The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED: This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON: The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF: The "message waiting" indicator is turned off.
LINEDEVSTATE_NUMCOMPLETIONS: The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_INSERVICE: The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE: The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE: Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN: The line has been opened by another application.
LINEDEVSTATE_CLOSE: The line has been closed by another application.
LINEDEVSTATE_NUMCALLS: The number of calls 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. To become aware of these changes (as with the appearance of new line devices), the application should reinitialize its use of TAPI. The dwDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK: The locked status of the line device has changed. (For more information, refer to the description of the LINEDEVSTATUSFLAGS_LOCKED bit of the LINEDEVSTATUSFLAGS_ constants.)
LINEDEVSTATE_CAPSCHANGE: Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure.
LINEDEVSTATE_CONFIGCHANGE: Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, can use lineGetDevConfig to read the updated information.
LINEDEVSTATE_TRANSLATECHANGE: Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure.
LINEDEVSTATE_COMPLCANCEL: Indicates that the call completion identified by the completion identifier contained in parameter dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled 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).
LINEDEVSTATE_REMOVED: Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; 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.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.

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.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).

Return Values

No return value.

Remarks

The sending of the LINE_LINEDEVSTATE message can be controlled with lineSetStatusMessages. An application can indicate status item changes about which it wants to be notified. By default, all status reporting is disabled except for LINEDEVSTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the line, including those that called lineOpen with the dwPrivileges parameter set to LINECALLPRIVILEGE_NONE, LINECALLPRIVILEGE_OWNER, LINECALLPRIVILEGE_MONITOR, or permitted combinations of these.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

LINE_LINEDEVSTATE

Parameters

Return Values

Remarks

QuickInfo

See Also