4.1.1.21 PHONE_STATE

This message is sent to the TAPI DLL whenever a phone device's status changes.

Sent to

PHONEEVENT

Parameters

HTAPIPHONE htPhone
Specifies the TAPI DLL's opaque object handle to the phone device.

DWORD dwMsg
The value PHONE_STATE

DWORD dwParam1
Specifies the phone state that has changed, of type PHONESTATE. Values are:

PHONESTATE_OTHER
An other phone status information item not listed below has changed.

PHONESTATE_CONNECTED
The connection between the phone device and the API was just made. This happens when the API is first invoked, or when the wire connection the phone to the PC is plugged in with the API active.

PHONESTATE_DISCONNECTED
The connection between the phone device and the API was just broken. This happens when the wire connecting the phone set to the PC is unplugged while the API 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 app's use of the phone is temporarily suspended.

PHONESTATE_RESUME
The app'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 dwParam2
Specifies phone state dependent information detailing the status change. This field is not used if multiple flags are set in dwParam1, since multiple status items have changed. The TAPI DLL should invoke TSPI_phoneGetStatus to obtain complete set of information.

If dwParam1 is PHONESTATE_LAMP, then dwParam2 contains the button/lamp ID of the lamp that has changed.

If dwParam1 is PHONESTATE_RING, then dwParam2 contains the new ring mode.

If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, then dwParam2 contains the new hookswitch mode of that hookswitch device, of type PHONEHOOKSWITCHMODE. Values are:

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.

DWORD dwParam3
Unused.

Comments

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

Comparison

The Service Provider never reports changed values for PHONESTATE_OWNER or PHONESTATE_MONITOR, since the notion of privilege does not appear at the TSPI level.

See Also

Functions: TSPI_phoneGetStatus, TSPI_phoneSetStatusMessages
Data Types: PHONESTATE