PHONECAPS
The PHONECAPS
structure describes the capabilities of a phone device.
typedef struct phonecaps_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;
DWORD dwProviderInfoSize;
DWORD dwProviderInfoOffset;
DWORD dwPhoneInfoSize;
DWORD dwPhoneInfoOffset;
DWORD dwPermanentPhoneID;
DWORD dwPhoneNameSize;
DWORD dwPhoneNameOffset;
DWORD
dwStringFormat;
DWORD dwPhoneStates;
DWORD dwHookSwitchDevs;
DWORD dwHandsetHookSwitchModes;
DWORD dwSpeakerHookSwitchModes;
DWORD dwHeadsetHookSwitchModes;
DWORD dwVolumeFlags;
DWORD dwGainFlags;
DWORD dwDisplayNumRows;
DWORD dwDisplayNumColumns;
DWORD dwNumRingModes;
DWORD
dwNumButtonLamps;
DWORD dwButtonModesSize;
DWORD dwButtonModesOffset;
DWORD dwButtonFunctionsSize;
DWORD dwButtonFunctionsOffset;
DWORD dwLampModesSize;
DWORD dwLampModesOffset;
DWORD dwNumSetData;
DWORD dwSetDataSize;
DWORD dwSetDataOffset;
DWORD dwNumGetData
DWORD dwGetDataSize;
DWORD dwGetDataOffset;
DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;
DWORD
dwDeviceClassesSize;
DWORD
dwDeviceClassesOffset;
DWORD
dwPhoneFeatures;
DWORD
dwSettableHandsetHookSwitchModes;
DWORD
dwSettableSpeakerHookSwitchModes;
DWORD
dwSettableHeadsetHookSwitchModes;
DWORD
dwMonitoredHandsetHookSwitchModes;
DWORD
dwMonitoredSpeakerHookSwitchModes;
DWORD
dwMonitoredHeadsetHookSwitchModes;
} PHONECAPS, FAR *LPPHONECAPS;
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.
dwProviderInfoSize
dwProviderInfoOffset
The size in
bytes of the variably sized field containing service provider-specific
information, and the offset in bytes from the beginning of this data structure.
The dwProviderInfoSize/Offset
field is intended to provide information about the provider hardware and/or software,
such as the vendor name and version numbers of hardware and software. This
information can be useful when a user needs to call customer service with
problems regarding the provider.
dwPhoneInfoSize
dwPhoneInfoOffset
The size in
bytes of the variably sized device field containing phone-specific information,
and the offset in bytes from the beginning of this data structure.
The dwPhoneInfoSize/Offset
field is intended to provide information about the attached phone device, such
as the phone device manufacturer, the model name, the software version, and so
on. This information can be useful when a user needs to call customer service
with problems regarding the phone.
dwPermanentPhoneID
The permanent
DWORD identifier by which the phone device is known in the system's configuration.
dwPhoneNameSize
dwPhoneNameOffset
The size in
bytes of the variably sized device field containing a user configurable name
for this phone device, and the offset in bytes from the beginning of this data
structure This name can be configured by the user when configuring the phone
device's service provider and is provided for the user's convenience.
dwStringFormat
The string
format to be used with this phone device. This parameter uses the following
STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
ASCII string
format using one byte per character.
STRINGFORMAT_DBCS
DBCS string
format using two bytes per character.
STRINGFORMAT_UNICODE
Unicode
string format using two bytes per character.
dwPhoneStates
The state
changes for this phone device for which the application can be notified in a PHONE_STATE message. 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 PC 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 PC 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 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 for the appearance of new phone devices) the application should
reinitialize its use of TAPI.
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_CLOSEFH4LO3 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 above;
applications negotiating a previous API version will not receive any
notification.
dwHookSwitchDevs
This field
specifies the phone's hookswitch devices. This parameter uses the following
PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
This is the
ubiquitous, handheld, ear- and mouthpiece.
PHONEHOOKSWITCHDEV_SPEAKER
A built-in
loudspeaker and microphone. This could also be an externally connected adjunct
to the telephone set.
PHONEHOOKSWITCHDEV_HEADSET
This is a
headset connected to the phone set.
dwHandsetHookSwitchModes
dwSpeakerHookSwitchModes
dwHeadsetHookSwitchModes
This field
specifies the phone's hookswitch mode capabilities of the handset, speaker, or
headset, respectively. The field is only meaningful if the hookswitch device is
listed in dwHookSwitchDevs. 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.
dwVolumeFlags
This field
specifies the volume setting capabilities of the phone device's speaker
components. If the bit in position PHONEHOOKSWITCHDEV_ is TRUE, the volume of
the corresponding hookswitch device's speaker component can be adjusted with phoneSetVolume; otherwise FALSE.
dwGainFlags
This field
specifies the gain setting capabilities of the phone device's microphone
components. If the bit position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the
corresponding hookswitch device's microphone component can be adjusted with phoneSetGain; otherwise FALSE.
dwDisplayNumRows
This field
specifies the display capabilities of the phone device by describing the number
of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns
fields are both zero for a phone device without a display.
dwDisplayNumColumns
This field
specifies the display capabilities of the phone device by describing the number
of columns in the phone display. dwDisplayNumRows and dwDisplayNumColumns
are both zero for a phone device without a display.
dwNumRingModes
The ring
capabilities of the phone device. The phone is able to ring with dwNumRingModes
different ring patterns, identified as 1, 2, through dwNumRingModes
minus one. If the value of this field is zero, applications have no control
over the ring mode of the phone. If the value of this field is greater than
zero, it indicates the number of ring modes in addition to silence that are
supported by the service provider. A value of 0 in the lpdwRingMode
parameter of phoneGetRing
or the dwRingMode parameter of phoneSetRing indicates silence (the
phone is not ringing or should not be rung), and dwRingMode values of 1
to dwNumRingModes are valid ring modes for the phone device.
dwNumButtonLamps
This field
specifies the number of button/lamps on the phone device that are detectable in
TAPI. Button/lamps are identified by their ID. Valid button/lamp IDs range from
zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9',
'*', and '#' are assigned the IDs 0 through 12.
dwButtonModesSize
dwButtonModesOffset
The size in
bytes and the offset from the beginning of this data structure in bytes of the
variably sized field containing the button modes of the phone's buttons. The
array is indexed by button/lamp ID. This parameter uses the following
PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_DUMMY
This value is
used to describe a button/lamp position that has no corresponding button, but
has only a lamp. If the phone provides any non-DUMMY buttons, the PHONE_BUTTON message will be sent to the
application if a button is pressed at the phone device.
PHONEBUTTONMODE_CALL
The button is
assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is
assigned to requesting features from the switch, such as hold, conference, and
transfer.
PHONEBUTTONMODE_KEYPAD
The button is
one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is
a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is
a "soft" button associated with the phone's display. A phone set can
have zero or more display buttons.
dwButtonFunctionsSize
dwButtonFunctionsOffset
The size in
bytes of the variably sized field containing the button modes of the phone's
buttons, and the offset in bytes from the beginning of this data structure.
This field uses the values specified by the PHONEBUTTONFUNCTION_ constants. The
array is indexed by button/lamp ID.
dwLampModesSize
dwLampModesOffset
The size in
bytes of the variably sized field containing the lamp modes of the phone's
lamps, and the offset in bytes from the beginning of this data structure. The
array is indexed by button/lamp ID. This parameter uses the following PHONELAMPMODE_
constants:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter
is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means
slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means
fast on and off.
PHONELAMPMODE_OFF
The lamp is
off.
PHONELAMPMODE_STEADY
The lamp is
continuously lit.
PHONELAMPMODE_WINK
The lamp is
winking.
PHONELAMPMODE_DUMMY
This value is
used to describe a button/lamp position that has no corresponding lamp.
dwNumSetData
The number of
different download areas in the phone device. The different areas are referred
to using the data IDs 0, 1, , dwNumSetData minus one. If this field is
zero, the phone does not support the download capability.
dwSetDataSize
dwSetDataOffset
The size in
bytes of the variably sized field containing the sizes (in bytes) of the
phone's download data areas, and the offset in bytes from the beginning of this
data structure. This is an array with DWORD-sized elements indexed by data ID.
dwNumGetData
The number of
different upload areas in the phone device. The different areas are referred to
using the data IDs 0, 1, , dwNumGetData minus one. If this field is
zero, the phone does not support the upload capability.
dwGetDataSize
dwGetDataOffset
The size in
bytes of the variably sized field containing the sizes (in bytes) of the
phone's upload data areas, and the offset in bytes from the beginning of this
data structure. This is an array with DWORD-sized elements indexed by data ID.
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
dwDeviceClassesSize
dwDeviceClassesOffset
Length in
bytes and offset from the beginning of PHONECAPS of a string consisting of the
device class identifiers supported on this device for use with phoneGetID, separated by nulls; the
last identifier in the list is followed by two nulls.
dwPhoneFeatures
These flags
indicate which Telephony API functions can be invoked on the phone. A zero indicates
the corresponding feature is not implemented and can never be invoked by the
application on the phone; a one indicates the feature may be invoked depending
on the device state and other factors. This field uses PHONEFEATURE_ constants.
dwSettableHandsetHookSwitchModes
The
PHONEHOOKSWITCHMODE_ values which can be set on the handset using phoneSetHookSwitch.
dwSettableSpeakerHookSwitchModes
The PHONEHOOKSWITCHMODE_
values which can be set on the speakerphone using phoneSetHookSwitch.
dwSettableHeadsetHookSwitchModes
The
PHONEHOOKSWITCHMODE_ values which can be set on the headset using phoneSetHookSwitch.
dwMonitoredHandsetHookSwitchModes
The PHONEHOOKSWITCHMODE_
values which can be detected and reported for the handset in a
PHONE_STATE message and by phoneGetHookSwitch1KB2.GS.
dwMonitoredSpeakerHookSwitchModes
The
PHONEHOOKSWITCHMODE_ values which can be detected and reported
for the speakerphone in a PHONE_STATE message and by phoneGetHookSwitch.
dwMonitoredHeadsetHookSwitchModes
The
PHONEHOOKSWITCHMODE_ values which can be detected and reported
for the headset in a PHONE_STATE message and by phoneGetHookSwitch.
Remarks
Device-specific
extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset)
variably sized area of this data structure.
The members dwDeviceClassesSize
through dwMonitoredHeadsetHookSwitchModes are available only to
applications that open the phone device with an API version of 0x00020000 or
greater.
See Also