PHONECAPS - Telephony API Programmer's Reference

Telephony API Programmer's Reference

Home Index About

Custom Search

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_CLOSE 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 phoneGetHookSwitch.

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
PHONE_BUTTON, PHONE_CLOSE, PHONE_STATE, phoneGetDevCaps, phoneGetHookSwitch, phoneGetRing, phoneSetGain, phoneSetHookSwitch, phoneSetRing, phoneSetVolume

Last news from Greatis Software

    Nostalgia .Net     .Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »

Recommended software for developers

    Ultimate Pack     Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »

    Form Designer .Net     Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »

    Print Suite .Net     Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »

    Gradient Controls .Net     Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »

    Greatis iGrid     iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »

All the contacts and projects

Dmitry Vasiliev (just.dmitry)

More Online Helps

Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages

greatis just4fun network