PHONE_STATE (TAPI) (Compact 2013)

  • Article

3/26/2014

This message is sent by TAPI to an application whenever the status of a phone device changes.

Syntax

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

Parameters

  • hPhone
    Handle to the phone device.
  • dwCallbackInstance
    Application's callback instance provided when opening the phone device.
  • dwParam1
    Phone state that has changed. This parameter uses one of the PHONESTATE.

  • 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 the phoneGetStatus function 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
    Not used by this message. Value is NULL.

Return Value

None.

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 the phoneOpen function 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

Header

tapi.h

See Also

Reference

TAPI Messages
phoneClose
phoneGetStatus
phoneGetStatusMessages
phoneOpen
phoneSetStatusMessages
phoneShutdown