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;

} 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 the returned information.

dwUsedSize

The size in bytes of this data structure that contains useful information.

dwProviderInfoSize

dwProviderInfoOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing service-provider specific information. The dwProviderInfoSize/Offset member provides information about the provider hardware or software, such as the vendor name and version numbers of hardware or 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 and the offset in bytes from the beginning of this data structure of the variably sized device field containing phone-specific information. The dwPhoneInfoSize/Offset member 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 and the offset in bytes from the beginning of this data structure of the variably sized device field containing a user-configurable name for this phone device. 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 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 through a PHONE_STATE callback message. This member uses the following PHONESTATE_ constants:

PHONESTATE_OTHER

A phone status information item other than those listed below has 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 when 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 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 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 (such as of the appearance of new phone devices) the application reinitializes its use of TAPI. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.

dwHookSwitchDevs

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

PHONEHOOKSWITCHDEV_HANDSET

The ubiquitous, hand-held ear- and mouthpiece.

PHONEHOOKSWITCHDEV_SPEAKER

A built-in loudspeaker and microphone. This can 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. These members are 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 and the speaker is mute.

PHONEHOOKSWITCHMODE_SPEAKER

The device's speaker is active and the microphone is mute.

PHONEHOOKSWITCHMODE_MICSPEAKER

The device's microphone and speaker are both active.

PHONEHOOKSWITCHMODE_UNKNOWN

The device's hookswitch state is unknown or cannot be detected.

dwVolumeFlags

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 through TSPI_phoneSetVolume; otherwise, FALSE.

dwGainFlags

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 using TSPI_phoneSetGain; otherwise, FALSE.

dwDisplayNumRows

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

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, ... dwNumRingModes minus one. If the value of this member is zero, applications have no control over the ring mode of the phone. If the value of this member 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 TSPI_phoneGetRing or the dwRingMode parameter of TSPI_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

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, of type PHONEBUTTONMODE_. The array is indexed by button/lamp identifier. Values are:

PHONEBUTTONMODE_DUMMY

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 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, of type PHONEBUTTONFUNCTION_. The array is indexed by button/lamp identifier.

dwLampModesSize

dwLampModesOffset

The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the lamp modes of the phone's lamps, of type PHONELAMPMODE_. The array is indexed by button/lamp identifier. Values are:

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 identifiers 0, 1, ..., dwNumSetData minus one. If this member is zero, the phone does not support the download capability.

dwSetDataSize

dwSetDataOffset

The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the sizes (in bytes) of the phone's download data areas. 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 identifiers 0, 1, ..., dwNumGetData minus one. If this member is zero, the phone does not support the upload capability.

dwGetDataSize

dwGetDataOffset

The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the sizes (in bytes) of the phone's upload data areas. This is an array with DWORD-sized elements, indexed by data identifier.

dwDevSpecificSize

dwDevSpecificOffset

The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

PHONEBUTTONMODE_ Constants, PHONEHOOKSWITCHDEV_ Constants, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps