| Syntax | LONG TSPI_phoneSetStatusMessages(dwRequestID, hdPhone, dwPhoneStates, dwButtonModes, dwButtonStates) |
| This operation enables the TAPI DLL to monitor the specified phone device for selected status events. | |
| Parameters | DRV_REQUESTID dwRequestID Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously. |
| HDRVPHONE hdPhone Specifies the Service Provider's opaque handle to the phone whose state-change monitoring filter is to be set. | |
| DWORD dwPhoneStates These flags specify the set of phone status changes and events for which the TAPI DLL wishes to receive notification messages, of type PHONESTATE. Values are: | |
| PHONESTATE_OTHER A non-specified phone status information item 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 PC 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 PC 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 hookswitch state has changed. | |
| PHONESTATE_HANDSETVOLUME The handset's speaker volume setting has changed. | |
| PHONESTATE_HANDSETGAIN The handset's mic 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 mic 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 mic gain setting has changed. | |
| PHONESTATE_SUSPEND The TAPI DLL's use of the phone is temporarily suspended. | |
| PHONESTATE_RESUME The TAPI DLL'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. | |
| DWORD dwButtonModes These flags specify the set of phone button modes for which the TAPI DLL wishes to receive notification messages, of type PHONEBUTTONMODE. Values are: | |
| 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, transfer, etc. | |
| 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. | |
| DWORD dwButtonStates These flags specify the set of phone button state changes for which the TAPI DLL wishes to receive notification messages, of type PHONEBUTTONSTATE. Values are: | |
| PHONEBUTTONSTATE_UP The button is in the "up" state. | |
| PHONEBUTTONSTATE_DOWN The button is in the "down" state (i.e., pressed down). | |
| Return Value | Returns zero if the function is successful, the (positive) dwRequestID value if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are: |
| PHONEERR_INVALPHONEHANDLE The specified line device handle is invalid. | |
| PHONEERR_INVALPHONESTATE The specified phone states parameter is invalid. | |
| PHONEERR_INVALBUTTONMODE The button mode parameter is invalid. | |
| PHONEERR_INVALBUTTONSTATE The button states parameter is invalid. | |
| PHONEERR_OPERATIONUNAVAIL The specified operation is not available. | |
| PHONEERR_OPERATIONFAILED The specified operation failed for unspecified reasons. | |
| Comments | The TAPI defines a number of messages that notify applications about events occurring on phones. The sets of all change messages that all applications are interested may be much smaller than the set of possible messages. This procedure allows the TAPI DLL to tell the Service Provider the reduced set of messages that should be delivered. The Service Provider must deliver at least this set. It is permitted to deliver more, but it is discouraged from doing so for performance reasons. All phone status messages are disabled by default. |
| Comparison | 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 (since 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. |
| The Service Provider never reports state changes related to the number of outstanding Opens because there is only ever one Open at the TSPI level, and there are no distinct privelege levels. | |
| See Also | Functions: TSPI_phoneGetStatusMessages Messages: PHONE_STATE, PHONE_BUTTON Data Types: PHONESTATE |