Cisco Unified CME TAPI Phone Device

The Cisco Unified TAPI implementation comprises a set of classes that expose the functionality of Cisco Unified IP Telephony Solutions. This API allows developers to create customized IP telephony applications for Cisco Unified CME without specific knowledge of the communication protocols between Cisco Unified CME and the TSP. For example, a developer could create a TAPI application that communicates with an external voice messaging system.

This chapter outlines the TAPI 2.1 functions, events, and messages that Cisco Unified TSP 2.1 supports. The Cisco Unified TAPI phone device implementation contains functions in the following areas:

Cisco Unified CME TAPI Phone Functions

TAPI phone functions enable an application to control physical aspects of a phone.

phoneCallbackFunc

Description

The phoneCallbackFunc function provides a placeholder for the application-supplied function name. All callbacks occur in the application context. The callback function must reside in a dynamic-link library (DLL) or application module and be exported in the module-definition file.

Function Details

VOID FAR PASCAL phoneCallbackFunc(

HANDLE hDevice,

DWORD dwMsg,

DWORD dwCallbackInstance,

DWORD dwParam1,

DWORD dwParam2,

DWORD dwParam3

);

Parameters

hDevice

dwMsg

dwCallbackInstance

Callback instance data passed to the application in the callback. TAPI does not interpret this DWORD.

dwParam1

dwParam2

dwParam3

phoneClose

Description

Function Details

LONG phoneClose(

HPHONE hPhone

);

Parameters

hPhone

A handle to the open phone device that is to be closed. If the function succeeds, the handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE,

PHONEERR_OPERATIONFAILED.

phoneGetDevCaps

Description

The phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

Function Details

LONG phoneGetDevCaps(

HPHONEAPP hPhoneApp,

DWORD dwDeviceID,

DWORD dwAPIVersion,

DWORD dwExtVersion,

LPPHONECAPS lpPhoneCaps

);

Parameters

hPhoneApp

dwDeviceID

dwAPIVersion

The version number of the telephony API that is to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained with the function phoneNegotiateAPIVersion.

dwExtVersion

The version number of the service provider-specific extensions to be used.This number is obtained with the function phoneNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.

lpPhoneCaps

A pointer to a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capabilities information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_INVALPOINTER, PHONEERR_BADDEVICEID, 
PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODEVICE.

phoneGetDisplay

Description

The phoneGetDisplay function returns the current contents of the specified phone display.

Function Details

LONG phoneGetDisplay(

HPHONE hPhone,

LPVARSTRING lpDisplay

);

Parameters

hPhone

lpDisplay

A pointer to the memory location where the display content is to be stored, of type VARSTRING.

The Display parameter is returned with the contents of the current prompt display line of the IP phone.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED,

phoneGetHookswitch

Description

The phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

Function Details

LONG phoneGetHookSwitch(

HPHONE hPhone,

LPDWORD lpdwHookSwitchDevs

);

Parameters

hPhone

lpdwHookSwitchDevs

Pointer to a DWORD to be filled with the mode of the phone's hookswitch devices. If a bit position is FALSE, the corresponding hookswitch device is onhook; if TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether the microphone and/or speaker are enabled, the application can use phoneGetStatus.

Return Values

PHONEERR_INVALPHONEHANDLE, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, 
PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL. PHONEERR_UNINITIALIZED.

phoneGetMessage

Description

The phoneGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see phoneInitializeEx for further details).

Function Details

LONG phoneGetMessage(

HPHONEAPP hPhoneApp,

LPPHONEMESSAGE lpMessage,

DWORD dwTimeout

);

Parameters

hPhoneApp

The handle that phoneInitializeEx returns. The application must have set the PHONEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the PHONEINITIALIZEEXPARAMS structure.

lpMessage

A pointer to a PHONEMESSAGE structure. Upon successful return from this function, the structure contains the next message that had been queued for delivery to the application.

dwTimeout

The time-out interval, in milliseconds. The function returns when the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the time-out interval never elapses.

Return Values

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED,

PHONEERR_INVALPOINTER, PHONEERR_NOMEM.

phoneGetRing

Description

The phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

Function Details

LONG phoneGetRing(

HPHONE hPhone,

LPDWORD lpdwRingMode,

LPDWORD lpdwVolume

);

Parameters

hPhone

lpdwRingMode

The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.

lpdwVolume

phoneInitializeEx

Description

The phoneInitializeEx function initializes the application use of TAPI for subsequent use of the phone abstraction. It registers the application-specified notification mechanism and returns the number of phone devices that are available to the application. A phone device represents any device that provides an implementation for the phone-prefixed functions in the telephony API.

Function Details

LONG phoneInitializeEx(

LPHPHONEAPP lphPhoneApp,

HINSTANCE hInstance,

PHONECALLBACK lpfnCallback,

LPCSTR lpszFriendlyAppName,

LPDWORD lpdwNumDevs,

LPDWORD lpdwAPIVersion,

LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams

);

Parameters

lphPhoneApp

A pointer to a location that is filled with the application usage handle for TAPI.

hInstance

The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process.

lpfnCallback

The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see phoneCallbackFunc). When the application chooses to use the "event handle" or "completion port" event notification mechanisms, this parameter is ignored and should be set to NULL.

lpszFriendlyAppName

A pointer to a null-terminated string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name, which is provided in the PHONESTATUS structure, indicates, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application module filename is used instead (as returned by the windows function GetModuleFileName).

lpdwNumDevs

A pointer to a DWORD. Upon successful completion of this request, the number of phone devices that are available to the application fills this location.

lpdwAPIVersion

A pointer to a DWORD. The application must initialize this DWORD, before calling this function, to the highest API version that it is designed to support (for example, the same value that it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Do not use artificially high values; ensure the values are accurately set. TAPI translates any newer messages or structures into values or formats that the application version supports. Upon successful completion of this request, the highest API version that is supported by TAPI fills this location, thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.

lpPhoneInitializeExParams

A pointer to a structure of type PHONEINITIALIZEEXPARAMS that contains additional parameters that are used to establish the association between the application and TAPI (specifically, the application selected event notification mechanism and associated parameters).

Return Values

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED,

PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER,

PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

phoneNegotiateAPIVersion

Description

Use the phoneNegotiateAPIVersion function to negotiate the API version number to be used with the specified phone device. It returns the extension identifier that the phone device supports, or zeros if no extensions are provided.

Function Details

LONG WINAPI phoneNegotiateAPIVersion(

HPHONEAPP hPhoneApp,

DWORD dwDeviceID,

DWORD dwAPILowVersion,

DWORD dwAPIHighVersion,

LPDWORD lpdwAPIVersion,

LPPHONEEXTENSIONID lpExtensionID

);

Parameters

hPhoneApp

dwDeviceID

dwAPILowVersion

The least recent API version with which the application is compliant. The high-order word represents the major version number, and the low-order word represents the minor version number.

dwAPIHighVersion

The most recent API version with which the application is compliant. The high-order word represents the major version number, and the low-order word represents the minor version number.

lpdwAPIVersion

A pointer to a DWORD in which the API version number that was negotiated will be returned. If negotiation succeeds, this number ranges from dwAPILowVersion to dwAPIHighVersion.

lpExtensionID

A pointer to a structure of type PHONEEXTENSIONID. If the service provider for the specified dwDeviceID parameter supports provider-specific extensions, this structure is filled with the extension identifier of these extensions when negotiation succeeds. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED,

PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL,

PHONEERR_NODRIVER, PHONEERR_NOMEM,

PHONEERR_INVALPOINTER,

PHONEERR_RESOURCEUNAVAIL,

PHONEERR_INCOMPATIBLEAPIVERS

phoneOpen

Description

The phoneOpen function opens the specified phone device. The device can be opened by using either owner privilege or monitor privilege. An application that opens the phone with owner privilege can control the lamps, display, ringer, and hookswitch or hookswitches that belong to the phone. An application that opens the phone device with monitor privilege receives notification only about events that occur at the phone, such as hookswitch changes or button presses. Because ownership of a phone device is exclusive, only one application at a time can have a phone device opened with owner privilege. The phone device can, however, be opened multiple times with monitor privilege.

Function Details

LONG phoneOpen(

HPHONEAPP hPhoneApp,

DWORD dwDeviceID,

LPHPHONE lphPhone,

DWORD dwAPIVersion,

DWORD dwExtVersion,

DWORD dwCallbackInstance,

DWORD dwPrivilege

);

Parameters

hPhoneApp

dwDeviceID

lphPhone

A pointer to an HPHONE handle that identifies the open phone device. Use this handle to identify the device when invoking other phone control functions.

dwAPIVersion

The API version number under which the application and telephony API agreed to operate. Obtain this number from phoneNegotiateAPIVersion.

dwExtVersion

The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. Obtain this number from phoneNegotiateExtVersion.

dwCallbackInstance

User instance data passed back to the application with each message. The telephony API does not interpret this parameter.

dwPrivilege

The privilege requested. The dwPrivilege parameter can have only one bit set. This parameter uses the following PHONEPRIVILEGE_ constants:

•

PHONEPRIVILEGE_MONITOR — An application that opens a phone device with this privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state.

•

PHONEPRIVILEGE_OWNER — An application that opens a phone device in this mode can change the state of the lamps, ringer, display, and hookswitch devices of the phone. Having owner privilege to a phone device automatically includes monitor privilege as well.

phoneSetHookswitch

Description

The phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

Function Details

LONG WINAPI phoneSetHookSwitch(

  HPHONE hPhone,

  DWORD dwHookSwitchDevs,

  DWORD dwHookSwitchMode

);

Parameters

hPhone

Handle to the open phone device. The application must be the owner of the phone.

dwHookSwitchDevs

Device whose hookswitch mode is to be set. This parameter uses one and only one of the PHONEHOOKSWITCHDEV_ constants:

dwHookSwitchMode

Hookswitch mode to set. This parameter uses one and only one of the 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.

Return Values

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, 
PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, 
PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, 
PHONEERR_UNINITIALIZED.

phoneSetRing

Description

The phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

Note For Cisco Unified CME TSP 2.1, this function is used only to set the ringer volume. The Ringer Device is selected during configuration and the ring patterns are played based on the ring type sent by the Cisco Unified CME.

Function Details

LONG WINAPI phoneSetRing(

  HPHONE hPhone,

  DWORD dwRingMode,

  DWORD dwVolume

);

Parameters

hPhone

Handle to the open phone device. The application must be the owner of the phone device.

dwRingMode

Ringing pattern with which to ring the phone. This parameter must be within the range of zero to the value of the dwNumRingModes member in the PHONECAPS structure. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 to dwNumRingModes are valid ring modes for the phone device.

dwVolume

Volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, 
PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, 
PHONEERR_INVALRINGMODE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

phoneSetVolume

Description

The phoneSetVolume function sets the volume of the speaker component of the specified hookswitch device to the specified level.

Function Details

LONG WINAPI phoneSetVolume(

  HPHONE hPhone,

  DWORD dwHookSwitchDev,

  DWORD dwVolume

);

Parameters

hPhone

Handle to the open phone device. The application must be the owner of the phone.

dwHookSwitchDev

Hookswitch device whose speaker's volume is to be set, one of the PHONEHOOKSWITCHDEV_ constants.

dwVolume

New volume setting of the device. The dwVolume parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, 
PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, 
PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

phoneShutdown

Description

The phoneShutdown function shuts down the application usage of the TAPI phone abstraction.

Note If this function is called when the application has open phone devices, these devices are closed.

Function Details

LONG WINAPI phoneShutdown(

HPHONEAPP hPhoneApp

);

Parameters

hPhoneApp

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs.

PHONEERR_INVALAPPHANDLE, PHONEERR_NOMEM,

PHONEERR_UNINITIALIZED,

Cisco Unified CME TAPI Phone Messages

This section describes the phone device messages that Cisco Unified CME TSP 2.1 supports. These messages notify the application of asynchronous events such as the a new call arriving in the Cisco Unified CME. The messages get sent to the application using the method that the application specifies in phoneInitializeEx.

PHONE_CLOSE

Description

The TAPI PHONE_CLOSE message is sent when an open phone device has been forcibly closed as part of resource reclamation. The device handle is no longer valid once this message has been sent.

Function Details

PHONE_CLOSE

hPhone = (HPHONE) hPhoneDevice;

dwCallbackInstance = (DWORD) hCallback;

dwParam1 = (DWORD) 0;

dwParam2 = (DWORD) 0;

dwParam3 = (DWORD) 0;

Parameters

hPhone

A handle to the open phone device that was closed. The handle is no longer valid after this message has been sent.

dwCallbackInstance

The application's callback instance that provided when opening the phone device.

dwParam1

dwParam2

dwParam3

PHONE_REMOVE

Description

The TAPI PHONE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a phone device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were re-initialized.

Function Details

PHONE_REMOVE

hDevice = (DWORD) 0;

dwCallbackInstance = (DWORD) 0;

dwParam1 = (DWORD) hDeviceID;

dwParam2 = (DWORD) 0;

dwParam3 = (DWORD) 0;

Parameters

hDevice

dwCallbackInstance

dwParam1

dwParam2

dwParam3

PHONE_REPLY

Description

The TAPI PHONE_REPLY message is sent to an application to report the results of function call that completed asynchronously.

Function Details

PHONE_REPLY

hPhone = (HPHONE) 0;

dwCallbackInstance = (DWORD) hCallback;

dwParam1 = (DWORD) idRequest;

dwParam2 = (DWORD) Status;

dwParam3 = (DWORD) 0;

Parameters

hPhone

dwCallbackInstance

dwParam1

dwParam2

The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.

dwParam3

Cisco Unified CME TAPI Phone Structures

This section describes the main phone structures that are impacted by Cisco Unified CME TSP 2.1. These structures are used to exchange parameters between the application and TAPI and between TAPI and Cisco Unified CME TSP 2.1. In response to the line messages from the TSP, the TAPI layer makes functions calls with these structures to obtain the message-related detailed information.

PHONECAPS

Description

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

Function Details

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;

  GUID PermanentPhoneGuid;

} PHONECAPS,

Parameters

dwTotalSize

dwNeededSize

Size for this data structure that is needed to hold all the returned information, in bytes.

dwUsedSize

Size of the portion of this data structure that contains useful information, in bytes.

dwProviderInfoSize

Size of the provider-specific information, in bytes. If the provider-specific information is a pointer to a string, the size must include the null terminator.

dwProviderInfoOffset

Offset from the beginning of the structure to the variably sized field containing service provider-specific information.

This 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. The size of the field is specified by dwProviderInfoSize.

dwPhoneInfoSize

Size of the phone-specific information, in bytes. If the phone-specific information is a pointer to a string, the size must include the null terminator.

dwPhoneInfoOffset

Offset from the beginning of the structure to the variably sized device field containing phone-specific information.

This 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. The size of the field is specified by dwPhoneInfoSize.

dwPermanentPhoneID

Permanent identifier by which the phone device is known in the system's configuration.

dwPhoneNameSize

dwPhoneNameOffset

Offset from the beginning of the structure to the variably sized device field containing a user-specified 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. The size of the field is specified by dwPhoneNameSize.

dwStringFormat

String format to be used with this phone device. This member uses one of the STRINGFORMAT_ constants.

dwPhoneStates

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

Phone's hookswitch devices. This member uses one of the PHONEHOOKSWITCHDEV_ constants.

dwHandsetHookSwitchModes

Hookswitch mode of the handset. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. It uses one of the PHONEHOOKSWITCHMODE_ constants.

dwSpeakerHookSwitchModes

Hookswitch mode of the speaker. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. It uses one of the PHONEHOOKSWITCHMODE_ constants.

dwHeadsetHookSwitchModes

Hookswitch mode of the headset. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. It uses one of the PHONEHOOKSWITCHMODE_ constants.

dwVolumeFlags

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.

dwGainFlags

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.

dwDisplayNumRows

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

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

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

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

Offset from the beginning of this structure to the variably sized field containing the button modes of the phone's buttons. The array is indexed by button/lamp identifier. This array uses the PHONEBUTTONMODE_ constants. The size of the array is specified by dwButtonModesSize.

dwButtonFunctionsSize

dwButtonFunctionsOffset

Offset from the beginning of this structure to the variably sized field containing the button functions of the phone's buttons. The array is indexed by button/lamp identifier. This array uses the PHONEBUTTONFUNCTION_ constants. The size of the array is specified by dwButtonFunctionsSize.

dwLampModesSize

dwLampModesOffset

Offset from the beginning of this structure to the variably sized field containing the lamp modes of the phone's lamps. The array is indexed by button/lamp identifier. This array uses the PHONELAMPMODE_ constants. The size of the array is specified by dwLampModesSize.

dwNumSetData

Number of different download areas in the phone device. The different areas are referred to using the data IDs 0, 1, and dwNumSetData minus one. If this member is zero, the phone does not support the download capability.

dwSetDataSize

dwSetDataOffset

Offset from the beginning of this structure to 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. The size of the array is specified by dwSetDataSize.

dwNumGetData

Number of different upload areas in the phone device. The different areas are referred to using the data IDs 0, 1, and dwNumGetData minus one. If this field is zero, the phone does not support the upload capability.

dwGetDataSize

dwGetDataOffset

Offset from the beginning of this structure to 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. The size of the array is specified by dwGetDataSize.

dwDevSpecificSize

Size of the device-specific field, in bytes. If the device specific information is a pointer to a string, the size must include the null terminator.

dwDevSpecificOffset

Offset from the beginning of this structure to the variably sized device-specific field. The size of the field is specified by dwDevSpecificSize.

dwDeviceClassesSize

dwDeviceClassesOffset

Offset from the beginning of this structure to a string consisting of the device class identifiers supported on this device for use with phoneGetID. The identifiers are separated by NULLs, and the last identifier in the list is followed by two NULLs. The size of the field is specified by dwDeviceClassesSize.

dwPhoneFeatures

Flags that 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

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

dwSettableSpeakerHookSwitchModes

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

dwSettableHeadsetHookSwitchModes

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

dwMonitoredHandsetHookSwitchModes

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

dwMonitoredSpeakerHookSwitchModes

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

dwMonitoredHeadsetHookSwitchModes

PHONEHOOKSWITCHMODE_ values that can be detected and reported for the headset in a PHONE_STATE message and by phoneSetHookSwitch.

PermanentPhoneGuid

PHONEEXTENSIONID

Description

The PHONEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service provider-specific extensions for phone device classes. The phoneNegotiateAPIVersion and TSPI_phoneGetExtensionID functions return this structure.

Function Details

typedef struct phoneextensionid_tag {

  DWORD dwExtensionID0;

  DWORD dwExtensionID1;

  DWORD dwExtensionID2;

  DWORD dwExtensionID3;

} PHONEEXTENSIONID,

*LPPHONEEXTENSIONID;

Parameters

dwExtensionID0

dwExtensionID1

dwExtensionID2

dwExtensionID3

PHONEMESSAGE

Description

The PHONEMESSAGE structure contains the next message queued for delivery to the application. The phoneGetMessage function returns this structure.

Function Details

typedef struct phonemessage_tag {

  DWORD hDevice;

  DWORD dwMessageID;

  DWORD_PTR dwCallbackInstance;

  DWORD_PTR dwParam1;

  DWORD_PTR dwParam2;

  DWORD_PTR dwParam3;

} PHONEMESSAGE,

*LPPHONEMESSAGE;

Parameters

hDevice

dwMessageID

dwCallbackInstance

Instance data passed back to the application, which was specified by the application in phoneInitializeEx. This value is not interpreted by TAPI.

dwParam1

dwParam2

dwParam3

Table Of Contents