PHONECAPS

The PHONECAPS structure describes the capabilities of a phone device. The phoneGetDevCaps and TSPI_phoneGetDevCaps functions return this structure.

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;               //TAPI 2.0
  DWORD dwDeviceClassesOffset;             //TAPI 2.0
  DWORD dwPhoneFeatures;                   //TAPI 2.0
  DWORD dwSettableHandsetHookSwitchModes;  //TAPI 2.0
  DWORD dwSettableSpeakerHookSwitchModes;  //TAPI 2.0
  DWORD dwSettableHeadsetHookSwitchModes;  //TAPI 2.0
  DWORD dwMonitoredHandsetHookSwitchModes; //TAPI 2.0
  DWORD dwMonitoredSpeakerHookSwitchModes; //TAPI 2.0
  DWORD dwMonitoredHeadsetHookSwitchModes; //TAPI 2.0
  GUID PermanentPhoneGuid;                 //TAPI 2.2
} 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 one of the STRINGFORMAT_ Constants.

dwPhoneStates

The state changes for this phone device for which the application can be notified in a PHONE_STATE message. This member one or more of the PHONESTATE_ Constants.

dwHookSwitchDevs

Specifies the phone's hookswitch devices. This member uses one of the PHONEHOOKSWITCHDEV_ Constants.

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 one of the PHONEHOOKSWITCHMODE_ Constants.

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 one of the PHONEBUTTONMODE_ Constants.

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 one of 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 one of the PHONELAMPMODE_ Constants.

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.

PermanentPhoneGuid

The GUID permanently associated with this phone.

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.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 1.4 or later.
  Header: Declared in Tapi.h.

See Also

PHONE_BUTTON, PHONE_CLOSE, PHONE_STATE, phoneGetDevCaps, TSPI_phoneGetDevCaps, phoneGetHookSwitch, phoneGetRing, phoneSetGain, phoneSetHookSwitch, phoneSetRing, phoneSetVolume