|
Table Of Contents
Cisco Unified CME TAPI Phone Device
Cisco Unified CME TAPI Phone Functions
Cisco Unified CME TAPI Phone Messages
Cisco Unified CME TAPI Phone Structures
Cisco Unified CME TAPI Phone Device
Revised: January 12, 2007The 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
• Cisco Unified CME TAPI Phone Messages
• Cisco Unified CME TAPI Phone Structures
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
A handle to a phone device that is associated with the callback.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data passed to the application in the callback. TAPI does not interpret this DWORD.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.
phoneClose
Description
The phoneClose function closes the specified open phone device.
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
The handle to the registration with TAPI for this application.
dwDeviceID
The phone device that is to be queried.
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
A handle to the open phone device.
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
A handle to the open phone device.
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
Possible return values follow:
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
A handle to the open phone device.
lpdwRingMode
The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
lpdwVolume
The volume level with which the phone is ringing.
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
Possible return values follow:
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
The handle to the application registration with TAPI.
dwDeviceID
The phone device to be queried.
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
Possible return values follow:
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
A handle by which the application is registered with TAPI.
dwDeviceID
The phone device to be opened.
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:
•PHONEHOOKSWITCHDEV_HANDSET: the phone's handset.
•PHONEHOOKSWITCHDEV_SPEAKER: the phone's speakerphone or adjunct.
•PHONEHOOKSWITCHDEV_HEADSET: the phone's headset.
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
Possible return values are:
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
The application usage handle for TAPI.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs.
Possible return values follow:
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
Unused.
dwParam2
Unused.
dwParam3
Unused.
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
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the phone device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.
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
Unused.
dwCallbackInstance
Returns the application's callback instance.
dwParam1
The request identifier for which this is the reply.
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
Unused.
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
Total size allocated to this data structure, in bytes.
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
Size of the name for the phone, including the null terminator, in bytes.
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
Size of the button modes array, in bytes.
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
Size of the button functions field, in bytes.
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
Size of the lamp modes array, in bytes.
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
Size of the data size array, in bytes.
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
Size of the data size array, in bytes.
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
Size of the supported device class identifiers, in bytes.
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
The GUID permanently associated with this phone.
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
First part of the extension identifier.
dwExtensionID1
Second part of the extension identifier.
dwExtensionID2
Third part of the extension identifier.
dwExtensionID3
Fourth part of the extension identifier.
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
Handle to a phone device.
dwMessageID
Phone message.
dwCallbackInstance
Instance data passed back to the application, which was specified by the application in phoneInitializeEx. This value is not interpreted by TAPI.
dwParam1
Parameter for the message.
dwParam2
Parameter for the message.
dwParam3
Parameter for the message.
Posted: Mon Apr 9 17:29:16 PDT 2007
All contents are Copyright © 1992--2007 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.