phoneGetStatusMessages

The phoneGetStatusMessages function returns which phone-state changes on the specified phone device generate a callback to the application.

LONG phoneGetStatusMessages(
  HPHONE hPhone,            
  LPDWORD lpdwPhoneStates,  
  LPDWORD lpdwButtonModes,  
  LPDWORD lpdwButtonStates  
);
 

Parameters

hPhone
A handle to the open phone device to be monitored.
lpdwPhoneStates
A pointer to a PHONESTATE_ constant. These flags specify the set of phone status changes and events for which the application can receive notification messages. The lpdwPhoneStates parameter can return a value with zero, one, or multiple bits set. Monitoring can be individually enabled and disabled for:
PHONESTATE_OTHER
Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in while TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
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
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application'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. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, as it applies to any of the phones in the system.
PHONESTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.
PHONESTATE_REMOVED
Indicates that 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 PHONE_STATE message with this value is normally immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.
lpdwButtonModes
A pointer to flags that specify the set of phone-button modes for which the application can receive notification messages. The lpdwButtonModes parameter can return a value with zero, one, or multiple bits set. This parameter uses the following PHONEBUTTONMODE_ constants:
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, and 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.
lpdwButtonStates
A pointer to a DWORD-sized location that contains flags specifying the set of phone button state changes for which the application can receive notification messages. The lpdwButtonStates parameter can return a value with zero, one, or multiple bits set. This parameter uses the following PHONEBUTTONSTATE_ constants:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time.
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and will not become known.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.

Remarks

An application can use phoneGetStatusMessages to query the generation of the corresponding messages. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are disabled by default.

QuickInfo

  Version: Use TAPI version 1.4 and later.
  Header: Declared in tapi.h.
  Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneSetStatusMessages