phoneSetStatusMessages
The phoneSetStatusMessages
function enables an application to monitor the specified phone device for
selected status events.
LONG phoneSetStatusMessages(
|
HPHONE hPhone, |
|
|
DWORD dwPhoneStates, |
|
|
DWORD dwButtonModes, |
|
|
DWORD dwButtonStates |
|
|
); |
|
Parameters
hPhone
A handle to
the open phone device to be monitored.
dwPhoneStates
These flags
specify the set of phone status changes and events for which the application
wishes to receive notification messages. This parameter can have zero, one, or
more bits set. This parameter uses the following PHONESTATE_ constants:
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 PC 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 PC 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
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. New phoneInitialize, phoneInitializeEx and phoneOpen requests are denied until
applications have shut down their usage of TAPI. The hDevice parameter
of the PHONE_STATE
message is left NULL for this state change, because it applies to any of the
lines in the system. Because of the critical nature of PHONESTATE_REINIT, such
messages cannot be masked, so the setting of this bit is ignored and the
messages are always delivered to the application.
PHONESTATE_CAPSCHANGE
Indicates
that, due to configuration changes made by the user or other circumstances, one
or more of the fields 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 will pass it along to applications which have negotiated TAPI
version 0x0001004 or above; applications negotiating a previous API version
will 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 will normally be immediately followed by a PHONE_CLOSE message on the device.
Subsequent attempts to access the device prior to TAPI being reinitialized will
result in PHONEERR_NODEVICE being returned to the application. If a service
provider sends a PHONE_STATE message containing this value to TAPI, TAPI will
pass it along to applications which have negotiated TAPI version 0x00010004 or
above; applications negotiating a previous API version will not receive any
notification.
dwButtonModes
The set of
phone-button modes for which the application wishes to receive notification
messages. This parameter can have zero, one, or more 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.
dwButtonStates
The set of
phone-button state changes for which the application wants to receive
notification messages. If the dwButtonModes parameter is 0, dwButtonStates
is ignored. If dwButtonModes has one or more bits set, this parameter
must also have at least one bit 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 at a future time.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
PHONEERR_INVALPHONEHANDLE,
PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE,
PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_UNINITIALIZED,
PHONEERR_OPERATIONUNAVAIL.
Remarks
An application
can use the phoneSetStatusMessages function to enable or disable the
generation of the corresponding messages. All phone status messages are
disabled by default.
See Also