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 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_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 fields 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). A
PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device.
Subsequent attempts to access the device prior to TAPI being reinitialized will
result in PHONEERR_NODEVICE being returned to the application. If a service
provider sends a PHONE_STATE message containing this value to TAPI, TAPI will
pass it along to applications which have negotiated TAPI version 0x00010004 or
higher; applications negotiating a previous API version will not receive any
notification.
dwParam2
Phone-state-dependent
information detailing the status change. This field is not used if multiple
flags are set in dwParam1, because multiple status items have changed.
The application should invoke phoneGetStatus1CGHX62 to obtain 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 ID 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.
See Also