PHONE_STATE

The PHONE_STATE message is sent to the PHONEEVENT callback function to TAPI whenever a phone device's status changes.

PHONE_STATE
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_STATE;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateData;
dwParam3 = (DWORD) 0;

Parameters

htPhone

The TAPI opaque object handle to the phone device.

dwMsg

The value PHONE_STATE.

dwParam1

The phone state that has changed. This parameter uses the following PHONESTATE_ constants:

PHONESTATE_OTHER: A phone status information item other than those listed below has 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 with TAPI 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_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 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. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.
PHONESTATE_CAPSCHANGE: Due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

dwParam2

Phone-state dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have changed. TAPI should invoke TSPI_phoneGetStatus to obtain a complete set of information. If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that has changed. If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode. If dwParam1 is PHONESTATE_HANDSETHOOKSWITCH, PHONESTATE_SPEAKERHOOKSWITCH or PHONESTATE_HEADSETHOOKSWITCH, dwParam2 contains the new hookswitch mode of that hookswitch device, which can be set to any of the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK: The device's mic and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC: The device's mic is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER: The device's speaker is active, the mic is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER: The device's mic and speaker are both active.

dwParam3

Unused.

Remarks

The sending of this message is controlled by TSPI_phoneSetStatusMessages. By default, this message is disabled for all state changes.

The service provider never reports changed values for PHONESTATE_OWNER or PHONESTATE_MONITORS, because the notion of privilege does not appear at the TSPI level.

For backward compatibility, older service providers are not expected to generate this value in a PHONE_STATE message. If they do, the message is handled in the same manner as for newer service providers (as described earlier).

PHONE_STATE

Parameters

Remarks

See Also