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 member provides 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 member provides 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 member uses the following STRINGFORMAT_ constants:

STRINGFORMAT_ASCII: ASCII string format using one byte per character.
STRINGFORMAT_DBCS: DBCS string format using one or 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 member 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 while TAPI is 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's 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 members 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). Normally, a PHONE_STATE message with this value is immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.

dwHookSwitchDevs

Specifies the phone's hookswitch devices. This member uses the following PHONEHOOKSWITCHDEV_ constants:

PHONEHOOKSWITCHDEV_HANDSET: 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: A headset connected to the phone set.

dwHandsetHookSwitchModes

dwSpeakerHookSwitchModes

dwHeadsetHookSwitchModes

Specifies the phone's hookswitch mode capabilities of the handset, speaker, or headset, respectively. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. This member 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

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

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

Specifies the display capabilities of the phone device by describing the number of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.

dwDisplayNumColumns

Specifies the display capabilities of the phone device by describing the number of columns in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members 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 member is 0, applications have no control over the ring mode of the phone. If the value of this member is greater than 0, 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

Specifies the number of button/lamps on the phone device that are detectable in TAPI. Button/lamps are identified by their identifier. Valid button/lamp identifiers range from zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9', '*', and '#' are assigned the identifiers 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 identifier. This member 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 is 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 member uses the values specified by the PHONEBUTTONFUNCTION_ constants. The array is indexed by button/lamp identifier.

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 identifier. This member 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 member 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 identifier.

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 identifier.

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 member uses PHONEFEATURE_ constants.

dwSettableHandsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that can be set on the handset using phoneSetHookSwitch.

dwSettableSpeakerHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that can be set on the speakerphone using phoneSetHookSwitch.

dwSettableHeadsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that can be set on the headset using phoneSetHookSwitch.

dwMonitoredHandsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the handset in a PHONE_STATE message and by phoneGetHookSwitch.

dwMonitoredSpeakerHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the speakerphone in a PHONE_STATE message and by phoneGetHookSwitch.

dwMonitoredHeadsetHookSwitchModes

The PHONEHOOKSWITCHMODE_ values that 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 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

PHONECAPS

Members

Remarks

QuickInfo

See Also