lineSetStatusMessages
The lineSetStatusMessages
enables an application to specify which notification messages the application
wants to receive for events related to status changes for the specified line or
any of its addresses.
LONG lineSetStatusMessages(
|
HLINE hLine, |
|
|
DWORD dwLineStates, |
|
|
DWORD dwAddressStates |
|
|
); |
|
Parameters
hLine
A handle to
the line device.
dwLineStates
A bit array
that identifies for which line-device status changes a message is to be sent to
the application. This parameter uses 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 LINE_LINEDEVSTATE 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_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 some application.
LINEDEVSTATE_CLOSE
The line has
been closed by some application.
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 roam mode
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. New lineInitialize, lineInitializeEx and lineOpen requests are denied until
applications have shut down their usage of TAPI. The hDevice parameter
of the LINE_LINEDEVSTATE
message is left NULL for this state change as it applies to any of the lines in
the system. Because of the critical nature of LINEDEVSTATE_REINIT, such
messages cannot be masked, so the setting of this bit is ignored and the
messages are always delivered to the application.
LINEDEVSTATE_LOCK
The locked
status of the line device has changed.
LINEDEVSTATE_REMOVED
Indicates
that the device is being removed from the system by the service provider (most
likely through user action, via 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 API TAPI version 0x00010004 or above; applications negotiating a
previous API version will not receive any notification.
dwAddressStates
A bit array
that identifies for which address status changes a message is to be sent to the
application. This parameter uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address-status
items other than those listed below have changed. The application should check
the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The
device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address
has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address
has changed from idle or from being in use by many bridged stations to being in
use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored
or bridged address has changed from being in use by one station to being used
by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of
calls on the address has changed. This is the result of events such as a new
inbound call, an outbound call on the address, or a call changing its hold
status.
LINEADDRESSSTATE_FORWARD
The
forwarding status of the address has changed (including the number of rings for
determining a no-answer condition). The application should check the address
status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal
settings for the address have changed.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
LINEERR_INVALADDRESSSTATE,
LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE,
LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL.
Remarks
TAPI defines
a number of messages that notify applications about events occurring on lines
and addresses. An application may not be interested in receiving all address
and line status change messages. The lineSetStatusMessages function can
be used to select which messages the application wants to receive. By default,
address and line status reporting is disabled.
See Also