TSPI_phoneSetStatusMessages

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function causes the service provider to filter status messages that are not currently of interest to any application.

Syntax

LONG TSPIAPI TSPI_phoneSetStatusMessages(
  HDRVPHONE hdPhone, 
  DWORD dwPhoneStates,  
  DWORD dwButtonModes,  
  DWORD dwButtonStates 
);

Parameters

hdPhone
Opaque handle to the phone whose state-change monitoring filter is to be set.

dwPhoneStates
Flags that specify the set of phone status changes and events for which TAPI wants to receive notification messages. This parameter can have zero, one, or more than one of the PHONESTATE constants.

dwButtonModes
Flags that specify the set of phone button modes for which TAPI wants to receive notification messages. If dwButtonModes is zero, dwButtonStates is ignored. This parameter can have zero, one, or more than one of the PHONEBUTTONMODE constants. If dwButtonModes has at least one of these flags set, dwButtonStates must also have at least one bit set:

dwButtonStates
This parameter specifies the set of phone button state changes for which TAPI wishes to receive notification messages, one of the PHONEBUTTONSTATE constants.

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
PHONEERR_INVALPHONEHANDLE	The handle to the phone is invalid.
PHONEERR_NOMEM	Not enough memory is available.
PHONEERR_INVALPHONESTATE	The phone state is invalid.
PHONEERR_RESOURCEUNAVAIL	The resource is unavailable.
PHONEERR_INVALBUTTONMODE	The button mode is invalid.
PHONEERR_OPERATIONFAILED	The operation failed.
PHONEERR_INVALBUTTONSTATE	The button state is invalid.
PHONEERR_OPERATIONUNAVAIL	The operation is unavailable.

Remarks

TAPI defines a number of messages that notify applications about events occurring on phones. 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. All phone status messages except PHONESTATE_REINIT are disabled by default.

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

Share via