 Feedback
|
Table Of Contents
Cisco Unified TAPI Implementation
TAPI Assisted Telephony Functions
Cisco Unified TAPI Implementation
The Cisco Unified TAPI implementation comprises a set of classes that expose the functionality of Cisco Unified Communications Solutions. This API allows developers to create customized IP Telephony applications for Cisco Unified CallManager without specific knowledge of the communication protocols between the Cisco Unified CallManager and the service provider. 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 the Cisco Unified TAPI Service Provider supports and does not support. The Cisco Unified TAPI implementation contains functions in the following areas:
•
Wave
TAPI Line Functions
The number of TAPI devices that are configured in the Cisco Unified CallManager determines the number of available lines. To terminate an audio stream by using first-party call control, you must first install the Cisco wave device driver.
lineAccept
Description
The lineAccept function accepts the specified offered call.
Function Details
LONG lineAccept(HCALL hCall,LPCSTR lpsUserUserInfo,DWORD dwSize);Parameters
hCall
A handle to the call to be accepted. The application must be an owner of the call. Call state of hCall must be offering.
lpsUserUserInfo
A pointer to a string that contains user-user information to be sent to the remote party as part of the call accept. Leave this pointer NULL if no user-user information is to be sent. User-user information only gets sent if supported by the underlying network. The protocol discriminator member for the user-user information, if required, should appear as the first byte of the buffer that is pointed to by lpsUserUserInfo and must be accounted for in dwSize.
Note
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information gets sent to the calling party, and dwSize is ignored.
lineAddProvider
Description
The lineAddProvider function installs a new telephony service provider into the telephony system.
Function Details
LONG WINAPI lineAddProvider(LPCSTR lpszProviderFilename,HWND hwndOwner,LPDWORD lpdwPermanentProviderID);Parameters
lpszProviderFilename
A pointer to a null-terminated string that contains the path of the service provider to be added.
hwndOwner
A handle to a window in which any dialog boxes that need to be displayed as part of the installation process (for example, by the service provider's TSPI_providerInstall function) would be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpdwPermanentProviderID
A pointer to a DWORD-sized memory location into which TAPI writes the permanent provider identifier of the newly installed service provider.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED.
lineAddToConference
Description
This function takes the consult call that is specified by hConsultCall and adds it to the conference call that is specified by hConfCall.
Function Details
LONG lineAddToConference(HCALL hConfCall,HCALL hConsultCall);Parameters
hConfCall
A pointer to the conference call handle. The state of the conference call must be OnHoldPendingConference or OnHold.
hConsultCall
A pointer to the consult call that will be added to the conference call. The application must be the owner of this call, and it cannot be a member of another conference call. The allowed states of the consult call comprise connected, onHold, proceeding, or ringback
lineAnswer
Description
The lineAnswer function answers the specified offering call.
Note
Function Details
LONG lineAnswer(HCALL hCall,LPCSTR lpsUserUserInfo,DWORD dwSize);Parameters
hCall
A handle to the call to be answered. The application must be an owner of this call. The call state of hCall must be offering or accepted.
lpsUserUserInfo
A pointer to a string that contains user-user information to be sent to the remote party at the time the call is answered. You can leave this pointer NULL if no user-user information will be sent.
User-user information only gets sent if supported by the underlying network. The protocol discriminator field for the user-user information, if required, should be the first byte of the buffer that is pointed to by lpsUserUserInfo and must be accounted for in dwSize.
Note
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information gets sent to the calling party, and dwSize is ignored.
lineBlindTransfer
Description
The lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.
Note
If the application tries to blind transfer a call to an address that requires a FAC, CMC, or both, then the lineBlindTransfer function will return an error. If a FAC is required, the TSP will return the error LINEERR_FACREQUIRED. If a CMC is required, the TSP will return the error LINEERR_CMCREQUIRED. If both a FAC and a CMC is required, the TSP will return the error LINEERR_FACANDCMCREQUIRED. An application that wishes to blind transfer a call to an address that requires a FAC, CMC, or both, should use the lineDevSpecific - BlindTransferFACCMC function.
Function Details
LONG lineBlindTransfer(HCALL hCall,LPCSTR lpszDestAddress,DWORD dwCountryCode);Parameters
hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be connected.
lpszDestAddress
A pointer to a NULL-terminated string that identifies the location to which the call is to be transferred. The destination address uses the standard dial number format.
dwCountryCode
The country code of the destination. The implementation uses this parameter to select the call progress protocols for the destination address. If a value of 0 is specified, the defined default call-progress protocol is used.
lineCallbackFunc
Description
The lineCallbackFunc function provides a placeholder for the application-supplied function name.
Function Details
VOID FAR PASCAL lineCallbackFunc(DWORD hDevice,DWORD dwMsg,DWORD dwCallbackInstance,DWORD dwParam1,DWORD dwParam2,DWORD dwParam3);Parameters
hDevice
A handle to either a line device or a call that is associated with the callback. The context provided by dwMsg determines thee nature of this handle (line handle or call handle). Applications must use the DWORD type for this parameter because using the HANDLE type may generate an error.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data that is passed back to the application in the callback. TAPI does not interpret DWORD.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.
Further Details
For information about parameter values that are passed to this function, see "TAPI Line Functions."
lineClose
Description
The lineClose function closes the specified open line device.
Function Details
LONG lineClose(HLINE hLine);Parameter
hLine
A handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.
lineCompleteTransfer
Description
The lineCompleteTransfer function completes the transfer of the specified call to the party that is connected in the consultation call.
Function Details
LONG lineCompleteTransfer(HCALL hCall,HCALL hConsultCall,LPHCALL lphConfCall,DWORD dwTransferMode);Parameters
hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer.
hConsultCall
A handle to the call that represents a connection with the destination of the transfer. The application must be an owner of this call. The call state of hConsultCall must be connected, ringback, busy, or proceeding.
lphConfCall
A pointer to a memory location where an hCall handle can be returned. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned in lphConfCall and the application becomes the sole owner of the conference call. Otherwise, this parameter gets ignored by TAPI.
dwTransferMode
Specifies how the initiated transfer request is to be resolved. This parameter uses the following LINETRANSFERMODE_ constant:
–
–
lineConfigProvider
Description
The lineConfigProvider function causes a service provider to display its configuration dialog box. This basically provides a straight pass-through to TSPI_providerConfig.
Function Details
LONG WINAPI lineConfigProvider(HWND hwndOwner,DWORD dwPermanentProviderID);Parameters
hwndOwner
A handle to a window to which the configuration dialog box (displayed by TSPI_providerConfig) is attached. This parameter can be NULL to indicate that any window that is created during the function should have no owner window.
dwPermanentProviderID
The permanent provider identifier of the service provider to be configured.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.
lineDeallocateCall
Description
The lineDeallocateCall function deallocates the specified call handle.
Function Details
LONG lineDeallocateCall(HCALL hCall);Parameter
hCall
The call handle to be deallocated. An application with monitoring privileges for a call can always deallocate its handle for that call. An application with owner privilege for a call can deallocate its handle unless it is the sole owner of the call and the call is not in the idle state. The call handle is no longer valid after it has been deallocated.
lineDevSpecific
Description
The lineDevSpecific function enables service providers to provide access to features that other TAPI functions do not offer. The extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.
When used with the Cisco Unified CallManager TSP, lineDevSpecific can be used to
•
•
•
•
•
•
•
•
•
•
•
Note
Function Details
LONG lineDevSpecific(HLINE hLine,DWORD dwAddressID,HCALL hCall,LPVOID lpParams,DWORD dwSize);Parameters
hLine
A handle to a line device. This parameter is required.
dwAddressID
An address identifier on the given line device.
hCall
A handle to a call. Although this parameter is optional, it is specified, the call that it represents must belong to the hLine line device. The call state of hCall is device specific.
lpParams
A pointer to a memory area that is used to hold a parameter block. The format of this parameter block specifies device specific, and TAPI passes its contents to or from the service provider.
dwSize
The size in bytes of the parameter block area.
lineDial
Description
The lineDial function dials the specified number on the specified call.
This function can be used by the application to enter a FAC or CMC. The FAC or CMC can be entered one digit at a time or multiple digits at a time. The application may also enter both the FAC and CMC if required in one lineDial() request as long as the FAC and CMC are separated by a "#" character. If sending both a FAC and CMC in one lineDial() request, it is recommended to terminate the lpszDestAddress with a "#" character in order to avoid waiting for the T.302 interdigit timeout.
This function cannot be used to enter a dial string along with a FAC and/or a CMC. The FAC and/or CMC must be entered in a separate lineDial request.
Function Details
LONG lineDial(HCALL hCall,LPCSTR lpszDestAddress,DWORD dwCountryCode);Parameters
hCall
A handle to the call on which a number is to be dialed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.
lpszDestAddress
The destination to be dialed by using the standard dial number format.
dwCountryCode
The country code of the destination. The implementation uses this code to select the call progress protocols for the destination address. If a value of 0 is specified, the default call progress protocol is used.
lineDrop
Description
The lineDrop function drops or disconnects the specified call. The application can specify user-user information to be transmitted as part of the call disconnect.
Function Details
LONG lineDrop(HCALL hCall,LPCSTR lpsUserUserInfo,DWORD dwSize);Parameters
hCall
A handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.
lpsUserUserInfo
A pointer to a string that contains user-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-user information is to be sent. User-user information only gets sent if supported by the underlying network. The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer that is pointed to by lpsUserUserInfo and must be accounted for in dwSize.
Note
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information gets sent to the calling party, and dwSize is ignored.
lineForward
Description
The lineForward function forwards calls that are destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the switch deflects the specified incoming calls for that address to the other number. This function provides a combination of forward all feature. This API allows calls to be forwarded unconditionally to a forwarded destination.
This function can also cancel forwarding that currently is in effect.
To indicate that the forward is set/reset, upon completion of lineForward, TAPI fires LINEADDRESSSTATE events that indicate the change in the line forward status.
Change forward destination with a call to lineForward without canceling the current forwarding set on that line.
Note
Function Details
LONG lineForward(HLINE hLine,DWORD bAllAddresses,DWORD dwAddressID,LPLINEFORWARDLIST const lpForwardList,DWORD dwNumRingsNoAnswer,LPHCALL lphConsultCall,LPLINECALLPARAMS const lpCallParams);Parameters
hLine
A handle to the line device.
bAllAddresses
Specifies whether all originating addresses on the line or just the one that is specified are to be forwarded. If TRUE, all addresses on the line get forwarded, and dwAddressID is ignored; if FALSE, only the address that is specified as dwAddressID gets forwarded.
dwAddressID
The address of the specified line whose incoming calls are to be forwarded. This parameter gets ignored if bAllAddresses is TRUE.
Note
lpForwardList
A pointer to a variably sized data structure that describes the specific forwarding instructions of type LINEFORWARDLIST.
Note
dwNumRingsNoAnswer
The number of rings before a call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value gets set to the nearest value in the allowable range.
Note
lphConsultCall
A pointer to an HCALL location. In some telephony environments, this location is loaded with a handle to a consultation call that is used to consult the party that is being forwarded to, and the application becomes the initial sole owner of this call. This pointer must be valid even in environments where call forwarding does not require a consultation call. This handle is set to NULL if no consultation call is created.
Note
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer gets ignored unless lineForward requires the establishment of a call to the forwarding destination (and lphConsultCall is returned; in which case, lpCallParams is optional). If NULL, default call parameters get used. Otherwise, the specified call parameters get used for establishing hConsultCall.
Note
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.
Note
lineGenerateDigits
Description
The lineGenerateDigits function initiates the generation of the specified digits on the specified call as out-of-band tones by using the specified signaling mode.
Note
Function Details
LONG lineGenerateDigits(HCALL hCall,DWORD dwDigitMode,LPCSTR lpszDigits,DWORD dwDuration);Parameters
hCall
A handle to the call. The application must be an owner of the call. Call state of hCall can be any state.
dwDigitMode
The format to be used for signaling these digits. The dwDigitMode can have only a single flag set. This parameter uses the following LINEDIGITMODE_ constant:
–
lpszDigits
Valid characters for DTMF mode in the Cisco Unified CallManager TSP include `0' through `9', `*', and `#'.
dwDuration
Duration in milliseconds during which the tone should be sustained.
Note
lineGenerateTone
Description
The lineGenerateTone function generates the specified tone over the specified call.
Note
Function Details
LONG lineGenerateTone(HCALL hCall,DWORD dwToneMode,DWORD dwDuration,DWORD dwNumTones,LPLINEGENERATETONE const lpTones);Parameters
hCall
A handle to the call on which a tone is to be generated. The application must be an owner of the call. The call state of hCall can be any state.
dwToneMode
Defines the tone to be generated. Tones can be either standard or custom. A custom tone comprises a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone gets specified with dwDuration for both standard and custom tones. The dwToneMode parameter can have only one bit set. If no bits are set (the value 0 is passed), tone generation gets canceled. This parameter uses the following LINETONEMODE_ constant:
–
dwDuration
Duration in milliseconds during which the tone should be sustained.
Note
dwNumTones
The number of entries in the lpTones array. This parameter gets ignored if dwToneMode is not equal to CUSTOM.
lpTones
A pointer to a LINEGENERATETONE array that specifies the components of the tone. This parameter gets ignored for non-custom tones. If lpTones is a multifrequency tone, the various tones play simultaneously.
lineGetAddressCaps
Description
The lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.
Function Details
LONG lineGetAddressCaps(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAddressID,DWORD dwAPIVersion,DWORD dwExtVersion,LPLINEADDRESSCAPS lpAddressCaps);Parameters
hLineApp
The handle by which the application is registered with TAPI.
dwDeviceID
The line device that contains the address to be queried. Only one address gets supported per line, so dwAddressID must be zero.
dwAddressID
The address on the given line device whose capabilities are to be queried.
dwAPIVersion
The version number, obtained by lineNegotiateAPIVersion, of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number.
dwExtVersion
The version number of the extensions to be used. This number can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number and the low-order word contains the minor version number.
lpAddressCaps
A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure gets filled with address capabilities information. Prior to calling lineGetAddressCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lineGetAddressID
Description
The lineGetAddressID function returns the address identifier that is associated with an address in a different format on the specified line.
Function Details
LONG lineGetAddressID(HLINE hLine,LPDWORD lpdwAddressID,DWORD dwAddressMode,LPCSTR lpsAddress,DWORD dwSize);Parameters
hLine
A handle to the open line device.
lpdwAddressID
A pointer to a DWORD-sized memory location that returns the address identifier.
dwAddressMode
The address mode of the address that is contained in lpsAddress. The dwAddressMode parameter can have only a single flag set. This parameter uses the following LINEADDRESSMODE_ constant:
–
lpsAddress
A pointer to a data structure that holds the address that is assigned to the specified line device. dwAddressMode determines the format of the address. Because the only valid value is LINEADDRESSMODE_DIALABLEADDR, lpsAddress uses the common dialable number format and is NULL-terminated.
dwSize
The size of the address that is contained in lpsAddress.
lineGetAddressStatus
Description
The lineGetAddressStatus function allows an application to query the specified address for its current status.
Function Details
LONG lineGetAddressStatus(HLINE hLine,DWORD dwAddressID,LPLINEADDRESSSTATUS lpAddressStatus);Parameters
hLine
A handle to the open line device.
dwAddressID
An address on the given open line device. This is the address to be queried.
lpAddressStatus
A pointer to a variably sized data structure of type LINEADDRESSSTATUS. Prior to calling lineGetAddressStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lineGetCallInfo
Description
The lineGetCallInfo function enables an application to obtain fixed information about the specified call.
Function Details
LONG lineGetCallInfo(HCALL hCall,LPLINECALLINFO lpCallInfo);Parameters
hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallInfo
A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, call-related information fills this structure. Prior to calling lineGetCallInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lineGetCallStatus
Description
The lineGetCallStatus function returns the current status of the specified call.
Function Details
LONG lineGetCallStatus(HCALL hCall,LPLINECALLSTATUS lpCallStatus);Parameters
hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallStatus
A pointer to a variably sized data structure of type LINECALLSTATUS. Upon successful completion of the request, call status information fills this structure. Prior to calling lineGetCallStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lineGetConfRelatedCalls
Description
The lineGetConfRelatedCalls function returns a list of call handles that are part of the same conference call as the specified call. The specified call represents either a conference call or a participant call in a conference call. New handles get generated for those calls for which the application does not already have handles, and the application receives monitor privilege to those calls.
Function Details
LONG WINAPI lineGetConfRelatedCalls(HCALL hCall,LPLINECALLLIST lpCallList);Parameters
hCall
A handle to a call. This represents either a conference call or a participant call in a conference call. For a conference parent call, the call state of hCall can be any state. For a conference participant call, it must be in the conferenced state.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all calls in the conference call return in this structure. The first call in the list represents the conference call, the other calls represent the participant calls. The application receives monitor privilege to those calls for which it does not already have handles; the privileges to calls in the list for which the application already has handles remains unchanged. Prior to calling lineGetConfRelatedCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOCONFERENCE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.
lineGetDevCaps
Description
The lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information applies for all addresses on the line device.
Function Details
LONG lineGetDevCaps(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAPIVersion,DWORD dwExtVersion,LPLINEDEVCAPS lpLineDevCaps);Parameters
hLineApp
The handle by which the application is registered with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The version number, obtained by lineNegotiateAPIVersion, of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number.
dwExtVersion
The version number, obtained by lineNegotiateExtVersion, of the extensions to be used. 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.
lpLineDevCaps
A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure gets filled with line device capabilities information. Prior to calling lineGetDevCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lineGetID
Description
The lineGetID function returns a device identifier for the specified device class that is associated with the selected line, address, or call.
Function Details
LONG lineGetID(HLINE hLine,DWORD dwAddressID,HCALL hCall,DWORD dwSelect,LPVARSTRING lpDeviceID,LPCSTR lpszDeviceClass);Parameters
hLine
A handle to an open line device.
dwAddressID
An address on the given open line device.
hCall
A handle to a call.
dwSelect
Specifies whether the requested device identifier is associated with the line, address or a single call. The dwSelect parameter can only have a single flag set. This parameter uses the following LINECALLSELECT_ constants:
–
–
–
lpDeviceID
A pointer to a memory location of type VARSTRING, where the device identifier is returned. Upon successful completion of the request, the device identifier fills this location. The format of the returned information depends on the method the device class API uses for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lpszDeviceClass
A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose identifier is requested. Device classes include wave/in, wave/out and tapi/line.
Valid device class strings are those that are used in the SYSTEM.INI section to identify device classes.
lineGetLineDevStatus
Description
The lineGetLineDevStatus function enables an application to query the specified open line device for its current status.
Function Details
LONG lineGetLineDevStatus(HLINE hLine,LPLINEDEVSTATUS lpLineDevStatus);Parameters
hLine
A handle to the open line device to be queried.
lpLineDevStatus
A pointer to a variably sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, the device status of the line fills this structure. Prior to calling lineGetLineDevStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
lineGetMessage
Description
The lineGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see lineInitializeEx for further details).
Function Details
LONG WINAPI lineGetMessage(HLINEAPP hLineApp,LPLINEMESSAGE lpMessage,DWORD dwTimeout);Parameters
hLineApp
The handle returned by lineInitializeEx. The application must have set the LINEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the LINEINITIALIZEEXPARAMS structure.
lpMessage
A pointer to a LINEMESSAGE 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 if 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 function's time-out interval never elapses.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_NOMEM.
lineGetNewCalls
Description
The lineGetNewCalls function returns call handles to calls on a specified line or address for which the application currently does not have handles. The application receives monitor privilege for these calls.
An application can use lineGetNewCalls to obtain handles to calls for which it currently has no handles. The application can select the calls for which handles are to be returned by basing this selection on scope (calls on a specified line, or calls on a specified address). For example, an application can request call handles to all calls on a given address for which it currently has no handle.
Function Details
LONG WINAPI lineGetNewCalls(HLINE hLine,DWORD dwAddressID,DWORD dwSelect,LPLINECALLLIST lpCallList);Parameters
hLine
A handle to an open line device.
dwAddressID
An address on the given open line device. An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.
dwSelect
The selection of calls that are requested. This parameter uses one and only one of the LINECALLSELECT_ Constants.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all selected calls get returned in this structure. Prior to calling lineGetNewCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.
lineGetNumRings
Description
The lineGetNumRings function determines the number of rings that an incoming call on the given address should ring before the call is answered.
Function Details
LONG WINAPI lineGetNumRings(HLINE hLine,DWORD dwAddressID,LPDWORD lpdwNumRings);Parameters
hLine
A handle to the open line device.
dwAddressID
An address on the line device. An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.
lpdwNumRings
The number of rings that is the minimum of all current lineSetNumRings requests.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.
lineGetProviderList
Description
The lineGetProviderList function returns a list of service providers that are currently installed in the telephony system.
Function Details
LONG WINAPI lineGetProviderList(DWORD dwAPIVersion,LPLINEPROVIDERLIST lpProviderList);Parameters
dwAPIVersion
The highest version of TAPI that the application supports (not necessarily the value that lineNegotiateAPIVersion negotiates on some particular line device).
lpProviderList
A pointer to a memory location where TAPI can return a LINEPROVIDERLIST structure. Prior to calling lineGetProviderList, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.
lineGetRequest
Description
The lineGetRequest function retrieves the next by-proxy request for the specified request mode.
Function Details
LONG WINAPI lineGetRequest(HLINEAPP hLineApp,DWORD dwRequestMode,LPVOID lpRequestBuffer);Parameters
hLineApp
The application's usage handle for the line portion of TAPI.
dwRequestMode
The type of request that is to be obtained. dwRequestMode can have only one bit set. This parameter uses one and only one of the
LINEREQUESTMODE_ Constants.lpRequestBuffer
A pointer to a memory buffer where the parameters of the request are to be placed. The size of the buffer and the interpretation of the information that is placed in the buffer depends on the request mode. The application-allocated buffer provides sufficient size to hold the request. If dwRequestMode is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer by using the LINEREQMAKECALL structure. If dwRequestMode is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer by using the LINEREQMEDIACALL structure.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALAPPHANDLE, LINEERR_NOTREGISTERED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOREQUEST.
lineGetStatusMessages
Description
The lineGetStatusMessages function enables an application to query which notification messages the application is set up to receive for events that relate to status changes for the specified line or any of its addresses.
Function Details
LONG WINAPI lineGetStatusMessages(HLINE hLine,LPDWORD lpdwLineStates,LPDWORD lpdwAddressStates);Parameters
hLine
Handle to the line device.
lpdwLineStates
A bit array that identifies for which line device status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, it is disabled. This parameter uses one or more of the LINEDEVSTATE_ Constants.
lpdwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, disabled. This parameter uses one or more of the LINEADDRESSSTATE_ Constants.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.
lineGetTranslateCaps
Description
The lineGetTranslateCaps function returns address translation capabilities.
Function Details
LONG WINAPI lineGetTranslateCaps(HLINEAPP hLineApp,DWORD dwAPIVersion,LPLINETRANSLATECAPS lpTranslateCaps);Parameters
hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwAPIVersion
The highest version of TAPI that the application supports (not necessarily the value that lineNegotiateAPIVersion negotiates on some particular line device).
lpTranslateCaps
A pointer to a location to which a LINETRANSLATECAPS structure is loaded. Prior to calling lineGetTranslateCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER.
lineHandoff
Description
The lineHandoff function gives ownership of the specified call to another application. The application can be either specified directly by its file name or indirectly as the highest priority application that handles calls of the specified media mode.
Function Details
LONG WINAPI lineHandoff(HCALL hCall,LPCSTR lpszFileName,DWORD dwMediaMode);Parameters
hCall
A handle to the call to be handed off. The application must be an owner of the call. The call state of hCall can be any state.
lpszFileName
A pointer to a null-terminated string. If this pointer parameter is non-NULL, it contains the file name of the application that is the target of the handoff. If NULL, the handoff target represents the highest priority application that has opened the line for owner privilege for the specified media mode. A valid file name does not include the path of the file.
dwMediaMode
The media mode that is used to identify the target for the indirect handoff. The dwMediaMode parameter indirectly identifies the target application that is to receive ownership of the call. This parameter gets ignored if lpszFileName is not NULL. This parameter uses one and only one of the LINEMEDIAMODE_ Constants.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return
values are:LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.
lineHold
Description
The lineHold function places the specified call on hold.
Function Details
LONG lineHold(HCALL hCall);Parameter
hCall
A handle to the call that is to be placed on hold. Ensure the application is an owner of the call and the call state of hCall is connected.
lineInitialize
Description
Although the lineInitialize function is obsolete, tapi.dll and tapi32.dll continue to export it for backward compatibility with applications that are using API versions 1.3 and 1.4.
Function Details
LONG WINAPI lineInitialize(LPHLINEAPP lphLineApp,HINSTANCE hInstance,LINECALLBACK lpfnCallback,LPCSTR lpszAppName,LPDWORD lpdwNumDevs);Parameters
lphLineApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information, see lineCallbackFunc.
lpszAppName
A pointer to a null-terminated text string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. The LINECALLINFO structure provides this name to indicate, in a user-friendly way, which application originated, originally accepted, or answered the call. This information can prove useful for call logging purposes. If lpszAppName is NULL, the application's file name gets used instead.
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location gets filled with the number of line devices that is available to the application.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.
lineInitializeEx
Description
The lineInitializeEx function initializes the use of TAPI by the application for the subsequent use of the line abstraction. It registers the specified notification mechanism of the application and returns the number of line devices that are available. A line device represents any device that provides an implementation for the line-prefixed functions in the Telephony API.
Function Details
LONG lineInitializeEx(LPHLINEAPP lphLineApp,HINSTANCE hInstance,LINECALLBACK lpfnCallback,LPCSTR lpszFriendlyAppName,LPDWORD lpdwNumDevs,LPDWORD lpdwAPIVersion,LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams);Parameters
lphLineApp
A pointer to a location that is filled with the TAPI usage handle for the application.
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 (for purposes of identifying call hand-off targets and media mode priorities).
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. This parameter gets ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a NULL-terminated ASCII string that contains only standard ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. The LINECALLINFO structure provides this name to indicate, in a user-friendly way, which application originated, originally accepted, or answered the call. This information can prove useful for call-logging purposes. If lpszFriendlyAppName is NULL, the module filename of the application gets used instead (as returned by the Windows API GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location gets filled with the number of line devices that are available to the application.
lpdwAPIVersion
A pointer to a DWORD-sized location. 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 lineNegotiateAPIVersion). Make sure that artificially high values are not used; the value must be set to 0x00020000. TAPI translates any newer messages or structures into values or formats that the application supports. Upon successful completion of this request, this location is filled with the highest API version that TAPI, 0x00020000, supports thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.
lpLineInitializeExParams
A pointer to a structure of type LINEINITIALIZEEXPARAMS that contains additional Parameters that are used to establish the association between the application and TAPI (specifically, the selected event notification mechanism of the application and associated parameters).
lineMakeCall
Description
The lineMakeCall function places a call on the specified line to the specified destination address. Optionally, you can specify call parameters if anything but default call setup parameters are requested.
Function Details
LONG lineMakeCall(HLINE hLine,LPHCALL lphCall,LPCSTR lpszDestAddress,DWORD dwCountryCode,LPLINECALLPARAMS const lpCallParams);Parameters
hLine
A handle to the open line device on which a call is to be originated.
lphCall
A pointer to an HCALL handle. The handle is only valid after the application receives LINE_REPLY message that indicates that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application initially acts as the sole owner of this call. This handle registers as void if the function returns an error (synchronously or asynchronously by the reply message).
lpszDestAddress
A pointer to the destination address. This parameter follows the standard dialable number format. This pointer can be NULL for non-dialed addresses or when all dialing is performed by using lineDial. In the latter case, lineMakeCall allocates an available call appearance that would typically remain in the dial tone state until dialing begins.
dwCountryCode
The country code of the called party. If a value of 0 is specified, the implementation uses a default.
lpCallParams
The dwNoAnswerTimeout attribute of the lpCallParams field is checked and if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.
lineMonitorDigits
Description
The lineMonitorDigits function enables and disables the unbuffered detection of digits that are received on the call. Each time that a digit of the specified digit mode is detected, a message gets sent to the application to indicate which digit has been detected.
Function Details
LONG lineMonitorDigits(HCALL hCall,DWORD dwDigitModes);Parameters
hCall
A handle to the call on which digits are to be detected. The call state of hCall can be any state except idle or disconnected.
dwDigitModes
The digit mode or modes that are to be monitored. If dwDigitModes is zero, the system cancels digit monitoring. This parameter can have multiple flags set and uses the following LINEDIGITMODE_ constant:
LINEDIGITMODE_DTMF - Detect digits as DTMF tones. Valid digits for DTMF include `0' through `9', `*', and `#'.
lineMonitorTones
Description
The lineMonitorTones function enables and disables the detection of inband tones on the call. Each time that a specified tone is detected, a message gets sent to the application.
Function Details
LONG lineMonitorTones(HCALL hCall,LPLINEMONITORTONE const lpToneList,DWORD dwNumEntries);Parameters
hCall
A handle to the call on which tones are to be detected. The call state of hCall can be any state except idle.
lpToneList
A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list to report a tone detection. Calling this operation with either NULL for lpToneList or with another tone list cancels or changes tone monitoring in progress.
dwNumEntries
The number of entries in lpToneList. This parameter gets ignored if lpToneList is NULL.
lineNegotiateAPIVersion
Description
The lineNegotiateAPIVersion function allows an application to negotiate an API version to use. The Cisco Unified CallManager TSP supports TAPI 2.0 and 2.1.
Function Details
LONG lineNegotiateAPIVersion(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAPILowVersion,DWORD dwAPIHighVersion,LPDWORD lpdwAPIVersion,LPLINEEXTENSIONID lpExtensionID);Parameters
hLineApp
The handle by which the application is registered with TAPI.
dwDeviceID
The line device to be queried.
dwAPILowVersion
The least recent API version with which the application is compliant. The high-order word specifies the major version number; the low-order word specifies the minor version number.
dwAPIHighVersion
The most recent API version with which the application is compliant. The high-order word specifies the major version number; the low-order word specifies the minor version number.
lpdwAPIVersion
A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation succeeds, this number falls in the range between dwAPILowVersion and dwAPIHighVersion.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, upon a successful negotiation, this structure gets filled with the extension identifier of these extensions. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.
The Cisco Unified CallManager TSP extensionID specifies 0x8EBD6A50, 0x138011d2, 0x905B0060, 0xB03DD275.
lineNegotiateExtVersion
Description
The lineNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified line device. You do not need to call this operation if the application does not support extensions.
Function Details
LONG lineNegotiateExtVersion(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAPIVersion,DWORD dwExtLowVersion,DWORD dwExtHighVersion,LPDWORD lpdwExtVersion);Parameters
hLineApp
The handle by which the application is registered with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The API version number that was negotiated for the specified line device by using lineNegotiateAPIVersion.
dwExtLowVersion
The least recent extension version of the extension identifier returned by lineNegotiateAPIVersion with which the application is compliant. The high-order word specifies the major version number; the low-order word specifies the minor version number.
dwExtHighVersion
The most recent extension version of the extension identifier returned by lineNegotiateAPIVersion with which the application is compliant. The high-order word specifies the major version number; the low-order word specifies the minor version number.
lpdwExtVersion
A pointer to a DWORD-sized location that contains the extension version number that was negotiated. If negotiation succeeds, this number falls between dwExtLowVersion and dwExtHighVersion.
lineOpen
Description
The lineOpen function opens the line device that its device identifier specifies and returns a line handle for the corresponding opened line device. Subsequent operations on the line device use this line handle.
Function Details
LONG lineOpen(HLINEAPP hLineApp,DWORD dwDeviceID,LPHLINE lphLine,DWORD dwAPIVersion,DWORD dwExtVersion,DWORD dwCallbackInstance,DWORD dwPrivileges,DWORD dwMediaModes,LPLINECALLPARAMS const lpCallParams);Parameters
hLineApp
The handle by which the application is registered with TAPI.
dwDeviceID
Identifies the line device to be opened. It either can be a valid device identifier or the value
LINEMAPPER
Note
lphLine
A pointer to an HLINE handle that is then loaded with the handle representing the opened line device. Use this handle to identify the device when you are invoking other functions on the open line device.
dwAPIVersion
The API version number under which the application and Telephony API operate. Obtain this number with lineNegotiateAPIVersion.
dwExtVersion
The extension version number under which the application and the service provider operate. This number remains zero if the application does not use any extensions. Obtain this number with lineNegotiateExtVersion.
dwCallbackInstance
User-instance data that is passed back to the application with each message that is associated with this line or with addresses or calls on this line. The Telephony API does not interpret this parameter.
dwPrivileges
The privilege that the application wants for the calls for which it is notified. This parameter can be a combination of the LINECALLPRIVILEGE_ constants. For applications that are using TAPI version 2.0 or later, values for this parameter can also be combined with the LINEOPENOPTION_ constants:
–
–
–
–
–
dwMediaModes
The media mode or modes of interest to the application. Use this parameter to register the application as a potential target for incoming call and call hand-off for the specified media mode. This parameter proves meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not).
This parameter uses the following LINEMEDIAMODE_ constant:
–
–
lpCallParams
The dwNoAnswerTimeout attribute of the lpCallParams field is checked and if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.
linePark
Description
The linePark function parks the specified call according to the specified park mode.
Function Details
LONG WINAPI linePark(HCALL hCall,DWORD dwParkMode,LPCSTR lpszDirAddress,LPVARSTRING lpNonDirAddress);Parameters
hCall
Handle to the call to be parked. The application must act as an owner of the call. The call state of hcall must be connected.
dwParkMode
Park mode with which the call is to be parked. This parameter can have only a single flag set and uses one of the LINEPARKMODE_Constants.
Note
lpszDirAddress
Pointer to a null-terminated string that indicates the address where the call is to be parked when directed park is used. The address specifies in dialable number format. This parameter gets ignored for nondirected park.
Note
lpNonDirAddress
Pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked gets returned in this structure. This parameter gets ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer that contains a null-terminated string), and the terminating NULL must be accounted for in the dwStringSize. Before calling linePark, the application must set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
linePrepareAddToConference
Description
The linePrepareAddToConference function prepares an existing conference call for the addition of another party.
If LINEERR_INVALLINESTATE is returned, that means that the line is currently not in a state in which this operation can be performed. The dwLineFeatures member includes a list of currently valid operations (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.)
Obtain a conference call handle with lineSetupConference or with lineCompleteTransfer that is resolved as a three-way conference call. The linePrepareAddToConference function typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with lineAddToConference.
You can cancel the consultation call by using lineDrop. You may also be able to swap an application between the consultation call and the held conference call with lineSwapHold.
Function Details
LONG WINAPI linePrepareAddToConference(HCALL hConfCall,LPHCALL lphConsultCall,LPLINECALLPARAMS const lpCallParams);Parameters
hConfCall
A handle to a conference call. The application must act as an owner of this call. The call state of hConfCall must be connected.
lphConsultCall
A pointer to an HCALL handle. This location then gets loaded with a handle that identifies the consultation call to be added. Initially, the application serves as the sole owner of this call.
lpCallParams
A pointer to call parameters that gets used when the consultation call is established. This parameter can be set to NULL if no special call setup parameters are desired.
Return Values
Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message specifies zero if the function succeeds or it is a negative error number if an error occurs.
Possible return values follow:
LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_CALLUNAVAIL, LINEERR_INVALRATE, LINEERR_CONFERENCEFULL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALMEDIAMODE, LINEERR_UNINITIALIZED.
lineRedirect
Description
The lineRedirect function redirects the specified offered or accepted call to the specified destination address.
Note
Function Details
LONG lineRedirect(HCALL hCall,LPCSTR lpszDestAddress,DWORD dwCountryCode);Parameters
hCall
A handle to the call to be redirected. The application must act as an owner of the call. The call state of hCall must be offering, accepted, or connected.
Note
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format.
dwCountryCode
The country code of the party to which the call is redirected. If a value of 0 is specified, the implementation uses a default.
lineRegisterRequestRecipient
Description
The lineRegisterRequestRecipient function registers the invoking application as a recipient of requests for the specified request mode.
Function Details
LONG WINAPI lineRegisterRequestRecipient(HLINEAPP hLineApp,DWORD dwRegistrationInstance,DWORD dwRequestMode,DWORD bEnable);Parameters
hLineApp
The application's usage handle for the line portion of TAPI.
dwRegistrationInstance
An application-specific DWORD that is passed back as a parameter of the LINE_REQUEST message. This message notifies the application that a request is pending. This parameter gets ignored if bEnable is set to zero. TAPI examines this parameter only for registration, not for deregistration. The dwRegistrationInstance value that is used while deregistering need not match the dwRegistrationInstance used while registering for a request mode.
dwRequestMode
The type or types of request for which the application registers. This parameter uses one or more LINEREQUESTMODE_ Constants.
bEnable
If TRUE, the application registers the specified request modes; if FALSE, the application deregisters for the specified request modes.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.
lineRemoveProvider
Description
The lineRemoveProvider function removes an existing telephony service provider from the telephony system.
Function Details
LONG WINAPI lineRemoveProvider(DWORD dwPermanentProviderID,HWND hwndOwner);Parameters
dwPermanentProviderID
The permanent provider identifier of the service provider that is to be removed.
hwndOwner
A handle to a window to which any dialog boxes that need to be displayed as part of the removal process (for example, a confirmation dialog box by the service provider's TSPI_providerRemove function) would be attached. The parameter can be a NULL value to indicate that any window that is created during the function should have no owner window.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.
lineSetAppPriority
Description
The lineSetAppPriority function allows an application to set its priority in the handoff priority list for a particular media type or Assisted Telephony request mode or to remove itself from the priority list.
Function Details
LONG WINAPI lineSetAppPriority(LPCSTR lpszAppFilename,DWORD dwMediaMode,LPLINEEXTENSIONID lpExtensionID,DWORD dwRequestMode,LPCSTR lpszExtensionName,DWORD dwPriority);Parameters
lpszAppFilename
A pointer to a string that contains the application executable module filename (without directory information). In TAPI version 2.0 or later, the parameter can specify a filename in either long or 8.3 filename format.
dwMediaMode
The media type for which the priority of the application is to be set. The value can be one LINEMEDIAMODE_ Constant; only a single bit may be on. Use the value zero to set the application priority for Assisted Telephony requests.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. This parameter gets ignored.
dwRequestMode
If the dwMediaMode parameter is zero, this parameter specifies the Assisted Telephony request mode for which priority is to be set. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter gets ignored if dwMediaMode is nonzero.
lpszExtensionName
This parameter gets ignored.
dwPriority
The new priority for the application. If the value 0 is passed, the application gets removed from the priority list for the specified media or request mode (if it was already not present, no error gets generated). If the value 1 is passed, the application gets inserted as the highest priority application for the media or request mode (and removed from a lower-priority position, if it was already in the list). Any other value generates an error.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER.
lineSetCallPrivilege
Description
The lineSetCallPrivilege function sets the application's privilege to the specified privilege.
Function Details
LONG WINAPI lineSetCallPrivilege(HCALL hCall,DWORD dwCallPrivilege);Parameters
hCall
A handle to the call whose privilege is to be set. The call state of hCall can be any state.
dwCallPrivilege
The privilege that the application can have for the specified call. This parameter uses one and only one LINECALLPRIVILEGE_ Constant.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLPRIVILEGE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.
lineSetNumRings
Description
The lineSetNumRings function sets the number of rings that must occur before an incoming call is answered. Use this function to implement a toll-saver-style function. It allows multiple, independent applications to each register the number of rings. The function lineGetNumRings returns the minimum number of rings that are requested. The application that answers incoming calls can use it to determine the number of rings that it should wait before answering the call.
Function Details
LONG WINAPI lineSetNumRings(HLINE hLine,DWORD dwAddressID,DWORD dwNumRings);Parameters
hLine
A handle to the open line device.
dwAddressID
An address on the line device. An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.
dwNumRings
The number of rings before a call should be answered to honor the toll-saver requests from all applications.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.
lineSetStatusMessages
Description
The lineSetStatusMessages function enables an application to specify which notification messages to receive for events that are related to status changes for the specified line or any of its addresses.
Function Details
LONG lineSetStatusMessages(HLINE hLine,DWORD dwLineStates,DWORD dwAddressStates);Parameters
hLine
A handle to the line device.
dwLineStates
A bit array that identifies for which line-device status changes a message is to be sent to the application. This parameter uses the following LINEDEVSTATE_ constants:
–
–
–
–
–
dwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. This parameter uses the following LINEADDRESSSTATE_ constant:
–
lineSetTollList
Description
The lineSetTollList function manipulates the toll list.
Function Details
LONG WINAPI lineSetTollList(HLINEAPP hLineApp,DWORD dwDeviceID,LPCSTR lpszAddressIn,DWORD dwTollListOption);Parameters
hLineApp
The application handle that lineInitializeEx returns. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so variations in dialing procedures on different lines can be applied to the translation process.
lpszAddressIn
A pointer to a null-terminated string that contains the address from which the prefix information is to be extracted for processing. This parameter must not be NULL, and it must be in the canonical address format.
dwTollListOption
The toll list operation to be performed. This parameter uses one and only one of the LINETOLLLISTOPTION_ Constants.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALAPPHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_UNINITIALIZED, LINEERR_INVALLOCATION
lineSetupConference
Description
The lineSetupConference function initiates a conference given an existing two-party call that the hCall parameter specifies. A conference call and consult call are established and the handles return to the application. Use the consult call to dial the third party and the conference call replaces the initial two-party call. The application can also specify the destination address of the consult call that will allow the PBX to dial the call for the application.
Function Details
LONG lineSetupConference (HCALL hCall,HLINE hLine,LPHCALL lphConfCall,LPHCALL lphConsultCall,DWORD dwNumParties,LPLINECALLPARAMS const lpCallParams);Parameters
hCall
The handle of the existing two-party call. The application must be the owner of the call.
hLine
The line on which the initial two-party call was made. This parameter does not get used because hCall must be set.
lphConfCall
A pointer to the conference call handle. The service provider allocates this call and returns the handle to the application.
lphConsultCall
A pointer to the consult call. If the application does not specify the destination address in the call parameters, it should use this call handle to dial the consult call. If the destination address is specified, the consult call will be made using this handle.
dwNumParties
The number of parties in the conference call. Currently the Cisco Unified TAPI Service Provider supports a three-party conference call.
lpCallParams
The call parameters that are used to set up the consult call. The application can specify the destination address if it wants the consult call to be dialed for it in the conference setup.
lineSetupTransfer
Description
The lineSetupTransfer function initiates a transfer of the call that the hCall parameter specifies. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer. The application acquires owner privilege to the lphConsultCall parameter.
Function Details
LONG lineSetupTransfer(HCALL hCall,LPHCALL lphConsultCall,LPLINECALLPARAMS const lpCallParams);Parameters
hCall
The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.
lphConsultCall
A pointer to an hCall handle. This location is then loaded with a handle that identifies the temporary consultation call. When setting up a call for transfer, a consultation call automatically gets allocated that enables lineDial to dial the address that is associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCall does not apply.
This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and remove the hold on an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. The address capabilities of the call specifies which forms of transfer are available.
lpCallParams
The dwNoAnswerTimeout attribute of the lpCallParams field is checked and, if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.
lineShutdown
Description
The lineShutdown function shuts down the usage of the line abstraction of the API.
Function Details
LONG lineShutdown(HLINEAPP hLineApp);Parameters
hLineApp
The usage handle of the application for the line API.
lineTranslateAddress
Description
The lineTranslateAddress function translates the specified address into another format.
Function Details
LONG WINAPI lineTranslateAddress(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAPIVersion,LPCSTR lpszAddressIn,DWORD dwCard,DWORD dwTranslateOptions,LPLINETRANSLATEOUTPUT lpTranslateOutput);Parameters
hLineApp
The application handle that lineInitializeEx returns. If a TAPI 2.0 application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL. TAPI 1.4 applications must still call lineInitialize first.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI that the application supports (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpszAddressIn
Pointer to a null-terminated string that contains the address from which the information is to be extracted for translation. This parameter must be in either the canonical address format or an arbitrary string of dialable digits (non-canonical). This parameter must not be NULL. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by CR and LF characters, only the first address gets translated.
dwCard
The credit card to be used for dialing. This parameter proves valid only if the CARDOVERRIDE bit is set in dwTranslateOptions. This parameter specifies the permanent identifier of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) that should be used instead of the PreferredCardID that is specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. This parameter gets ignored if the CARDOVERRIDE bit is not set in dwTranslateOptions.
dwTranslateOptions
The associated operations to be performed prior to the translation of the address into a dialable string. This parameter uses one of the LINETRANSLATEOPTION_ Constants.
Note
lpTranslateOutput
A pointer to an application-allocated memory area to contain the output of the translation operation, of type LINETRANSLATEOUTPUT. Prior to calling lineTranslateAddress, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_BADDEVICEID, LINEERR_INVALPOINTER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCARD, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM.
lineTranslateDialog
Description
The lineTranslateDialog function displays an application-modal dialog box that allows the user to change the current location of a phone number that is about to be dialed, adjust location and calling card parameters, and see the effect.
Function Details
LONG WINAPI lineTranslateDialog(HLINEAPP hLineApp,DWORD dwDeviceID,DWORD dwAPIVersion,HWND hwndOwner,LPCSTR lpszAddressIn);Parameters
hLineApp
The application handle that lineInitializeEx returns. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI that the application supports (not necessarily the value that is negotiated by lineNegotiateAPIVersion on the line device that is indicated by dwDeviceID).
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window that is created during the function should have no owner window.
lpszAddressIn
A pointer to a null-terminated string that contains a phone number that is used, in the lower portion of the dialog box, to show the effect of the user's changes on the location parameters. The number must be in canonical format; if noncanonical, the phone number portion of the dialog box does not display. This pointer can be left NULL, in which case the phone number portion of the dialog box does not display. If the lpszAddressIn parameter contains a subaddress or name field, or additional addresses separated from the first address by CR and LF characters, only the first address gets used in the dialog box.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.
lineUnhold
Description
The lineUnhold function retrieves the specified held call.
Function Details
LONG lineUnhold(HCALL hCall);Parameters
hCall
The handle to the call to be retrieved. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer, or onHoldPendingConference.
lineUnpark
Description
The lineUnpark function retrieves the call that is parked at the specified address and returns a call handle for it.
Function Details
LONG WINAPI lineUnpark(HLINE hLine,DWORD dwAddressID,LPHCALL lphCall,LPCSTR lpszDestAddress);Parameters
hLine
Handle to the open line device on which a call is to be unparked.
dwAddressID
Address on hLine at which the unpark is to be originated. An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.
lphCall
Pointer to the location of type HCALL where the handle to the unparked call is returned. This handle is unrelated to any other handle that previously may have been associated with the retrieved call, such as the handle that might have been associated with the call when it was originally parked. The application acts as the initial sole owner of this call.
lpszDestAddress
Pointer to a null-terminated character buffer that contains the address where the call is parked. The address displays in standard dialable address format.
TAPI Line Messages
This section describes the line messages that the CiscoTSP supports and does not support. These messages notify the application of asynchronous events such as a new call arriving in the Cisco Unified CallManager. The messages get sent to the application using the method that the application specifies in lineInitializeEx.
.LINE_ADDRESSSTATE
Description
The LINE_ADDRESSSTATE message gets sent when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.
Function Details
LINE_ADDRESSSTATUSdwDevice = (DWORD) hLine;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) idAddress;dwParam2 = (DWORD) AddressState;dwParam3 = (DWORD) 0;Parameters
dwDevice
A handle to the line device.
dwCallbackInstance
The callback instance that supplied when the line is opened.
dwParam1
The address identifier of the address that changed status.
dwParam2
The address state that changed. Can be a combination of these values:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below changed. The application should check the current address status to determine which items changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status changed.
LINEADDRESSSTATE_INUSEZERO
The address changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address changed from idle or from being used by many bridged stations to being used by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address changed from being used by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This change results from events such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address changed, including the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address changed.
LINEADDRESSSTATE_CAPSCHANGE
Indicates that due to configuration changes that the user made, or other circumstances, one or more of the members in the LINEADDRESSCAPS structure for the address changed. The application should use lineGetAddressCaps to read the updated structure. Applications that support API versions earlier than 1.4 receive a LINEDEVSTATE_REINIT message that requires them to shut down and reinitialize their connection to TAPI to obtain the updated information.
dwParam3
Not used.
LINE_APPNEWCALL
Description
The LINE_APPNEWCALL message informs an application when a new call handle was spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter that was passed into the function).
Function Details
LINE_APPNEWCALLdwDevice = (DWORD) hLine;dwCallbackInstance = (DWORD) dwInstanceData;dwParam1 = (DWORD) dwAddressID;dwParam2 = (DWORD) hCall;dwParam3 = (DWORD) dwPrivilege;Parameters
dwDevice
The handle of the application to the line device on which the call was created.
dwCallbackInstance
The callback instance that is supplied when the line belonging to the call is opened.
dwParam1
Identifier of the address on the line on which the call appears.
dwParam2
The handle of the application to the new call.
dwParam3
The privilege of the application to the new call (LINECALLPRIVILEGE_OWNER or LINECALLPRIVILEGE_MONITOR).
LINE_CALLDEVSPECIFIC
Description
The LINE_CALLDEVSPECIFIC message is sent to notify TAPI about device-specific events occurring on a call. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.
Function Details
LINE_CALLDEVSPECIFIChtLine = (HTAPILINE) hLineDevice;htCall = (HTAPICALL) hCallDevice;dwMsg = (DWORD) LINE_CALLDEVSPECIFIC;dwParam1 = (DWORD) DeviceData1;dwParam2 = (DWORD) DeviceData2;dwParam3 = (DWORD) DeviceData3;Parameters
htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLDEVSPECIFIC.
dwParam1
Device specific
dwParam2
Device specific
dwParam3
Device specific
LINE_CALLINFO
Description
The TAPI LINE_CALLINFO message gets sent when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.
Function Details
LINE_CALLINFOhDevice = (DWORD) hCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) CallInfoState;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
hDevice
A handle to the call.
dwCallbackInstance
The callback instance that is supplied when the call's line is opened.
dwParam1
The call information item that changed. Can be one or more of the
LINECALLINFOSTATE_ constants.dwParam2
Not used.
dwParam3
Not used.
LINE_CALLSTATE
Description
The LINE_CALLSTATE message gets sent when the status of the specified call changed. Typically, several such messages are received during the lifetime of a call. Applications get notified of new incoming calls with this message; the new call is in the offering state. The application can use the lineGetCallStatus function to retrieve more detailed information about the current status of the call.
Function Details
LINE_CALLSTATEdwDevice = (DWORD) hCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) CallState;dwParam2 = (DWORD) CallStateDetail;dwParam3 = (DWORD) CallPrivilege;Parameters
dwDevice
A handle to the call.
dwCallbackInstance
The callback instance that is supplied when the line belonging to this call is opened.
dwParam1
The new call state. CiscoTSP only supports the following call state values:
–
–
–
–
–
–
–
–
–
–
–
–
–
–
Note
dwParam2
Call-state-dependent information.
If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:
–
–
When a call is disconnected with cause code = DISCONNECTMODE_TEMPFAILURE and the lineState = LINEDEVSTATE_INSERVICE, applications must take care of dropping the call. If the application is terminating media for a device, then it is also the responsibility of the application to stop the RTP streams for the same call. TSP will not provide Stop Transmission/Reception events to applications in this scenario. The behavior is exactly same with IP Phones. The User needs to hang up the disconnected - temp fail call on IPPhone to stop the media. The application is also responsible for stopping the RTP streams in case the line goes out of service (LINEDEVSTATE_OUTOFSERVICE) and the call on a line is reported as IDLE.
Note
If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constant:
–
If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:
–
Note
If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:
–
–
–
–
–
–
–
–
Note
dwParam3
If zero, this parameter indicates that there has been no change in the privilege for the call to this application.
If nonzero, this parameter specifies the privilege for the application to the call. This occurs in the following situations: (1) The first time that the application receives a handle to this call; (2) When the application is the target of a call hand-off (even if the application already was an owner of the call). This parameter uses the following LINECALLPRIVILEGE_ constants:
–
–
LINE_CLOSE
Description
The LINE_CLOSE message gets sent when the specified line device has been forcibly closed. The line device handle or any call handles for calls on the line are no longer valid after this message has been sent.
Function Details
LINE_CLOSEdwDevice = (DWORD) hLine;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) 0;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
dwDevice
A handle to the line device that was closed. This handle is no longer valid.
dwCallbackInstance
The callback instance that is supplied when the line belonging to this call is opened.
dwParam1
Not used.
dwParam2
Not used.
dwParam3
Not used.
LINE_CREATE
Description
The LINE_CREATE message informs the application of the creation of a new line device.
Note
Function Details
LINE_CREATEdwDevice = (DWORD) 0;dwCallbackInstance = (DWORD) 0;dwParam1 = (DWORD) idDevice;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
dwDevice
Not used.
dwCallbackInstance
Not used.
dwParam1
The dwDeviceID of the newly created device.
dwParam2
Not used.
dwParam3
Not used.
LINE_DEVSPECIFIC
Description
The LINE_DEVSPECIFIC message notifies the application about device-specific events that are occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.
Function Details
LINE_DEVSPECIFICdwDevice = (DWORD) hLineOrCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) DeviceSpecific1;dwParam2 = (DWORD) DeviceSpecific2;dwParam3 = (DWORD) DeviceSpecific3;Parameters
dwDevice
A handle to either a line device or call. This is device specific.
dwCallbackInstance
The callback instance that is supplied when the line is opened.
dwParam1
Device specific
dwParam2
Device specific
dwParam3
Device specific
LINE_GENERATE
Description
The TAPI LINE_GENERATE message notifies the application that the current digit or tone generation terminated. Only one such generation request can be in progress an a given call at any time. This message also gets sent when digit or tone generation is canceled.
Function Details
LINE_GENERATEhDevice = (DWORD) hCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) GenerateTermination;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
hDevice
A handle to the call.
dwCallbackInstance
The callback instance that is supplied when the line is opened.
dwParam1
The reason that digit or tone generation terminated. This parameter must be one and only one of the LINEGENERATETERM_ constants.
dwParam2
Not used.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the digit or tone generation completed. For API versions earlier than 2.0, this parameter does not get used.
LINE_LINEDEVSTATE
Description
The TAPI LINE_LINEDEVSTATE message gets sent when the state of a line device changes. The application can invoke lineGetLineDevStatus to determine the new status of the line.
Function Details
LINE_LINEDEVSTATEhDevice = (DWORD) hLine;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) DeviceState;dwParam2 = (DWORD) DeviceStateDetail1;dwParam3 = (DWORD) DeviceStateDetail2;Parameters
hDevice
A handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.
dwCallbackInstance
The callback instance that is supplied when the line is opened. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.
dwParam1
The line device status item that changed. The parameter can be one or more of the LINEDEVSTATE_ constants.
dwParam2
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes include numbers in the range one to dwNumRingModes, where dwNumRingModes specifies a line device capability.
If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.
dwParam3
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.
If dwParam1 is LINEDEVSTATE_REINIT, and TAPI issued the message as a result of translation of a new API message into a REINIT message, dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).
LINE_MONITORDIGITS
Description
The LINE_MONITORDIGITS message gets sent when a digit is detected. The lineMonitorDigits function controls the sending of this message.
Function Details
LINE_MONITORDIGITSdwDevice = (DWORD) hCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) Digit;dwParam2 = (DWORD) DigitMode;dwParam3 = (DWORD) 0;Parameters
dwDevice
A handle to the call.
dwCallbackInstance
The callback instance that is supplied when the line for this call is opened.
dwParam1
The low-order byte contains the last digit that is received in ASCII.
dwParam2
The digit mode that was detected. This parameter must be one and only one of the following LINEDIGITMODE_ constant:
–
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified digit was detected. For API versions earlier than 2.0, this parameter does not get used.
LINE_MONITORTONE
Description
The LINE_MONITORTONE message gets sent when a tone is detected. The lineMonitorTones function controls the sending of this message.
Note
Function Details
LINE_MONITORTONEdwDevice = (DWORD) hCall;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) dwAppSpecific;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) tick count;Parameters
dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line for this call.
dwParam1
The application-specific dwAppSpecific member of the LINEMONITORTONE structure for the tone that was detected.
dwParam2
Not used.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified digit was detected.
LINE_REMOVE
Description
The LINE_REMOVE message informs an application of the removal (deletion from the system) of a line device. Generally, this parameter does not get 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 reinitialized.
Note
Function Details
LINE_REMOVEdwDevice = (DWORD) 0;dwCallbackInstance = (DWORD) 0;dwParam1 = (DWORD) dwDeviceID;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
dwDevice
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the line device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.
LINE_REPLY
Description
The LINE_REPLY message reports the results of function calls that completed asynchronously.
Function Details
LINE_REPLYdwDevice = (DWORD) 0;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) idRequest;dwParam2 = (DWORD) Status;dwParam3 = (DWORD) 0;Parameters
dwDevice
Not used.
dwCallbackInstance
Returns the callback instance for this application.
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 integer:
–
–
dwParam3
Not used.
LINE_REQUEST
Description
The TAPI LINE_REQUEST message reports the arrival of a new request from another application.
Function Details
LINE_REQUESThDevice = (DWORD) 0;dwCallbackInstance = (DWORD) hRegistration;dwParam1 = (DWORD) RequestMode;dwParam2 = (DWORD) RequestModeDetail1;dwParam3 = (DWORD) RequestModeDetail2;Parameters
hDevice
Not used.
dwCallbackInstance
The registration instance of the application that is specified on lineRegisterRequestRecipient.
dwParam1
The request mode of the newly pending request. This parameter uses the LINEREQUESTMODE_ constants.
dwParam2
If dwParam1 is set to LINEREQUESTMODE_DROP, dwParam2 contains the hWnd of the application that requests the drop. Otherwise, dwParam2 does not get used.
dwParam3
If dwParam1 is set to LINEREQUESTMODE_DROP, the low-order word of dwParam3 contains the wRequestID as specified by the application requesting the drop. Otherwise,
dwParam3 is not used.
TAPI Line Structures
This section describes the TAPI line device structures, shown in Table 2-3, that the Cisco Unified CallManager TSP supports and does not support, lists the possible values for the structure members as set by the CiscoTSP, and provides a cross reference to the functions that use them. If the value of a structure member is device, line, or call specific, the system notes the value for each condition.
LINEADDRESSCAPS
LINEADDRESSSTATUS
LINEAPPINFO
Description
The LINEAPPINFO structure contains information about the application that is currently running. The LINEDEVSTATUS structure can contain an array of LINEAPPINFO structures.
Structure Details
typedef struct lineappinfo_tag {DWORD dwMachineNameSize;DWORD dwMachineNameOffset;DWORD dwUserNameSize;DWORD dwUserNameOffset;DWORD dwModuleFilenameSize;DWORD dwModuleFilenameOffset;DWORD dwFriendlyNameSize;DWORD dwFriendlyNameOffset;DWORD dwMediaModes;DWORD dwAddressID;} LINEAPPINFO, *LPLINEAPPINFO;Members
dwMachineNameSize
dwMachineNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string that specifies the name of the computer on which the application is executing.
dwUserNameSize
dwUserNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string that specifies the user name under whose account the application is running.
dwModuleFilenameSize
dwModuleFilenameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string that specifies the module filename of the application. You can use this string in a call to lineHandoff to perform a directed handoff to the application.
dwFriendlyNameSize
dwFriendlyNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of the string that the application provides to lineInitialize or lineInitializeEx, which should be used in any display of applications to the user.
dwMediaModes
The media types for which the application has requested ownership of new calls; zero if the line dwPrivileges did not include LINECALLPRIVILEGE_OWNER when it opened.
dwAddressID
If the line handle that was opened by using LINEOPENOPTION_SINGLEADDRESS contains the address identifier specified set to 0xFFFFFFFF if the single address option was not used.
An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.
LINECALLINFO
LINECALLLIST
Description
The LINECALLLIST structure describes a list of call handles. The lineGetNewCalls and lineGetConfRelatedCalls functions return a structure of this type.
Note
Structure Details
typedef struct linecalllist_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwCallsNumEntries;DWORD dwCallsSize;DWORD dwCallsOffset;} LINECALLLIST, FAR *LPLINECALLLIST;Members
dwTotalSize
The total size, in bytes, that is 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.
dwCallsNumEntries
The number of handles in the hCalls array.
dwCallsSize
dwCallsOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field (which is an array of HCALL-sized handles).
LINECALLPARAMS
LINECALLSTATUS
LINECARDENTRY
Description
The LINECARDENTRY structure describes a calling card. The LINETRANSLATECAPS structure can contain an array of LINECARDENTRY structures.
Note
Structure Details
typedef struct linecardentry_tag {DWORD dwPermanentCardID;DWORD dwCardNameSize;DWORD dwCardNameOffset;DWORD dwCardNumberDigits;DWORD dwSameAreaRuleSize;DWORD dwSameAreaRuleOffset;DWORD dwLongDistanceRuleSize;DWORD dwLongDistanceRuleOffset;DWORD dwInternationalRuleSize;DWORD dwInternationalRuleOffset;DWORD dwOptions;} LINECARDENTRY, FAR *LPLINECARDENTRY;Members
dwPermanentCardID
The permanent identifier that identifies the card.
dwCardNameSize
dwCardNameOffset
Contains a null-terminated string (size includes the NULL) that describes the card in a user-friendly manner.
dwCardNumberDigits
The number of digits in the existing card number. The card number itself does not get returned for security reasons (TAPI stores it in scrambled form). The application can use this parameter to insert filler bytes into a text control in "password" mode to show that a number exists.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the same area code. The rule specifies a null-terminated string.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule that is defined for calls to numbers in the other areas in the same country or region. The rule specifies a null-terminated string.
dwInternationalRuleSize
dwInternationalRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule that is defined for calls to numbers in other countries/regions. The rule specifies a null-terminated string.
dwOptions
Indicates other settings that are associated with this calling card, using the LINECARDOPTION_
LINECOUNTRYENTRY
Description
The LINECOUNTRYENTRY structure provides the information for a single country entry. An array of one or more of these structures makes up part of the LINECOUNTRYLIST structure that the lineGetCountry function returns.
Note
Structure Details
typedef struct linecountryentry_tag {DWORD dwCountryID;DWORD dwCountryCode;DWORD dwNextCountryID;DWORD dwCountryNameSize;DWORD dwCountryNameOffset;DWORD dwSameAreaRuleSize;DWORD dwSameAreaRuleOffset;DWORD dwLongDistanceRuleSize;DWORD dwLongDistanceRuleOffset;DWORD dwInternationalRuleSize;DWORD dwInternationalRuleOffset;} LINECOUNTRYENTRY, FAR *LPLINECOUNTRYENTRY;Members
dwCountryID
The country or region identifier of the entry. The country or region identifier specifies an internal identifier that allows multiple entries to exist in the country or region list with the same country code (for example, all countries in North America and the Caribbean share country code 1 but require separate entries in the list).
dwCountryCode
The actual country code of the country or region that the entry represents (that is, the digits that would be dialed in an international call). Only this value should ever display to users (country identifiers should never display, as they could be confusing).
dwNextCountryID
The country identifier of the next entry in the country or region list. Because country codes and identifiers are not assigned in any regular numeric sequence, the country or region list represents a single linked list, with each entry pointing to the next. The last country or region in the list has a dwNextCountryID value of zero. When the LINECOUNTRYLIST structure is used to obtain the entire list, the entries in the list appear in sequence as linked by their dwNextCountryID members.
dwCountryNameSize
dwCountryNameOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string that gives the name of the country or region.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string that contains the dialing rule for direct-dialed calls to the same area code.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string that contains the dialing rule for direct-dialed calls to other areas in the same country or region.
dwInternationalRuleSize
dwInternationalRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string that contains the dialing rule for direct-dialed calls to other countries/regions.
LINECOUNTRYLIST
Description
The LINECOUNTRYLIST structure describes a list of countries/regions. This structure can contain an array of LINECOUNTRYENTRY structures. The lineGetCountry function returns LINECOUNTRYLIST.
Note
Structure Details
typedef struct linecountrylist_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwNumCountries;DWORD dwCountryListSize;DWORD dwCountryListOffset;} LINECOUNTRYLIST, FAR *LPLINECOUNTRYLIST;Members
dwTotalSize
The total size, in bytes, that are 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.
dwNumCountries
The number of LINECOUNTRYENTRY structures that are present in the array dwCountryListSize and dwCountryListOffset dominate.
dwCountryListSize
dwCountryListOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of an array of LINECOUNTRYENTRY elements that provide the information on each country or region.
LINEDEVCAPS
LINEDEVSTATUS
LINEEXTENSIONID
dwExtensionID0
For All Devices:
0x8EBD6A50dwExtensionID1
For All Devices:
0x128011D2dwExtensionID2
For All Devices:
0x905B0060dwExtensionID3
For All Devices:
0xB03DD275
LINEFORWARD
Description
The LINEFORWARD structure describes an entry of the forwarding instructions.
Structure Details
typedef struct lineforward_tag {DWORD dwForwardMode;DWORD dwCallerAddressSize;DWORD dwCallerAddressOffset;DWORD dwDestCountryCode;DWORD dwDestAddressSize;DWORD dwDestAddressOffset;} LINEFORWARD, FAR *LPLINEFORWARD;Members
dwForwardMode
The types of forwarding. The dwForwardMode member can have only a single bit set. This member uses the following LINEFORWARDMODE_ constants:
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no-answer conditions.
Note
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Unconditionally forward all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls both on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward on busy all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy or no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on both busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy or no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy or no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward on busy or no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_UNKNOWN
Calls get forwarded, but the conditions under which forwarding occurs are not known at this time.
LINEFORWARDMODE_UNAVAIL
Calls are forwarded, but the conditions under which forwarding occurs are not known and are never known by the service provider.
dwCallerAddressSize
dwCallerAddressOffset
The size in bytes of the variably sized address field that contains the address of a caller to be forwarded and the offset in bytes from the beginning of the containing data structure. The dwCallerAddressSize/Offset member gets set to zero if dwForwardMode is not one of the following choices:
LINEFORWARDMODE_BUSYNASPECIFIC, LINEFORWARDMODE_NOANSWSPECIFIC, LINEFORWARDMODE_UNCONDSPECIFIC, or LINEFORWARDMODE_BUSYSPECIFIC.dwDestCountryCode
The country code of the destination address to which the call is to be forwarded.
dwDestAddressSize
dwDestAddressOffset
The size in bytes of the variably sized address field that contains the address of the address where calls are to be forwarded and the offset in bytes from the beginning of the containing data structure.
LINEFORWARDLIST
Description
The LINEFORWARDLIST structure describes a list of forwarding instructions.
Structure Details
typedef struct lineforwardlist_tag {DWORD dwTotalSize;DWORD dwNumEntries;LINEFORWARD ForwardList[1];} LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;Members
dwTotalSize
The total size in bytes of the data structure.
dwNumEntries
Number of entries in the array that is specified as ForwardList[ ].
ForwardList[ ]
An array of forwarding instruction. The array entries specify type LINEFORWARD.
LINEGENERATETONE
Description
The LINEGENERATETONE structure contains information about a tone to be generated. The lineGenerateTone and TSPI_lineGenerateTone functions use this structure.
Note
This structure gets used only for the generation of tones; it does not get used for tone monitoring.
Structure Details
typedef struct linegeneratetone_tag {DWORD dwFrequency;DWORD dwCadenceOn;DWORD dwCadenceOff;DWORD dwVolume;} LINEGENERATETONE, FAR *LPLINEGENERATETONE;Members
dwFrequency
The frequency, in hertz, of this tone component. A service provider may adjust (round up or down) the frequency that the application specified to fit its resolution.
dwCadenceOn
The "on" duration, in milliseconds, of the cadence of the custom tone to be generated. Zero means no tone gets generated.
dwCadenceOff
The "off" duration, in milliseconds, of the cadence of the custom tone to be generated. Zero means no off time, that is, a constant tone.
dwVolume
The volume level at which the tone gets generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 means silence.
LINEINITIALIZEEXPARAMS
Description
The LINEINITIZALIZEEXPARAMS structure describes parameters that are supplied when calls are made using LINEINITIALIZEEX.
Structure Details
typedef struct lineinitializeexparams_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwOptions;union{HANDLE hEvent;HANDLE hCompletionPort;} Handles;DWORD dwCompletionKey;} LINEINITIALIZEEXPARAMS, FAR *LPLINEINITIALIZEEXPARAMS;Members
dwTotalSize
The total size, in bytes, that is 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.
dwOptions
One of the LINEINITIALIZEEXOPTION_ Constants. Specifies the event notification mechanism that the application wants to use.
hEvent
If dwOptions specifies LINEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this field.
hCompletionPort
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field the handle of an existing completion port that was opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.
Further Details
See "lineInitializeEx" for further information on these options.
LINELOCATIONENTRY
Description
The LINELOCATIONENTRY structure describes a location that is used to provide an address translation context. The LINETRANSLATECAPS structure can contain an array of LINELOCATIONENTRY structures.
Note
Structure Details
typedef struct linelocationentry_tag {DWORD dwPermanentLocationID;DWORD dwLocationNameSize;DWORD dwLocationNameOffset;DWORD dwCountryCode;DWORD dwCityCodeSize;DWORD dwCityCodeOffset;DWORD dwPreferredCardID;DWORD dwLocalAccessCodeSize;DWORD dwLocalAccessCodeOffset;DWORD dwLongDistanceAccessCodeSize;DWORD dwLongDistanceAccessCodeOffset;DWORD dwTollPrefixListSize;DWORD dwTollPrefixListOffset;DWORD dwCountryID;DWORD dwOptions;DWORD dwCancelCallWaitingSize;DWORD dwCancelCallWaitingOffset;} LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;Members
dwPermanentLocationID
The permanent identifier that identifies the location.
dwLocationNameSize
dwLocationNameOffset
Contains a null-terminated string (size includes the NULL) that describes the location in a user-friendly manner.
dwCountryCode
The country code of the location.
dwPreferredCardID
The preferred calling card when dialing from this location.
dwCityCodeSize
dwCityCodeOffset
Contains a null-terminated string that specifies the city or area code that is associated with the location (the size includes the NULL). Applications can use this information, along with the country code, to "default" entry fields for the user when you enter the phone numbers, to encourage the entry of proper canonical numbers.
dwLocalAccessCodeSize
dwLocalAccessCodeOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string that contains the access code to be dialed before calls to addresses in the local calling area.
dwLongDistanceAccessCodeSize
dwLongDistanceAccessCodeOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string that contains the access code to be dialed before calls to addresses outside the local calling area.
dwTollPrefixListSize
dwTollPrefixListOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string that contains the toll prefix list for the location. The string contains only prefixes that consist of the digits "0" through "9" and are separated from each other by a single "," (comma) character.
dwCountryID
The country identifier of the country or region that is selected for the location. Use this identifier with the lineGetCountry function to obtain additional information about the specific country or region, such as the country or region name (the dwCountryCode member cannot be used for this purpose because country codes are not unique).
dwOptions
Indicates options in effect for this location with values taken from the
LINELOCATIONOPTION_ Constants.dwCancelCallWaitingSize
dwCancelCallWaitingOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string that contains the dial digits and modifier characters that should be prefixed to the dialable string (after the pulse/tone character) when an application sets the LINETRANSLATEOPTION_CANCELCALLWAITING bit in the dwTranslateOptions parameter of lineTranslateAddress. If no prefix is defined, dwCancelCallWaitingSize being set to zero may indicate this, or it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single NULL byte) may indicate this.
LINEMESSAGE
Description
The LINEMESSAGE structure contains parameter values that specify a change in status of the line that the application currently has open. The lineGetMessage function returns the LINEMESSAGE structure.
Structure Details
typedef struct linemessage_tag {DWORD hDevice;DWORD dwMessageID;DWORD_PTR dwCallbackInstance;DWORD_PTR dwParam1;DWORD_PTR dwParam2;DWORD_PTR dwParam3;} LINEMESSAGE, FAR *LPLINEMESSAGE;Members
hDevice
A handle to either a line device or a call. The context that is provided by dwMessageID can determine the nature of this handle (line handle or call handle).
dwMessageID
A line or call device message.
dwCallbackInstance
Instance data passed back to the application, which the application in the dwCallBackInstance parameter of lineInitializeEx specified. TAPI does not interpret this DWORD.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.
Further Details
For details about the parameter values that are passed in this structure, see "TAPI Line Messages."
LINEMONITORTONE
Description
The LINEMONITORTONE structure defines a tone for the purpose of detection. Use this as an entry in an array. An array of tones gets passed to the lineMonitorTones function that monitors these tones and sends a LINE_MONITORTONE message to the application when a detection is made.
A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call information stream for silence.
Note
Structure Details
typedef struct linemonitortone_tag {DWORD dwAppSpecific;DWORD dwDuration;DWORD dwFrequency1;DWORD dwFrequency2;DWORD dwFrequency3;} LINEMONITORTONE, FAR *LPLINEMONITORTONE;Members
dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member gets passed back to the application.
dwDuration
The duration, in milliseconds, during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency, in hertz, of a component of the tone. If fewer than three frequencies are needed in the tone, a value of 0 should be used for the unused frequencies. A tone with all three frequencies set to zero gets interpreted as silence and can be used for silence detection.
LINEPROVIDERENTRY
Description
The LINEPROVIDERENTRY structure provides the information for a single service provider entry. An array of these structures gets returned as part of the LINEPROVIDERLIST structure that the function lineGetProviderList returns.
Note
Structure Details
typedef struct lineproviderentry_tag {DWORD dwPermanentProviderID;DWORD dwProviderFilenameSize;DWORD dwProviderFilenameOffset;} LINEPROVIDERENTRY, FAR *LPLINEPROVIDERENTRY;Members
dwPermanentProviderID
The permanent provider identifier of the entry.
dwProviderFilenameSize
dwProviderFilenameOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINEPROVIDERLIST structure of a null-terminated string that contains the filename (path) of the service provider DLL (.TSP) file.
LINEPROVIDERLIST
Description
The LINEPROVIDERLIST structure describes a list of service providers. The lineGetProviderList function returns a structure of this type. The LINEPROVIDERLIST structure can contain an array of LINEPROVIDERENTRY structures.
Note
Structure Details
typedef struct lineproviderlist_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwNumProviders;DWORD dwProviderListSize;DWORD dwProviderListOffset;} LINEPROVIDERLIST, FAR *LPLINEPROVIDERLIST;Members
dwTotalSize
The total size, in bytes, that are 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.
dwNumProviders
The number of LINEPROVIDERENTRY structures that are present in the array that is denominated by dwProviderListSize and dwProviderListOffset.
dwProviderListSize
dwProviderListOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of an array of LINEPROVIDERENTRY elements, which provide the information on each service provider.
LINEREQMAKECALL
Description
The LINEREQMAKECALL structure describes a request that is initiated by a call to the lineGetRequest function.
Note
Structure Details
typedef struct linereqmakecall_tag {char szDestAddress[TAPIMAXDESTADDRESSSIZE];char szAppName[TAPIMAXAPPNAMESIZE];char szCalledParty[TAPIMAXCALLEDPARTYSIZE];char szComment[TAPIMAXCOMMENTSIZE];} LINEREQMAKECALL, FAR *LPLINEREQMAKECALL;Members
szDestAddress[TAPIMAXADDRESSSIZE]
The null-terminated destination address of the make-call request. The address uses the canonical address format or the dialable address format. The maximum length of the address specifies TAPIMAXDESTADDRESSSIZE characters, which include the NULL terminator. Longer strings get truncated.
szAppName[TAPIMAXAPPNAMESIZE]
The null-terminated, user-friendly application name or filename of the application that originated the request. The maximum length of the address specifies TAPIMAXAPPNAMESIZE characters, which include the NULL terminator.
szCalledParty[TAPIMAXCALLEDPARTYSIZE]
The null-terminated, user-friendly called-party name. The maximum length of the called-party information specifies TAPIMAXCALLEDPARTYSIZE characters, which include the NULL terminator.
szComment[TAPIMAXCOMMENTSIZE]
The null-terminated comment about the call request. The maximum length of the comment string specifies TAPIMAXCOMMENTSIZE characters, which include the NULL terminator.
LINETRANSLATECAPS
Description
The LINETRANSLATECAPS structure describes the address translation capabilities. This structure can contain an array of LINELOCATIONENTRY structures and an array of LINECARDENTRY structures. the lineGetTranslateCaps function returns the LINETRANSLATECAPS structure.
Note
Structure Details
typedef struct linetranslatecaps_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwNumLocations;DWORD dwLocationListSize;DWORD dwLocationListOffset;DWORD dwCurrentLocationID;DWORD dwNumCards;DWORD dwCardListSize;DWORD dwCardListOffset;DWORD dwCurrentPreferredCardID;} LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;Members
dwTotalSize
The total size, in bytes, that is 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.
dwNumLocations
The number of entries in the location list. It includes all locations that are defined, including zero (default).
dwLocationListSize
dwLocationListOffset
List of locations that are known to the address translation. The list comprises a sequence of LINELOCATIONENTRY structures. The dwLocationListOffset member points to the first byte of the first LINELOCATIONENTRY structure, and the dwLocationListSize member indicates the total number of bytes in the entire list.
dwCurrentLocationID
The dwPermanentLocationID member from the LINELOCATIONENTRY structure for the CurrentLocation.
dwNumCards
The number of entries in the CardList.
dwCardListSize
dwCardListOffset
List of calling cards that are known to the address translation. It includes only non-hidden card entries and always includes card 0 (direct dial). The list comprises a sequence of LINECARDENTRY structures. The dwCardListOffset member points to the first byte of the first LINECARDENTRY structure, and the dwCardListSize member indicates the total number of bytes in the entire list.
dwCurrentPreferredCardID
The dwPreferredCardID member from the LINELOCATIONENTRY structure for the CurrentLocation.
LINETRANSLATEOUTPUT
Description
The LINETRANSLATEOUTPUT structure describes the result of an address translation. The lineTranslateAddress function uses this structure.
Note
Structure Details
typedef struct linetranslateoutput_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwDialableStringSize;DWORD dwDialableStringOffset;DWORD dwDisplayableStringSize;DWORD dwDisplayableStringOffset;DWORD dwCurrentCountry;DWORD dwDestCountry;DWORD dwTranslateResults;} LINETRANSLATEOUTPUT, FAR *LPLINETRANSLATEOUTPUT;Members
dwTotalSize
The total size, in bytes, that is 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.
dwDialableStringSize
dwDialableStringOffset
Contains the translated output that can be passed to the lineMakeCall, lineDial, or other function that requires a dialable string. The output always comprises a null-terminated string (NULL gets included in the count in dwDialableStringSize). This output string includes ancillary fields such as name and subaddress if they were in the input string. This string may contain private information such as calling card numbers. To prevent inadvertent visibility to unauthorized persons, it should not display to the user.
dwDisplayableStringSize
dwDisplayableStringOffset
Contains the translated output that can display to the user for confirmation. Identical to DialableString, except the "friendly name" of the card enclosed within bracket characters (for example, "[AT&T Card]") replaces calling card digits. The ancillary fields, such as name and subaddress, get removed. You can display this string in call-status dialog boxes without exposing private information to unauthorized persons. You can also include this information in call logs.
dwCurrentCountry
Contains the country code that is configured in CurrentLocation. Use this value to control the display by the application of certain user interface elements for local call progress tone detection and for other purposes.
dwDestCountry
Contains the destination country code of the translated address. This value may pass to the dwCountryCode parameter of lineMakeCall and other dialing functions (so the call progress tones of the destination country or region are properly detected). This field gets set to zero if the destination address that is passed to lineTranslateAddress is not in canonical format.
dwTranslateResults
Indicates the information that is derived from the translation process, which may assist the application in presenting user-interface elements. This field uses one LINETRANSLATERESULT_.
TAPI Phone Functions
TAPI phone functions enable an application to control physical aspects of a phone. Table 2-4 lists the TAPI phone funtions that CiscoTSP supports and does not support.
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.
Further Details
For more information about the parameters that are passed to this callback function, see "TAPI Line Messages" and "TAPI Phone Messages."
phoneClose
Description
The phoneClose function closes the specified open phone device.
Function Details
LONG phoneClose(HPHONE hPhone);Parameter
hPhone
A handle to the open phone device that is to be closed. If the function succeeds, the handle is no longer valid.
phoneDevSpecific
Description
The phoneDevSpecific function gets used as a general extension mechanism to enable a Telephony API implementation to provide features that are not described in the other TAPI functions. The meanings of these extensions are device specific.
When used with the Cisco Unified CallManager TSP, phoneDevSpecific can be used to send device specific data to a phone device.
Function Details
LONG WINAPI phoneDevSpecific (HPHONE hPhone,LPVOID lpParams,DWORD dwSize);Parameter
hPhone
A handle to a phone device.
lpParams
A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The contents of the parameter block are passed unchanged to or from the service provider by TAPI.
dwSize
The size in bytes of the parameter block area.
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.
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.
phoneGetLamp
Description
The phoneGetLamp function returns the current lamp mode of the specified lamp.
Note
Function Details
LONG phoneGetLamp(HPHONE hPhone,DWORD dwButtonLampID,LPDWORD lpdwLampMode);Parameters
hPhone
A handle to the open phone device.
dwButtonLampID
The identifier of the lamp that is to be queried. See Table 2-7, "Phone Button Values" for lamp IDs.
lpdwLampMode
Note
A pointer to a memory location that holds the lamp mode status of the given lamp. The lpdwLampMode parameter can have at most one bit set. This parameter uses the following PHONELAMPMODE_ constants:
–
–
–
–
–
–
–
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 WINAPI 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 if 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
Returns zero if the request succeeds or a negative error number if an error occurs. 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.
The system supports four ring modes.
Table 2-5 lists the valid ring modes.
lpdwVolume
The volume level with which the phone is ringing. This parameter has no meaning, the value 0x8000 always gets returned.
phoneGetStatus
Description
The phoneGetStatus function enables an application to query the specified open phone device for its overall status.
Function Details
LONG WINAPI phoneGetStatusMessages(HPHONE hPhone,LPPHONESTATUS lpPhoneStatus) ;Parameters
hPhone
A handle to the open phone device to be queried.
lpPhoneStatus
A pointer to a variably sized data structure of type PHONESTATUS, which is loaded with the returned information about the phone's status.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Return values include the following:
PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED
phoneGetStatusMessages
Description
The phoneGetStatusMessages function returns which phone-state changes on the specified phone device generate a callback to the application.
An application can use phoneGetStatusMessages to query the generation of the corresponding messages. The phoneSetStatusMessages can control Message generation. All phone status messages remain disabled by default.
Function Details
LONG WINAPI phoneGetStatusMessages(HPHONE hPhone,LPDWORD lpdwPhoneStates,LPDWORD lpdwButtonModes,LPDWORD lpdwButtonStates);Parameters
hPhone
A handle to the open phone device that is to be monitored.
lpdwPhoneStates
A pointer to a DWORD holding zero, one or more of the PHONESTATE_ Constants. These flags specify the set of phone status changes and events for which the application can receive notification messages. Monitoring can be individually enabled and disabled for the following:
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
lpdwButtonModes
A pointer to a DWORD that contains flags that specify the set of phone-button modes for which the application can receive notification messages. This parameter uses zero, one or more of the PHONEBUTTONMODE_ Constants.
lpdwButtonStates
A pointer to a DWORD that contains flags that specify the set of phone button state changes for which the application can receive notification messages. This parameter uses zero, one or more of the PHONEBUTTONSTATE_ Constants.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.
phoneInitialize
Description
Although the phoneInitialize function is obsolete, tapi.dll and tapi32.dll continues to export it for backward compatibility with applications that are using TAPI versions 1.3 and 1.4.
Function Details
LONG WINAPI phoneInitialize(LPHPHONEAPP lphPhoneApp,HINSTANCE hInstance,PHONECALLBACK lpfnCallback,LPCSTR lpszAppName,LPDWORD lpdwNumDevs);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.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the phone device.
lpszAppName
A pointer to a null-terminated string that contains displayable characters. If this parameter is non-NULL, it contains an application-supplied name of the application. This name, which is provided in the PHONESTATUS structure, indicates, in a user-friendly way, which application is the current owner of the phone device. You can use this information for logging and status reporting purposes. If lpszAppName is NULL, the application filename gets used instead.
lpdwNumDevs
A pointer to DWORD. This location gets loaded with the number of phone devices that are available to the application.
Return Values
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
PHONEERR_INVALAPPNAME, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM
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 WINAPI 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 gets 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 gets 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 no 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
Returns zero if the request succeeds or a negative error number if an error occurs. 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 gets 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
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values follow:
PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.
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.
Note
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.
Note
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:
–
–
phoneSetDisplay
Description
The phoneSetDisplay function causes the specified string to display on the specified open phone device.
Note
Function Details
LONG phoneSetDisplay(HPHONE hPhone,DWORD dwRow,DWORD dwColumn,LPCSTR lpsDisplay,DWORD dwSize);Parameters
hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwRow
The row position on the display where the new text displays.
dwColumn
The column position on the display where the new text displays.
lpsDisplay
A pointer to the memory location where the display content is stored. The display information must have the format that is specified in the dwStringFormat member of the device capabilities for this phone.
dwSize
The size in bytes of the information to which lpsDisplay points.
phoneSetLamp
Description
The phoneSetLamp function causes the specified lamp to be lit on the specified open phone device in the specified lamp mode.
Function Details
LONG phoneSetLamp(HPHONE hPhone,DWORD dwButtonLampID,DWORD dwLampMode);Parameters
hPhone
A handle to the open phone device. Ensure that the application is the owner of the phone.
dwButtonLampID
The button whose lamp is to be illuminated. See "Phone Button Values" Table 2-7 for lamp IDs.
dwLampMode
Note
How the lamp is to be illuminated. The dwLampMode parameter can have only a single bit set. This parameter uses the following PHONELAMPMODE_ constants:
–
–
–
–
–
–
phoneSetStatusMessages
Description
The phoneSetStatusMessages function enables an application to monitor the specified phone device for selected status events.
See "TAPI Phone Messages" for supported messages.
Function Details
LONG phoneSetStatusMessages(HPHONE hPhone,DWORD dwPhoneStates,DWORD dwButtonModes,DWORD dwButtonStates);Parameters
hPhone
A handle to the open phone device to be monitored.
dwPhoneStates
These flags specify the set of phone status changes and events for which the application can receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONESTATE_ constants:
–
–
–
–
–
–
–
–
–
dwButtonModes
The set of phone-button modes for which the application can receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONEBUTTONMODE_ constants:
–
–
–
–
dwButtonStates
The set of phone-button state changes for which the application can receive notification messages. If the dwButtonModes parameter is zero, the system ignores dwButtonStates. If dwButtonModes has one or more bits set, this parameter also must have at least one bit set. This parameter uses the following PHONEBUTTONSTATE_ constants:
–
–
–
–
phoneShutdown
Description
The phoneShutdown function shuts down the application usage of the TAPI phone abstraction.
Note
Function Details
LONG WINAPI phoneShutdown(HPHONEAPP hPhoneApp);Parameter
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 are as follows:
•
•
•
•
TAPI Phone Messages
Messages notify the application of asynchronous events. All messages get sent to the application through the message notification mechanism that the application specified in lineInitializeEx. The message always contains a handle to the relevant object (phone, line, or call), of which the application can determine the type from the message type.
Table 2-6 TAPI Phone Messages
Supported
Supported
Supported
PHONE_DEVSPECIFIC
Not Supported
Supported
Supported
Supported
PHONE_BUTTON
Description
The PHONE_BUTTON message notifies the application that button press monitoring is enabled if it has detected a button press on the local phone.
Function Details
PHONE_BUTTONhPhone = (HPHONE) hPhoneDevice;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) idButtonOrLamp;dwParam2 = (DWORD) ButtonMode;dwParam3 = (DWORD) ButtonState;Parameters
hPhone
A handle to the phone device.
dwCallbackInstance
The callback instance that is provided when opening the phone device for this application.
dwParam1
The button/lamp identifier of the button that was pressed. Button identifiers zero through 11 always represent the KEYPAD buttons, with `0' being button identifier zero, `1' being button identifier 1 (and so on through button identifier 9), and with `*' being button identifier 10, and `#' being button identifier 11. Find additional information about a button identifier with phoneGetDevCaps.
dwParam2
The button mode of the button. The button mode for each button ID gets listed as "Phone Button Values".
The TAPI service provider cannot detect button down or button up state changes. To conform to the TAPI specification, two messages get sent simulating a down state followed by an up state in dwparam3.
This parameter uses the following PHONEBUTTONMODE_ constants:
–
–
–
–
dwParam3
Specifies whether this is a button-down event or a button-up event. This parameter uses the following PHONEBUTTONSTATE_ constants:
–
–
–
–
Button ID values of zero through 11 map to the keypad buttons as defined by TAPI. Values above 11 map to line and feature buttons. The low order part of the DWORD specifies the feature. The high-order part of the DWORD specifies the instance number of that feature. Table 2-7 lists all possible values for the low order part of the DWORD corresponding to the feature.
The button ID can be made by the following expression:
ButtonID = (instance << 16) | featureID
Table 2-7 lists the valid phone button values.
PHONE_CLOSE
Description
The PHONE_CLOSE message gets sent when an open phone device is forcibly closed as part of resource reclamation. The device handle is no longer valid after this message is sent.
Function Details
PHONE_CLOSEhPhone = (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 is sent.
dwCallbackInstance
The callback instance of the application that is provided on an open phone device.
dwParam1
Not used.
dwParam2
Not used.
dwParam3
Not used.
PHONE_CREATE
Description
The PHONE_CREATE message gets sent to inform applications of the creation of a new phone device.
Note
Function Details
PHONE_CREATEhPhone = (HPHONE) hPhoneDevice;dwCallbackInstance = (DWORD) 0;dwParam1 = (DWORD) idDevice;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
hPhone
Not used.
dwCallbackInstance
Not used.
dwParam1
The dwDeviceID of the newly created device.
dwParam2
Not used.
dwParam3
Not used.
PHONE_REMOVE
Description
The PHONE_REMOVE message gets sent to inform an application of the removal (deletion from the system) of a phone device. Generally, this method does not get 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 reinitialized.
Note
Function Details
PHONE_REMOVEdwDevice = (DWORD) 0;dwCallbackInstance = (DWORD) 0;dwParam1 = (DWORD) dwDeviceID;dwParam2 = (DWORD) 0;dwParam3 = (DWORD) 0;Parameters
dwDevice
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 gets sent to an application to report the results of function call that completed asynchronously.
Function Details
PHONE_REPLYhPhone = (HPHONE) 0;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) idRequest;dwParam2 = (DWORD) Status;dwParam3 = (DWORD) 0;Parameters
hPhone
Not used.
dwCallbackInstance
Returns the application 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
Not used.
PHONE_STATE
Description
TAPI sends the PHONE_STATE message to an application whenever the status of a phone device changes.
Function Details
PHONE_STATEhPhone = (HPHONE) hPhoneDevice;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) PhoneState;dwParam2 = (DWORD) PhoneStateDetails;dwParam3 = (DWORD) 0;Parameters
hPhone
A handle to the phone device.
dwCallbackInstance
The callback instance that is provided when the phone device is opened for this application.
dwParam1
The phone state that changed. This parameter uses the following PHONESTATE_ constants:
–
–
–
–
–
–
–
–
–
–
–
dwParam2
Phone state-dependent information detailing the status change. This parameter does not used if multiple flags are set in dwParam1 because multiple status items get changed. The application should invoke phoneGetStatus to obtain a complete set of information.
Parameter dwparam2 can be one of PHONESTATE_LAMP, PHONESTATE_DISPLAY, PHONESTATE_HANDSETHOOKSWITCH or PHONESTATE_RINGMODE. Because the Cisco Unified CallManager TSP cannot differentiate among hook switches for handsets, headsets, or speaker, the PHONESTATE_HANDSETHOOKSWITCH value will always get used for hook switches.
If dwparam2 is PHONESTATE_LAMP, dwparam2 will be the button ID that is defined as in the PHONE_BUTTON message.
If dwParam1 is PHONESTATE_OWNER, dwParam2 contains the new number of owners.
If dwParam1 is PHONESTATE_MONITORS, dwParam2 contains the new number of monitors.
If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that changed.
If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode.
If dwParam1 is PHONESTATE_HANDSET, SPEAKER, or HEADSET, dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:
–
–
dwParam3
The TAPI specification specifies that dwparam3 is zero; however, the Cisco Unified CallManager TSP will send the new lamp state to the application in dwparam3 to avoid the call to phoneGetLamp to obtain the state when dwparam2 is PHONESTATE_LAMP.
TAPI Phone Structures
This section lists the Cisco-set attributes for each member of the PHONECAPS structure. If the value of a structure member is device, line, or call specific, the value for each condition is noted.
.
Table 2-8 TAPI Phone Structures
PHONEBUTTONINFO
Not Supported
Supported
PHONEEXTENSIONID
Not Supported
Supported
Supported
Supported
PHONECAPS
dwProviderInfoSize
dwProviderInfoOffset
"Cisco Unified CallManager TSPxxx.TSP: Cisco IP PBX Service Provider Ver. X.X(x.x)" where the text before the colon specifies the file name of the TSP, and the text after "Ver. " specifies the version of the TSP.
dwPhoneInfoSize
dwPhoneInfoOffset
"DeviceType:[type]" where type specifies the device type that is specified in the Cisco Unified CallManager database.
dwPermanentPhoneID
dwPhoneNameSize
dwPhoneNameOffset
"Cisco Phone: [deviceName]" where deviceName specifies the name of the device in the Cisco Unified CallManager database.
dwStringFormat
STRINGFORMAT_ASCII
dwPhoneStates
PHONESTATE_OWNER |
PHONESTATE_MONITORS |
PHONESTATE_DISPLAY | (Not set for CTI Route Points)
PHONESTATE_LAMP | (Not set for CTI Route Points)
PHONESTATE_RESUME |
PHONESTATE_REINIT |
PHONESTATE_SUSPEND
dwHookSwitchDevs
PHONEHOOKSWITCHDEV_HANDSET (Not set for CTI Route Points)
dwHandsetHookSwitchModes
PHONEHOOKSWITCHMODE_ONHOOK | (Not set for CTI Route Points)
PHONEHOOKSWITCHMODE_MICSPEAKER | (Not set for CTI Route Points)
PHONEHOOKSWITCHMODE_UNKNOWN (Not set for CTI Route Points)
dwDisplayNumRows (Not set for CTI Route Points)
1
dwDisplayNumColumns
20 (Not set for CTI Route Points)
dwNumRingModes
3 (Not set for CTI Route Points)
dwPhoneFeatures (Not set for CTI Route Points)
PHONEFEATURE_GETDISPLAY |
PHONEFEATURE_GETLAMP |
PHONEFEATURE_GETRING |
PHONEFEATURE_SETDISPLAY |
PHONEFEATURE_SETLAMP
dwMonitoredHandsetHookSwitchModes
PHONEHOOKSWITCHMODE_ONHOOK | (Not set for CTI Route Points)
PHONEHOOKSWITCHMODE_MICSPEAKER (Not set for CTI Route Points)
PHONEINITIALIZEEXPARAMS
Description
The PHONEINITIALIZEEXPARAMS structure contains parameters that are used to establish the association between an application and TAPI; for example, the application selected event notification mechanism. The phoneInitializeEx function uses this structure.
Structure Details
typedef struct phoneinitializeexparams_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwOptions;union{HANDLE hEvent;HANDLE hCompletionPort;} Handles;DWORD dwCompletionKey;} PHONEINITIALIZEEXPARAMS, FAR *LPPHONEINITIALIZEEXPARAMS;Members
dwTotalSize
The total size, in bytes, that is 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.
dwOptions
One of the PHONEINITIALIZEEXOPTION_ Constants. Specifies the event notification mechanism that the application desires to use.
hEvent
If dwOptions specifies PHONEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this member.
hCompletionPort
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this member the handle of an existing completion port that is opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.
PHONEMESSAGE
Description
The PHONEMESSAGE structure contains the next message that is queued for delivery to the application. The phoneGetMessage function returns the following structure.
Structure Details
typedef struct phonemessage_tag {DWORD hDevice;DWORD dwMessageID;DWORD_PTR dwCallbackInstance;DWORD_PTR dwParam1;DWORD_PTR dwParam2;DWORD_PTR dwParam3;} PHONEMESSAGE, FAR *LPPHONEMESSAGE;Members
hDevice
A handle to a phone device.
dwMessageID
A phone message.
dwCallbackInstance
Instance data that is passed back to the application, which the application specified in phoneInitializeEx. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.
Further Details
For details on the parameter values that are passed in this structure, see "TAPI Phone Messages."
PHONESTATUS
Description
The PHONESTATUS structure describes the current status of a phone device. The phoneGetStatus and TSPI_phoneGetStatus functions return this structure.
Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.
Note
Structure Details
typedef struct phonestatus_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwStatusFlags;DWORD dwNumOwners;DWORD dwNumMonitors;DWORD dwRingMode;DWORD dwRingVolume;DWORD dwHandsetHookSwitchMode;DWORD dwHandsetVolume;DWORD dwHandsetGain;DWORD dwSpeakerHookSwitchMode;DWORD dwSpeakerVolume;DWORD dwSpeakerGain;DWORD dwHeadsetHookSwitchMode;DWORD dwHeadsetVolume;DWORD dwHeadsetGain;DWORD dwDisplaySize;DWORD dwDisplayOffset;DWORD dwLampModesSize;DWORD dwLampModesOffset;DWORD dwOwnerNameSize;DWORD dwOwnerNameOffset;DWORD dwDevSpecificSize;DWORD dwDevSpecificOffset;DWORD dwPhoneFeatures;} PHONESTATUS, FAR *LPPHONESTATUS;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.
dwStatusFlags
Provides a set of status flags for this phone device. This member uses one of the PHONESTATUSFLAGS_ Constants.
dwNumOwners
The number of application modules with owner privilege for the phone.
dwNumMonitors
The number of application modules with monitor privilege for the phone.
dwRingMode
The current ring mode of a phone device.
dwRingVolume
0x8000
dwHandsetHookSwitchMode
The current hookswitch mode of the phone's handset. PHONEHOOKSWITCHMODE_UNKNOWN
dwHandsetVolume
0
dwHandsetGain
0
dwSpeakerHookSwitchMode
The current hookswitch mode of the phone's speakerphone. PHONEHOOKSWITCHMODE_UNKNOWN
dwSpeakerVolume
0
dwSpeakerGain
0
dwHeadsetHookSwitchMode
The current hookswitch mode of the phone's headset. PHONEHOOKSWITCHMODE_UNKNOWN
dwHeadsetVolume
0
dwHeadsetGain
0
dwDisplaySize
dwDisplayOffset
0
dwLampModesSize
dwLampModesOffset
0
dwOwnerNameSize
dwOwnerNameOffset
The size, in bytes, of the variably sized field containing the name of the application that is the current owner of the phone device, and the offset, in bytes, from the beginning of this data structure. The name is the application name provided by the application when it invoked with phoneInitialize or phoneInitializeEx. If no application name was supplied, the application's filename is used instead. If the phone currently has no owner, dwOwnerNameSize is zero.
dwDevSpecificSize
dwDevSpecificOffset
Application can send XSI data to phone using DeviceDataPassThrough device specific extension. Phone can pass back data to Application. The data is returned as part of this field. The format of the data is as follows:
struct PhoneDevSpecificData
{DWORD m_DeviceDataSize ; // size of device dataDWORD m_DeviceDataOffset ; // offset from PHONESTATUS structure// this will follow the actual variable length device data.}dwPhoneFeatures
The application negotiates an extension version >= 0x00020000. The following features are supported:
–
–
–
–
–
VARSTRING
Description
The VARSTRING structure returns variably sized strings. The line device class and the phone device class both use it.
Note
Structure Details
typedef struct varstring_tag {DWORD dwTotalSize;DWORD dwNeededSize;DWORD dwUsedSize;DWORD dwStringFormat;DWORD dwStringSize;DWORD dwStringOffset;} VARSTRING, FAR *LPVARSTRING;Members
dwTotalSize
The total size, in bytes, that is 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.
dwStringFormat
The format of the string. This member uses one of the STRINGFORMAT_ Constants.
dwStringSize
dwStringOffset
The size, in bytes, of the variably sized device field that contains the string information and the offset, in bytes, from the beginning of this data structure.
If a string cannot be returned in a variable structure, the dwStringSize and dwStringOffset members get set in one of the following ways:
dwStringSize and dwStringOffset members both get set to zero.
dwStringOffset gets set to nonzero and dwStringSize gets set to zero.
dwStringOffset gets set to nonzero, dwStringSize gets set to 1, and the byte at the given offset gets set to zero.
TAPI Assisted Telephony Functions
Table 2-9
tapiGetLocationInfo
Supported
tapiRequestDrop
Not Supported
tapiRequestMakeCall
Supported
tapiRequestMediaCall
Not Supported
tapiGetLocationInfo
tapiRequestMakeCall
Wave
The AVAudio32.dll implements the Wave interfaces to the Cisco wave drivers. The system supports all APIs for input and output waveform devices.
.waveInAddBuffer
Description
The waveInAddBuffer function sends an input buffer to the given waveform-audio input device. When the buffer is filled, the application receives notification.
Function Details
MMRESULT waveInAddBuffer(HWAVEIN hwi,LPWAVEHDR pwh,UINT cbwh);Parameters
hwi
Handle of the waveform-audio input device.
pwh
Address of a WAVEHDR structure that identifies the buffer.
cbwh
Size, in bytes, of the WAVEHDR structure.
waveInClose
Description
The waveInClose function closes the given waveform-audio input device.
Function Details
MMRESULT waveInClose(HWAVEIN hwi);Parameter
hwi
Handle of the waveform-audio input device. If the function succeeds, the handle no longer remains valid after this call.
waveInGetID
Description
The waveInGetID function gets the device identifier for the given waveform-audio input device.
This function gets supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.
Function Details
MMRESULT waveInGetID(HWAVEIN hwi,LPUINT puDeviceID);Parameters
hwi
Handle of the waveform-audio input device.
puDeviceID
Address of a variable to be filled with the device identifier.
waveInGetPosition
Description
The waveInGetPosition function retrieves the current input position of the given waveform-audio input device.
Function Details
MMRESULT waveInGetPosition(HWAVEIN hwi,LPMMTIME pmmt,UINT cbmmt);Parameters
hwi
Handle of the waveform-audio input device.
pmmt
Address of the MMTIME structure.
cbmmt
Size, in bytes, of the MMTIME structure.
waveInOpen
Description
The waveInOpen function opens the given waveform-audio input device for recording.
Function Details
MMRESULT waveInOpen(LPHWAVEIN phwi,UINT uDeviceID,LPWAVEFORMATEX pwfx,DWORD dwCallback,DWORD dwCallbackInstance,DWORD fdwOpen);Parameters
phwi
Address that is filled with a handle that identifies the open waveform-audio input device. Use this handle to identify the device when calling other waveform-audio input functions. This parameter can be NULL if WAVE_FORMAT_QUERY is specified for fdwOpen.
uDeviceID
Identifier of the waveform-audio input device to open. It can be either a device identifier or a handle of an open waveform-audio input device. You can use the following flag instead of a device identifier:
WAVE_MAPPER - The function selects a waveform-audio input device that is capable of recording in the specified format.
pwfx
Address of a WAVEFORMATEX structure that identifies the desired format for recording waveform-audio data. You can free this structure immediately after waveInOpen returns.
Note
dwCallback
Address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio recording to process messages that are related to the progress of recording. If no callback function is required, this value can specify zero. For more information on the callback function, see waveInProc in the TAPI API.
dwCallbackInstance
User-instance data that is passed to the callback mechanism. This parameter does not get used with the window callback mechanism.
fdwOpen
Flags for opening the device. The following values definitions apply:
–
–
–
–
–
–
–
–
waveInPrepareHeader
Description
The waveInPrepareHeader function prepares a buffer for waveform-audio input.
Function Details
MMRESULT waveInPrepareHeader(HWAVEIN hwi,LPWAVEHDR pwh,UINT cbwh);Parameters
hwi
Handle of the waveform-audio input device.
pwh
Address of a WAVEHDR structure that identifies the buffer to be prepared.
cbwh
Size, in bytes, of the WAVEHDR structure.
waveInReset
Description
The waveInReset function stops input on the given waveform-audio input device and resets the current position to zero. All pending buffers get marked as done and get returned to the application.
Function Details
MMRESULT waveInReset(HWAVEIN hwi);Parameter
hwi
Handle of the waveform-audio input device.
waveInStart
Description
The waveInStart function starts input on the given waveform-audio input device.
Function Details
MMRESULT waveInStart(HWAVEIN hwi);Parameter
hwi
Handle of the waveform-audio input device.
waveInUnprepareHeader
Description
The waveInUnprepareHeader function cleans up the preparation that the waveInPrepareHeader function performs. This function must be called after the device driver fills a buffer and returns it to the application. You must call this function before freeing the buffer.
Function Details
MMRESULT waveInUnprepareHeader(HWAVEIN hwi,LPWAVEHDR pwh,UINT cbwh);Parameters
hwi
Handle of the waveform-audio input device.
pwh
Address of a WAVEHDR structure that identifies the buffer to be cleaned up.
cbwh
Size, in bytes, of the WAVEHDR structure.
waveOutClose
Description
The waveOutClose function closes the given waveform-audio output device.
Function Details
MMRESULT waveOutClose(HWAVEOUT hwo);Parameter
hwo
Handle of the waveform-audio output device. If the function succeeds, the handle no longer remains valid after this call.
waveOutGetDevCaps
Description
The waveOutGetDevCaps function retrieves the capabilities of a given waveform-audio output device.
Function Details
MMRESULT waveOutGetDevCaps(UINT uDeviceID,LPWAVEOUTCAPS pwoc,UINT cbwoc);Parameters
uDeviceID
Identifier of the waveform-audio output device. It can be either a device identifier or a handle of an open waveform-audio output device.
pwoc
Address of a WAVEOUTCAPS structure that is to be filled with information about the capabilities of the device.
cbwoc
Size, in bytes, of the WAVEOUTCAPS structure.
waveOutGetID
Description
The waveOutGetID function retrieves the device identifier for the given waveform-audio output device.
This function gets supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.
Function Details
MMRESULT waveOutGetID(HWAVEOUT hwo,LPUINT puDeviceID);Parameters
hwo
Handle of the waveform-audio output device.
puDeviceID
Address of a variable to be filled with the device identifier.
waveOutGetPosition
Description
The waveOutGetPosition function retrieves the current playback position of the given waveform-audio output device.
Function Details
MMRESULT waveOutGetPosition(HWAVEOUT hwo,LPMMTIME pmmt,UINT cbmmt);Parameters
hwo
Handle of the waveform-audio output device.
pmmt
Address of an MMTIME structure.
cbmmt
Size, in bytes, of the MMTIME structure.
waveOutOpen
Description
The waveOutOpen function opens the given waveform-audio output device for playback.
Function Details
MMRESULT waveOutOpen(LPHWAVEOUT phwo,UINT uDeviceID,LPWAVEFORMATEX pwfx,DWORD dwCallback,DWORD dwCallbackInstance,DWORD fdwOpen);Parameters
phwo
Address that is filled with a handle identifying the open waveform-audio output device. Use the handle to identify the device when other waveform-audio output functions are called. This parameter might be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen.
uDeviceID
Identifier of the waveform-audio output device to open. It can be either a device identifier or a handle of an open waveform-audio input device. You can use the following flag instead of a device identifier:
WAVE_MAPPER - The function selects a waveform-audio output device that is capable of playing the given format.
pwfx
Address of a WAVEFORMATEX structure that identifies the format of the waveform-audio data to be sent to the device. You can free this structure immediately after passing it to waveOutOpen.
Note
dwCallback
Address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio playback to process messages that are related to the progress of the playback. If no callback function is required, this value can specify zero. For more information on the callback function, see waveOutProc in the TAPI API.
dwCallbackInstance
User-instance data that is passed to the callback mechanism. This parameter does not get used with the window callback mechanism.
fdwOpen
Flags for opening the device. The following value definitions apply:
–
–
–
–
–
–
–
–
–
waveOutPrepareHeader
Description
The waveOutPrepareHeader function prepares a waveform-audio data block for playback.
Function Details
MMRESULT waveOutPrepareHeader(HWAVEOUT hwo,LPWAVEHDR pwh,UINT cbwh);Parameters
hwo
Handle of the waveform-audio output device.
pwh
Address of a WAVEHDR structure that identifies the data block to be prepared.
cbwh
Size, in bytes, of the WAVEHDR structure.
waveOutReset
Description
The waveOutReset function stops playback on the given waveform-audio output device and resets the current position to zero. All pending playback buffers get marked as done and get returned to the application.
Function Details
MMRESULT waveOutReset(HWAVEOUT hwo);Parameter
hwo
Handle of the waveform-audio output device.
waveOutUnprepareHeader
Description
The waveOutUnprepareHeader function cleans up the preparation that the waveOUtPrepareHeader function performs. Ensure this function is called after the device driver is finished with a data block. You must call this function before freeing the buffer.
Function Details
MMRESULT waveOutUnprepareHeader(HWAVEOUT hwo,LPWAVEHDR pwh,UINT cbwh);Parameters
hwo
Handle of the waveform-audio output device.
pwh
Address of a WAVEHDR structure that identifies the data block to be cleaned up.
cbwh
Size, in bytes, of the WAVEHDR structure.
waveOutWrite
Description
The waveOutWrite function sends a data block to the given waveform-audio output device.
Function Details
MMRESULT waveOutWrite(HWAVEOUT hwo,LPWAVEHDR pwh,UINT cbwh);Parameters
hwo
Handle of the waveform-audio output device.
pwh
Address of a WAVEHDR structure that contains information about the data block.
cbwh
Size, in bytes, of the WAVEHDR structure.
