TSPI_phoneSetStatusMessages

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

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

Parameters

hdPhone

The 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 following PHONESTATE_ bits set:

PHONESTATE_OTHER: A phone status information item other than those listed below has changed.
PHONESTATE_CONNECTED: The connection between the phone device and the service provider was just made. This happens when the API is first invoked, or when the wire connecting the phone to the computer is plugged in with the API active.
PHONESTATE_DISCONNECTED: The connection between the phone device and the service provider was just broken. This happens when the wire connecting the phone set to the computer is unplugged while the service provider is active.
PHONESTATE_DISPLAY: The display of the phone has changed.
PHONESTATE_LAMP: A lamp of the phone has changed.
PHONESTATE_RINGMODE: The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME: The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH: The handset's hookswitch state has changed.
PHONESTATE_HANDSETVOLUME: The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN: The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH: The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME: The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN: The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH: The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME: The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN: The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND: TAPI's use of the phone is temporarily suspended. This can occur when the switch requires exclusive use of the phone device.
PHONESTATE_RESUME: TAPI's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC: The phone's device-specific information has changed.
PHONESTATE_REINIT: Items have changed in the configuration of phone devices. To become aware of these changes, (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.
The PHONESTATE_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.

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 following PHONEBUTTONMODE_ bits set. If dwButtonModes has at least one of these flags set, dwButtonStates must also have at least one bit set:

PHONEBUTTONMODE_CALL: The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE: The button is assigned to requesting features from the switch, such as hold, conference, or transfer.
PHONEBUTTONMODE_KEYPAD: The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL: The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY: The button is a soft button associated with the phone's display. A phone set can have zero or more display buttons.

dwButtonStates

This parameter specifies the set of phone button state changes for which TAPI wishes to receive notification messages. Values are:

PHONEBUTTONSTATE_UP: The button is in the up state.
PHONEBUTTONSTATE_DOWN: The button is in the down state (pressed down).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_OPERATIONUNAVAIL.

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.

TSPI_phoneSetStatusMessages

Parameters

Return Values

Remarks

See Also