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

PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneInitialize, phoneInitializeEx, phoneOpen

Software for developers

Delphi Components
.Net Components
Software for Android Developers

More information resources

MegaDetailed.Net
Unix Manual Pages
Delphi Examples

Databases for Amazon shops developers

Amazon Categories Database
Browse Nodes Database