lineGetStatusMessages

The lineGetStatusMessages function enables an application to query which notification messages the application is set up to receive for events related to status changes for the specified line or any of its addresses.

LONG lineGetStatusMessages(
  HLINE hLine,             
  LPDWORD lpdwLineStates,  
  LPDWORD lpdwAddressStates  
);

Parameters

hLine

A handle to the line device.

lpdwLineStates

A bit array that identifies for which line device status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, it is disabled. Note that multiple flags can be set. 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_NUMCOMPLETIONS: The number of outstanding call completions on the line device has changed.
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_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 (for example, the appearance of new line devices) the application should reinitialize its use 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.
LINEDEVSTATE_LOCK: The locked status of the line device has changed.
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). 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 does not receive any notification.

lpdwAddressStates

A bit array that identifies for which address status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, disabled. Multiple flags can be set. 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 being 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 incoming call, an outgoing 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 succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

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 status and line status reporting is disabled.

QuickInfo

  Version: Use TAPI version 1.4 and later.
  Header: Declared in tapi.h.
  Import Library: Link with tapi32.lib.

lineGetStatusMessages

Parameters

Return Values

Remarks

QuickInfo

See Also