Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This 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.

Syntax 

LONG TSPIAPI TSPI_lineSetStatusMessages(
  HDRVLINE 
hdLine, 
  DWORD 
dwLineStates,
  DWORD 
dwAddressStates 
);

Parameters

hdLine

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

dwLineStates

Bit array that identifies for which line device status changes a message is to be sent to TAPI. This parameter uses one of the LINEDEVSTATEconstants.

dwAddressStates

Bit array that identifies for which address status changes a message is to be sent to TAPI. This parameter uses one of the LINEADDRESSSTATEconstants.

Return Value

Returns zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this method.

Value Description

LINEERR_INVALADDRESSSTATE

The address state is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALLINEHANDLE

The line handle is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALLINESTATE

The line state is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_NOMEM

Not enough memory is available.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the dwLineStatesparameter 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:

  • The set of messages requested is the union of all sets requested by applications at the TAPI level.

  • The message set is neither reduced nor augmented by ownership because there is no concept of ownership at the TSPI level.

  • 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.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later