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 one of the PHONESTATE_ constants.

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 one of the PHONEHOOKSWITCHMODE_ constants.

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.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 2.0 or later.
  Header: Declared in Tapi.h.

See Also

PHONE_CLOSE, PHONECAPS, phoneClose, phoneGetDevCaps, phoneGetStatus, phoneGetStatusMessages, phoneInitialize, phoneInitializeEx, phoneOpen, phoneSetStatusMessages, phoneShutdown