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 fields 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, may 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 fields in the LINETRANSLATECAPS5PWH.X structure have changed. The application
should use lineGetTranslateCaps to read the updated structure.
LINEDEVSTATE_COMPLCANCEL
Indicates
that the call completion identified by the completion ID 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). A
LINE_LINEDEVSTATE message with this value will normally be immediately followed
by a LINE_CLOSE
message on the device. Subsequent attempts to access the device prior to TAPI
being reinitialized will result in LINEERR_NODEVICE being returned to the
application. If a service provider sends a LINE_LINEDEVSTATE message containing
this value to TAPI, TAPI will pass it along to applications which have
negotiated TAPI version 0x00010004 or above; applications negotiating a
previous API version will 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 ID, 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 will be 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.
See Also