PHONESTATUS
The PHONESTATUS
structure describes the current status of a phone device.
typedef struct phonestatus_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;
DWORD dwStatusFlags;
DWORD dwNumOwners;
DWORD dwNumMonitors;
DWORD dwRingMode;
DWORD dwRingVolume;
DWORD dwHandsetHookSwitchMode;
DWORD dwHandsetVolume;
DWORD dwHandsetGain;
DWORD dwSpeakerHookSwitchMode;
DWORD dwSpeakerVolume;
DWORD dwSpeakerGain;
DWORD dwHeadsetHookSwitchMode;
DWORD dwHeadsetVolume;
DWORD dwHeadsetGain;
DWORD dwDisplaySize;
DWORD dwDisplayOffset;
DWORD dwLampModesSize;
DWORD dwLampModesOffset;
DWORD dwOwnerNameSize;
DWORD dwOwnerNameOffset;
DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;
DWORD
dwPhoneFeatures;
} PHONESTATUS, FAR *LPPHONESTATUS;
Members
dwTotalSize
The total
size in bytes allocated to this data structure.
dwNeededSize
The size in
bytes for this data structure that is needed to hold all the returned
information.
dwUsedSize
The size in
bytes of the portion of this data structure that contains useful information.
dwStatusFlags
This field
provides a set of status flags for this phone device. This parameter uses the
following PHONESTATUSFLAGS_ constants:
PHONESTATUSFLAGS_CONNECTED
Specifies whether
the phone is currently connected to TAPI. TRUE if connected; FALSE otherwise.
PHONESTATUSFLAGS_SUSPENDED
Specifies
whether TAPI's manipulation of the phone device is suspended. TRUE if
suspended; FALSE otherwise. An application's use of a phone device may be
temporarily suspended when the switch wants to manipulate the phone in a way
that cannot tolerate interference from the application.
dwNumOwners
The number of
application modules with owner privilege for the phone.
dwNumMonitors
The number of
application modules with monitor privilege for the phone.
dwRingMode
The current
ring mode of a phone device.
dwRingVolume
The current
ring volume of a phone device. This is a value between 0x00000000 (silence) and
0x0000FFFF (maximum volume).
dwHandsetHookSwitchMode
The current
hookswitch mode of the phone's handset. 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.
dwHandsetVolume
The current
speaker volume of the phone's handset device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetGain
The current
microphone gain of the phone's handset device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwSpeakerHookSwitchMode
The current
hookswitch mode of the phone's speakerphone. 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.
dwSpeakerVolume
The current
speaker volume of the phone's speaker device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwSpeakerGain
The current
microphone gain of the phone's speaker device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwHeadsetHookSwitchMode
The current
hookswitch mode of the phone's headset. 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.
dwHeadsetVolume
The current
speaker volume of the phone's headset device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHeadsetGain
The current
microphone gain of the phone's headset device. This is a value between
0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwDisplaySize
dwDisplayOffset
The size in
bytes of the variably sized field containing the phone's current display
information, and the offset in bytes, from the beginning of this data
structure.
dwLampModesSize
dwLampModesOffset
The size in
bytes of the variably sized field containing the phone's current lamp modes,
and the offset in bytes from the beginning of this data structure.
dwOwnerNameSize
dwOwnerNameOffset
The size in
bytes of the variably sized field containing the name of the application that
is the current owner of the phone device, and the offset in bytes from the
beginning of this data structure. The name is the application name provided by
the application when it invoked with phoneInitialize or phoneInitializeEx . If no application name
was supplied, the application's file name is used instead. If the phone
currently has no owner, dwOwnerNameSize is zero.
dwDevSpecificSize
dwDevSpecificOffset
The size in
bytes of the variably sized device-specific field, and the offset in bytes from
the beginning of this data structure
dwPhoneFeatures
These flags
indicate which Telephony API functions can be invoked on the phone, considering
the availability of the feature in the device capabilities, the current device
state, and device ownership of the invoking application. A zero indicates the
corresponding feature cannot be invoked by the application on the phone in its
current state; a one indicates the feature can be invoked. This field uses
PHONEFEATURE_ constants.
Remarks
Device-specific
extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset)
variably sized area of this data structure.
The dwPhoneFeatures
member is available only to applications that open the phone device with an API
version of 0x00020000 or greater.
See Also