PHONE_STATE

TAPI sends the PHONE_STATE message to an application whenever the status of a phone device changes.

PHONE_STATE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateDetails;
dwParam3 = (DWORD) 0;

Parameters

hPhone

A handle to the phone device.

dwCallbackInstance

The application's callback instance provided when opening the phone device.

dwParam1

The phone state that has changed. 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 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 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 device 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.
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). Normally, a PHONE_STATE message with this value is 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 API version do not receive any notification.

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. The application should invoke phoneGetStatus to obtain a complete set of information.

If dwParam1 is PHONESTATE_OWNER, dwParam2 contains the new number of owners.

If dwParam1 is PHONESTATE_MONITORS, dwParam2 contains the new number of monitors.

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_HANDSET, SPEAKER or HEADSET, dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

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

dwParam3

Unused.

Return Values

No return value.

Remarks

Sending the PHONE_STATE message to the application can be controlled and queried using phoneSetStatusMessages and phoneGetStatusMessages. By default, this message is disabled for all state changes except for PHONESTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the phone, including those that called phoneOpen with the dwPrivileges parameter set to PHONEPRIVILEGE_OWNER or PHONEPRIVILEGE_MONITOR.

A PHONE_STATE message with an Owners and/or Monitors indication is sent to applications that already have a handle for the phone. This can be the result of another application changing ownership or monitorship of the phone device with phoneOpen, phoneClose or phoneShutdown.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

PHONE_STATE

Parameters

Return Values

Remarks

QuickInfo

See Also