TSPI_lineSetStatusMessages

The TSPI_lineSetStatusMessages function enables TAPI to specify which notification messages the service provider should generate for events related to status changes for the specified line or any of its addresses.

LONG TSPI_lineSetStatusMessages(
  HDRVLINE hdLine,    
  DWORD dwLineStates  
);
 

Parameters

hdLine

The handle to the line device for which the new filter is to be set.

dwLineStates

A bit array that identifies for which line device status changes a message is to be sent to TAPI. This parameter uses the following LINEDEVSTATE_. constants:

LINEDEVSTATE_OTHER

Device-status items other than those listed below have changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to the service provider.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from the service provider.

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 the service provider. This happens when the service provider is first activated, or when the line wire is physically plugged in and in service at the switch while the service provider is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or is physically disconnected. The API cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. The service provider cannot be used to operate on the line device.

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 roaming 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) TAPI notifies all its client applications to reinitialize their use of the API. A service provider should initiate such a sequence only in extreme cases that cannot be handled through the normal configuration-change notification mechanism described in the Overview section. The LINEDEVSTATE_REINIT message is never masked. REINIT messages should always be sent when appropriate, regardless of the setting of this flag. The setting of the REINIT flag is simply ignored and generates no error.

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). A LINE_LINEDEVSTATE message with this value is normally 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 this or a subsequent API version; applications negotiating a previous API version do not receive any notification.

DWORD dwAddressStates

A bit array that identifies for which address status changes a message is to be sent to TAPI. This parameter uses the following LINEADDRESSSTATE_ constants:

LINEADDRESSSTATE_OTHER

Address-status items other than those listed below 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 to 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, as a result of an event 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. TAPI checks 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 function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants.

Win32 Telephony defines a number of messages that notify applications about events occurring on lines and addresses. The sets of all change messages in which all applications are interested can be much smaller than the set of possible messages. This procedure allows TAPI to tell the service provider the reduced set of messages to deliver. The service provider delivers all of the messages it supports, within the specified set. It is permitted to deliver more (they are filtered out by TAPI), but is discouraged from doing so for performance reasons. If TAPI requests delivery of a particular message type that is not produced by the provider, the provider nevertheless accepts the request but simply does not produce the message. By default, address and line status reporting is initially disabled for a line.

This function differs from the corresponding TAPI function as follows: (1) The set of messages requested is the union of all sets requested by applications at the TAPI level. (2) The message set is neither reduced nor augmented by ownership (because there is no concept of ownership at the TSPI level) (3) The set is advisory in the sense that the service provider is required to forward at least the indicated set of messages but is permitted to forward a larger set.

Device state changes regarding Open and Close are not reported, because at the TSPI level there is only one outstanding Open at a time.

See Also

LINE_ADDRESSSTATE, LINE_CLOSE, LINE_LINEDEVSTATE, LINEADDRESSSTATE_ Constants, LINEDEVSTATE_ Constants