lineSetStatusMessages

This function 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
  [in] Handle to the line device.

• dwLineStates
  [in] Specifies for which line-device status changes a message is to be sent to the application. This parameter uses the following LINEDEVSTATE_ constants:

  Value	Description
  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 that contains 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 data 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 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, 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 that contains this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.

• dwAddressStates
  [in] Specifies for which address status changes a message is to be sent to the application. This parameter uses the following LINEADDRESSSTATE_ constants:

  Value	Description
  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 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

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

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 receives. By default, address and line status reporting is disabled.

Prior to Windows CE version 2.12, LINEDEVSTATE_ messages are not supported.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

lineInitialize, lineOpen, LINE_CLOSE, LINE_LINEDEVSTATE,

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.