Cisco CallManager 3.1 TAPI Developer Guide
Cisco TAPI Implementation
Downloads: This chapterpdf (PDF - 1.03MB) The complete bookPDF (PDF - 1.96MB) | Feedback

Cisco TAPI Implementation

Table Of Contents

Cisco TAPI Implementation

Introduction

TAPI Line Functions

lineAccept

Description

Function Details

Parameters

lineAddProvider

Description

Function Details

Parameters

Return Values

lineAddToConference

Description

Function Details

Parameters

lineAnswer

Description

Function Details

Parameters

lineBlindTransfer

Description

Function Details

Parameters

lineCallbackFunc

Description

Function Details

Parameters

Further Details

lineClose

Description

Function Details

Parameter

lineCompleteTransfer

Description

Function Details

Parameters

lineConfigProvider

Description

Function Details

Parameters

Return Values

lineDeallocateCall

Description

Function Details

Parameter

lineDevSpecific

Description

Function Details

Parameters

lineDial

Description

Function Details

Parameters

lineDrop

Description

Function Details

Parameters

lineForward

Description

Function Details

Parameters

Return Values

lineGenerateDigits

Description

Function Details

Parameters

lineGenerateTone

Description

Function Details

Parameters

lineGetAddressCaps

Description

Function Details

Parameters

lineGetAddressID

Description

Function Details

Parameters

lineGetAddressStatus

Description

Function Details

Parameters

lineGetCallInfo

Description

Function Details

Parameters

lineGetCallStatus

Description

Function Details

Parameters

lineGetConfRelatedCalls

Description

Function Details

Parameters

Return Values

lineGetDevCaps

Description

Function Details

Parameters

lineGetID

Description

Function Details

Parameters

lineGetLineDevStatus

Description

Function Details

Parameters

lineGetMessage

Description

Function Details

Parameters

Return Values

lineGetNewCalls

Description

Function Details

Parameters

Return Values

lineGetNumRings

Description

Function Details

Parameters

Return Values

lineGetProviderList

Description

Function Details

Parameters

Return Values

lineGetRequest

Description

Function Details

Parameters

Return Values

lineGetStatusMessages

Description

Function Details

Parameters

Return Values

lineGetTranslateCaps

Description

Function Details

Parameters

Return Values

lineHandoff

Description

Function Details

Parameters

Return Values

lineHold

Description

Function Details

Parameter

lineInitialize

Description

Function Details

Parameters

Return Values

IlineInitializeEx

Description

Function Details

Parameters

lineMakeCall

Description

Function Details

Parameters

lineMonitorDigits

Description

Function Details

Parameters

lineMonitorTones

Description

Function Details

Parameters

lineNegotiateAPIVersion

Description

Function Details

Parameters

lineNegotiateExtVersion

Description

Function Details

Parameters

lineOpen

Description

Function Details

Parameters

linePrepareAddToConference

Description

Function Details

Parameters

Return Values

lineRedirect

Description

Function Details

Parameters

lineRegisterRequestRecipient

Description

Function Details

Parameters

Return Values

lineRemoveProvider

Description

Function Details

Parameters

Return Values

lineSetAppPriority

Description

Function Details

Parameters

Return Values

lineSetCallPrivilege

Description

Function Details

Parameters

Return Values

lineSetNumRings

Description

Function Details

Parameters

Return Values

lineSetStatusMessages

Description

Function Details

Parameters

lineSetTollList

Description

Function Details

Parameters

Return Values

lineSetupConference

Description

Function Details

Parameters

lineSetupTransfer

Description

Function Details

Parameters

lineShutdown

Description

Function Details

Parameters

lineTranslateAddress

Description

Function Details

Parameters

Return Values

lineTranslateDialog

Description

Function Details

Parameters

Return Values

lineUnhold

Description

Function Details

Parameters

TAPI Line Messages

LINE_ADDRESSSTATE

Description

Function Details

Parameters

LINE_APPNEWCALL

Description

Function Details

Parameters

LINE_CALLINFO

Description

Function Details

Parameters

LINE_CALLSTATE

Description

Function Details

Parameters

LINE_CLOSE

Description

Function Details

Parameters

LINE_CREATE

Description

Function Details

Parameters

LINE_DEVSPECIFIC

Description

Function Details

Parameters

LINE_GENERATE

Description

Function Details

Parameters

LINE_LINEDEVSTATE

Description

Function Details

Parameters

LINE_MONITORDIGITS

Description

Function Details

Parameters

LINE_MONITORTONE

Description

Function Details

Parameters

LINE_REMOVE

Description

Function Details

Parameters

LINE_REPLY

Description

Function Details

Parameters

LINE_REQUEST

Description

Function Details

Parameters

TAPI Line Structures

LINEADDRESSCAPS

LINEADDRESSSTATUS

LINEAPPINFO

Description

Structure Details

Members

LINECALLINFO

LINECALLLIST

Description

Structure Details

Members

LINECALLPARAMS

LINECALLSTATUS

LINECARDENTRY

Description

Structure Details

Members

LINECOUNTRYENTRY

Description

Structure Details

Members

LINECOUNTRYLIST

Description

Structure Details

Members

LINEDEVCAPS

LINEDEVSTATUS

LINEEXTENSIONID

LINEFORWARD

Description

Structure Details

Members

LINEFORWARDLIST

Description

Structure Details

Members

LINEGENERATETONE

Description

Structure Details

Members

LINEINITIALIZEEXPARAMS

Description

Structure Details

Members

Further Details

LINELOCATIONENTRY

Description

Structure Details

Members

LINEMESSAGE

Description

Structure Details

Members

Further Details

LINEMONITORTONE

Description

Structure Details

Members

LINEPROVIDERENTRY

Description

Structure Details

Members

LINEPROVIDERLIST

Description

Structure Details

Members

LINEREQMAKECALL

Description

Structure Details

Members

LINETRANSLATECAPS

Description

Structure Details

Members

LINETRANSLATEOUTPUT

Description

Structure Details

Members

TAPI Phone Functions

phoneCallbackFunc

Description

Function Details

Parameters

Further Details

phoneClose

Description

Function Details

Parameter

phoneGetDevCaps

Description

Function Details

Parameters

phoneGetDisplay

Description

Function Details

Parameters

phoneGetLamp

Description

Function Details

Parameters

phoneGetMessage

Description

Function Details

Parameters

Return Values

phoneGetRing

Description

Function Details

Parameters

phoneGetStatusMessages

Description

Function Details

Parameters

Return Values

phoneInitialize

Description

Function Details

Parameters

Return Values

phoneInitializeEx

Description

Function Details

Parameters

Return Values

phoneNegotiateAPIVersion

Description

Function Details

Parameters

Return Values

phoneOpen

Description

Function Details

Parameters

phoneSetDisplay

Description

Function Details

Parameters

phoneSetLamp

Description

Function Details

Parameters

phoneSetStatusMessages

Description

Function Details

Parameters

phoneShutdown

Description

Function Details

Parameter

Return Values

TAPI Phone Messages

PHONE_BUTTON

Description

Function Details

Parameters

PHONE_CLOSE

Description

Function Details

Parameters

PHONE_CREATE

Description

Function Details

Parameters

PHONE_REMOVE

Description

Function Details

Parameters

PHONE_REPLY

Description

Function Details

Parameters

PHONE_STATE

Description

Function Details

Parameters

TAPI Phone Structures

PHONECAPS

PHONEINITIALIZEEXPARAMS

Description

Structure Details

Members

PHONEMESSAGE

Description

Structure Details

Members

Further Details

VARSTRING

Description

Structure Details

Members

Wave

waveOutOpen

Description

Function Details

Parameters

waveOutClose

Description

Function Details

Parameter

waveOutGetDevCaps

Description

Function Details

Parameters

waveOutGetID

Description

Function Details

Parameters

waveOutPrepareHeader

Description

Function Details

Parameters

waveOutUnprepareHeader

Description

Function Details

Parameters

waveOutGetPosition

Description

Function Details

Parameters

waveOutWrite

Description

Function Details

Parameters

waveOutReset

Description

Function Details

Parameter

waveInOpen

Description

Function Details

Parameters

waveInClose

Description

Function Details

Parameter

waveInGetID

Description

Function Details

Parameters

waveInPrepareHeader

Description

Function Details

Parameters

waveInUnprepareHeader

Description

Function Details

Parameters

waveInGetPosition

Description

Function Details

Parameters

waveInAddBuffer

Description

Function Details

Parameters

waveInStart

Description

Function Details

Parameter

waveInReset

Description

Function Details

Parameter


Cisco TAPI Implementation


Introduction

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

This chapter outlines the TAPI 2.1 functions, events, and messages supported by the Cisco TAPI Service Provider. The Cisco TAPI implementation contains functions in the following areas:

TAPI Line Functions

TAPI Line Messages

TAPI Line Structures

TAPI Phone Functions

TAPI Phone Messages

TAPI Phone Structures

Wave

TAPI Line Functions

The number of available lines is determined by the number of TAPI devices configured in the Cisco CallManager. See the "CTI Port" section on page 1-3 for more information. To terminate an audio stream using first party control, you must first install the Cisco wave device driver.

Table 2-1 TAPI Line Functions 

TAPI Line Functions

lineAccept

lineAddProvider

lineAddToConference

lineAnswer

lineBlindTransfer

lineCallbackFunc

lineClose

lineCompleteTransfer

lineConfigProvider

lineDeallocateCall

lineDevSpecific

lineDial

lineDrop

lineForward

lineGenerateDigits

lineGenerateTone

lineGetAddressCaps

lineGetAddressID

lineGetAddressStatus

lineGetCallInfo

lineGetCallStatus

lineGetConfRelatedCalls

lineGetDevCaps

lineGetID

lineGetLineDevStatus

lineGetMessage

lineGetNewCalls

lineGetNumRings

lineGetProviderList

lineGetRequest

lineGetStatusMessages

lineGetTranslateCaps

lineHandoff

lineHold

lineInitialize

IlineInitializeEx

lineMakeCall

lineMonitorDigits

lineMonitorTones

lineNegotiateAPIVersion

lineNegotiateExtVersion

lineOpen

linePrepareAddToConference

lineRedirect

lineRegisterRequestRecipient

lineRemoveProvider

lineSetAppPriority

lineSetCallPrivilege

lineSetNumRings

lineSetStatusMessages

lineSetTollList

lineSetupConference

lineSetupTransfer

lineShutdown

lineTranslateAddress

lineTranslateDialog


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 containing user-user information to be sent to the remote party as part of the call accept. This pointer can be left NULL if no user-user information is to be sent. User-user information is only 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 pointed to by lpsUserUserInfo, and must be accounted for in dwSize.


Note The Cisco TSP does not support user-user information.


dwSize

The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is 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 containing 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 are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED.

lineAddToConference

Description

This function takes the consult call specified by hConsultCall and adds it to the conference call 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 are connected, onHold, proceeding, or ringback

lineAnswer

Description

The lineAnswer function answers the specified offering call.

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 containing user-user information to be sent to the remote party at the time the call is answered. This pointer can be left NULL if no user-user information will be sent. User-user information is only 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 pointed to by lpsUserUserInfo, and must be accounted for in dwSize.


Note The Cisco TSP does not support user-user information.


dwSize

The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is 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.

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 identifying 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. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, the defined a default call-progress protocol is used.

lineCallbackFunc

Description

The lineCallbackFunc function is 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 associated with the callback. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMsg. 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 passed back to the application in the callback. 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 information about parameter values passed to this function, see TAPI Line Messages.

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


Note Using lineCompleteTransfer to complete a conference call is not supported in the Cisco TSP.


dwTransferMode

Specifies how the initiated transfer request is to be resolved. This parameter uses the following LINETRANSFERMODE_ constant:

LINETRANSFERMODE_TRANSFER - Resolve the initiated transfer by transferring the initial call to the consultation call.

lineConfigProvider

Description

The lineConfigProvider function causes a service provider to display its configuration dialog box. This is basically 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. Can be NULL to indicate that any window 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 are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

lineDeallocateCall

Description

The lineDeallocateCall function deallocates the specified call handle.


Note The Cisco CallManager will automatically deallocate calls if the call is IDLE and it is not deallocated for a specified period of time.


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 not offered by other TAPI functions. 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 TSP, lineDevSpecific can be used to:

Enable the call waiting lamp for a particular line.

Handle the audio stream (instead of using the provided Cisco wave driver).

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. This parameter is optional, but if it is specified, the call it represents must belong to the hLine line device. The call state of hCall is device specific.

lpParams

A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI 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.

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 using the standard dial number format.

dwCountryCode

The country code of the destination. This is used by the implementation 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 has the option to 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 containing 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 is only 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 pointed to by lpsUserUserInfo, and must be accounted for in dwSize.


Note The Cisco TSP does not support user-user information.


dwSize

The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

lineForward

Description

The lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. 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 currently in effect.

To indicate that the forward is set/reset, upon completion of lineForward TAPI fires LINEADDRESSSTATE events indicating the change in the line forward status.

Forward destination can be changed with a call to lineForward without canceling the current forwarding set on that line.


Note lineForward implementation of CiscoTSP allows setting up only one type for forward as dwForwardMode = UNCOND. The lpLineForwardList data structure accepts LINEFORWARD entry with dwForwardMode = UNCOND.


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 specified are to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded.

dwAddressID

The address of the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE.


Note bAllAddresses is FALSE then dwAddressID must be 0.


lpForwardList

A pointer to a variably sized data structure that describes the specific forwarding instructions of type LINEFORWARDLIST.


Note To cancel the forwarding currently in effect lpForwardList Parameter must be set to NULL.


dwNumRingsNoAnswer

The number of rings before a call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range.


Note Not used, as call forward no answer is not supported by this version of CiscoTSP.


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 This parameter is also ignored, as we do not create a consult call for setting up lineForward.


lpCallParams

A pointer to a structure of type LINECALLPARAMS. This pointer is 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 are used. Otherwise, the specified call parameters are used for establishing hConsultCall.


Note This parameter must be NULL for this version of CiscoTSP, as we do not create a consult call.


Return Values

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

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 For lpForwardList[0].dwForwardMode other than UNCOND, lineForward returns LINEERR_OPERATIONUNAVAIL. For lpForwardList.dwNumEntries more than 1, returns LINEERR_INVALPARAM


lineGenerateDigits

Description

The lineGenerateDigits function initiates the generation of the specified digits on the specified call as out-of-band tones using the specified signaling mode.


Note The Cisco TSP supports neither invoking this function with a NULL value for lpszDigits to abort a digit generation currently in progress, nor invoking lineGenerateDigits while digit generation is in progress.


Cisco IP phones pass DTMF digits out-of-band. This means that the tone is not injected into the audio stream (in-band), but is sent as a message in the control stream. The phone on the far end then injects the tone into the audio stream to present it to the user. CTI port devices do not inject DTMF tones. Also, be aware that some gateways will not inject DTMF tones into the audio stream on the way out of the LAN.

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. Note that dwDigitMode is allowed to have only a single flag set. This parameter uses the following LINEDIGITMODE_ constant:

LINEDIGITMODE_DTMF - Uses DTMF tones for digit signaling. Valid digits for DTMF mode are `0' - `9', `*', `#'.

lpszDigits

Valid characters for DTMF mode in the Cisco TSP are `0' through `9', `*', and `#'.

dwDuration

dwDuration is not supported.

lineGenerateTone

Description

The lineGenerateTone function generates the specified tone over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation currently in progress on the specified call. Invoking the lineGenerateTone or lineGenerateDigits functions while tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

Cisco IP phones pass tones out-of-band. This means that the tone is not injected into the audio stream (in-band), but is sent as a message in the control stream. The phone on the far end then injects the tone into the audio stream to present it to the user. Also, be aware that some gateways will not inject tones into the audio stream on the way out of the LAN.

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 is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified with dwDuration for both standard and custom tones. The dwToneMode parameter can only have one bit set. If no bits are set (the value 0 is passed), tone generation is canceled. This parameter uses the following LINETONEMODE_ constant:

LINETONEMODE_BEEP - The tone is a beep, as used to announce the beginning of a recording. The exact beep tone is service provider defined.

dwDuration

Duration in milliseconds during which the tone should be sustained.


Note Cisco TSP does not support dwDuration.


dwNumTones

The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to CUSTOM.

lpTones

A pointer to a LINEGENERATETONE array that specifies the components of the tone. This parameter is ignored for non-custom tones. If lpTones is a multi-frequency tone, the various tones are played 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 containing the address to be queried. Only one address is 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 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. This number is obtained by lineNegotiateAPIVersion.

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 is 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 available to TAPI for returning information.

lineGetAddressID

Description

The lineGetAddressID function returns the address identifier 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 which returns the address identifier.

dwAddressMode

The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have only a single flag set. This parameter uses the following LINEADDRESSMODE_ constant:

LINEADDRESSMODE_DIALABLEADDR - The address is specified by its dialable address. The lpsAddress parameter is the dialable address or canonical address format.

lpsAddress

A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode. 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 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 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, this structure is filled with call-related information. Prior to calling lineGetCallInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory 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, this structure is filled with call status information. 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 is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls.

Function Details

LONG WINAPI lineGetConfRelatedCalls(
  HCALL hCall,               
  LPLINECALLLIST lpCallList  
);

Parameters

hCall

A handle to a call. This is 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 are returned in this structure. The first call in the list is the conference call, the other calls are the participant calls. The application is granted 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 is unchanged. Prior to calling lineGetConfRelatedCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory 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 are:

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 is valid 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 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. This number is obtained by lineNegotiateAPIVersion.

dwExtVersion

The version number of the extensions to be used. This number is obtained by lineNegotiateExtVersion. 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 is 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 available to TAPI for returning information.

lineGetID

Description

The lineGetID function returns a device identifier for the specified device class 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:

LINECALLSELECT_LINE Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.

LINECALLSELECT_CALL Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

lpDeviceID

A pointer to a memory location of type VARSTRING, where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class API for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory 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 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, this structure is filled with the device status of the line. Prior to calling lineGetLineDevStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory 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 are:

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 is granted monitor privilege to 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 is permanently associated 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 are returned in this structure. Prior to calling lineGetNewCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory 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 are:

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 an incoming call on the given address should ring prior to answering the call.

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 is permanently associated 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 are:

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 currently installed in the telephony system.

Function Details

LONG WINAPI lineGetProviderList(
  DWORD dwAPIVersion,                
  LPLINEPROVIDERLIST lpProviderList  
);

Parameters

dwAPIVersion

The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion 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 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 are:

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. Note that dwRequestMode can only have 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 placed in the buffer depends on the request mode. The application-allocated buffer is assumed to be of sufficient size to hold the request. If dwRequestMode is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer using the LINEREQMAKECALL structure. If dwRequestMode is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer using the LINEREQMEDIACALL structure.

Return Values

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

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 related 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 are:

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 supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion 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 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 are:

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 is 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 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 is 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 to be placed on hold. The application must be an owner of the call. The call state of hCall must be connected.

lineInitialize

Description

The lineInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications 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. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, originally accepted or answered the call. This information can be useful for call logging purposes. If lpszAppName is NULL, the application's file name is used instead.

lpdwNumDevs

A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Values

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

IlineInitializeEx

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 available. A line device is 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 is 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. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call-logging purposes. If lpszFriendlyAppName is NULL, the module filename of the application is 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 is filled with the number of line devices 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 it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used, the value must be set to 0x00020000. TAPI translates any newer messages or structures into values or formats supported by the application. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, 0x00020000, 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 containing additional Parameters 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, call parameters can be specified 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 LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application is initially the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).

lpszDestAddress

A pointer to the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses or when all dialing is performed 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, a default is used by the implementation.

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 received on the call. Each time a digit of the specified digit mode is detected, a message is sent to the application indicating 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, digit monitoring is canceled. This parameter can have multiple flags set, and uses the following LINEDIGITMODE_ constant:

LINEDIGITMODE_DTMF - Detect digits as DTMF tones. Valid digits for DTMF are `0' through `9', `*', and `#'.

lineMonitorTones

Description

The lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is 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. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list.

dwNumEntries

The number of entries in lpToneList. This parameter is ignored if lpToneList is NULL.

lineNegotiateAPIVersion

Description

The lineNegotiateAPIVersion function allows an application to negotiate an API version to use. The Cisco 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 the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

dwAPIHighVersion

The most recent API version the application is compliant with. The high-order word is the major version number; the low-order word is 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 is 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, then, upon a successful negotiation, this structure is 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 TSP extensionID is 0x8EBD6A50, 0x138011d2, 0x905B0060, 0xB03DD275.

lineNegotiateExtVersion

Description

The lineNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified line device. This operation need not be called 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 using lineNegotiateAPIVersion.

dwExtLowVersion

The least recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.

dwExtHighVersion

The most recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is 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 is in the range between dwExtLowVersion and dwExtHighVersion.

lineOpen

Description

The lineOpen function opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

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 can either be a valid device identifier or the value:

LINEMAPPER


Note The Cisco TSP does not support LINEMAPPER at this time.


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 invoking other functions on the open line device.

dwAPIVersion

The API version number under which the application and Telephony API have agreed to operate. This number is obtained with lineNegotiateAPIVersion.

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. This number is obtained with lineNegotiateExtVersion.

dwCallbackInstance

User-instance data passed back to the application with each message associated with this line or with addresses or calls on this line. This parameter is not interpreted by the Telephony API.

dwPrivileges

The privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_ constants. For applications using TAPI version 2.0 or later, values for this parameter can also be combined with the LINEOPENOPTION_ constants:

LINECALLPRIVILEGE_NONE - The application can make only outgoing calls.

LINECALLPRIVILEGE_MONITOR - The application can monitor only incoming and outgoing calls.

LINECALLPRIVILEGE_OWNER - The application can own only incoming calls of the types specified in dwMediaModes.

LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER - The application can own only incoming calls of the types specified in dwMediaModes, but if it is not an owner of a call, it is a monitor.

Other flag combinations return the LINEERR_INVALPRIVSELECT error.

dwMediaModes

The media mode or modes of interest to the application. This parameter is used to register the application as a potential target for incoming call and call hand-off for the specified media mode. This parameter is meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not). This parameter uses the following LINEMEDIAMODE_ constant:

LINEMEDIAMODE_INTERACTIVEVOICE - The application can handle calls of the interactive voice media type. That is, it manages voice calls with the human user on this end of the call. This is used for third party call control of physical phones and CTI port and CTI route point devices opened by other application.

LINEMEDIAMODE_AUTOMATEDVOICE - Voice energy is present on the call. The voice is locally handled by an automated application. This is first party call control and is used with CTI port and CTI route point devices.

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.

linePrepareAddToConference

Description

The linePrepareAddToConference function prepares an existing conference call for the addition of another party.

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

A conference call handle can be obtained 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.

The consultation call can be canceled using lineDrop. It may also be possible for an application to swap 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 be an owner of this call. The call state of hConfCall must be connected.

lphConsultCall

A pointer to an HCALL handle. This location is then loaded with a handle identifying the consultation call to be added. Initially, the application is the sole owner of this call.

lpCallParams

A pointer to call parameters to be used when establishing the consultation call. 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 is zero if the function succeeds or it is a negative error number if an error occurs. Possible return
values are:

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.

Function Details

LONG lineRedirect(
  HCALL hCall,         
  LPCSTR lpszDestAddress, 
  DWORD dwCountryCode 
);

Parameters

hCall

A handle to the call to be redirected. The application must be an owner of the call. The call state of hCall must be offering, accepted, or connected.

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, a default is used by the implementation.

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 is ignored if bEnable is set to zero. This parameter is examined by TAPI only for registration, not for deregistration. The dwRegistrationInstance value 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 of the 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 are:

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 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. Can be a NULL value to indicate that any window 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 are:

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 containing 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 of the LINEMEDIAMODE_ Constants; only a single bit may be on. The value zero should be used to set the application priority for Assisted Telephony requests.

lpExtensionID

A pointer to a structure of type LINEEXTENSIONID. This parameter is 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 is ignored if dwMediaMode is nonzero.

lpszExtensionName

This parameter is ignored.

dwPriority

The new priority for the application. If the value 0 is passed, the application is removed from the priority list for the specified media or request mode (if it was already not present, no error is generated). If the value 1 is passed, the application is 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 are:

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 the application can have for the specified call. This parameter uses one and only one of the LINECALLPRIVILEGE_ 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_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. This function can be used 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 requested. It can be used by the application that answers incoming calls to determine the number of rings 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 is permanently associated with an address; the identifier remains constant across operating system upgrades.

dwNumRings

The number of rings before a call should be answered in order 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 are:

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 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:

LINEDEVSTATE_OTHER - Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.

LINEDEVSTATE_RINGING - The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

LINEDEVSTATE_NUMCALLS - The number of calls on the line device has changed.

LINEDEVSTATE_REINIT - Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices) the application should re-initialize its use of TAPI. New lineInitialize, lineInitializeEx, and lineOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system. Because of the critical nature of LINEDEVSTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.

LINEDEVSTATE_REMOVED - Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being re-initialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.

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:

LINEADDRESSSTATE_NUMCALLS - The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status.

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 returned by lineInitializeEx. 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 that variations in dialing procedures on different lines can be applied to the translation process.

lpszAddressIn

A pointer to a null-terminated string containing 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 are:

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 specified by the hCall parameter. A conference call and consult call are established and the handles returned to the application. The consult call is used 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 which will allow the call to be dialed for the application by the PBX.

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 is not 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 then it should use this call handle to dial the consult call. If the destination address is specified then the consult call will be made using this handle.

dwNumParties

This is the number of parties in the conference call. Currently the Cisco TAPI Service Provider supports a three party conference call.

lpCallParams

The call parameters used to setup the consult call. The application can specify the destination address if it wants the consult call to be dialed for it in the conference set up.

lineSetupTransfer

Description

The lineSetupTransfer function initiates a transfer of the call specified by the hCall parameter. 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 identifying the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated that enables lineDial to dial the address 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 is not applicable.

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. Which forms of transfer are available are specified in the address capabilities of the call.

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 returned by lineInitializeEx. 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 that variations in dialing procedures on different lines can be applied to the translation process.

dwAPIVersion

Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).

lpszAddressIn

Pointer to a null-terminated string containing the address from which the information is to be extracted for translation. 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 is translated.

dwCard

The credit card to be used for dialing. This parameter is only valid 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 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 is 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 If you have set the LINETRANSLATEOPTION_CANCELCALLWAITING bit, it is also advisable to set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure (passed in to lineMakeCall through the lpCallParams parameter). This prevents the line device from using dialable digits to suppress call interrupts.


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 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 are:

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 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 returned by lineInitializeEx. 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 that variations in dialing procedures on different lines can be applied to the translation process.

dwAPIVersion

Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on the line device 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 created during the function should have no owner window.

lpszAddressIn

A pointer to a null-terminated string containing 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 is not displayed. This pointer can be left NULL, in which case the phone number portion of the dialog box is not displayed. 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 is 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 are:

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.

TAPI Line Messages

This section describes the line messages supported by the Cisco TSP. These messages are used to notify the application of asynchronous events such as the a new call arriving in the Cisco CallManager. The messages are sent to the application using the method specified by the application in lineInitializeEx

.


LINE_ADDRESSSTATE

Description

The LINE_ADDRESSSTATE message is 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_ADDRESSSTATE
dwDevice = (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 supplied when opening the line.

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 have changed. The application should check the current address status to determine which items have changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device-specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle (it is now in use by zero stations).

LINEADDRESSSTATE_INUSEONE

The address has 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 has 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 is the result of 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 has 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 have changed.

LINEADDRESSSTATE_CAPSCHANGE

Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINEADDRESSCAPS structure for the address have 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, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

dwParam3

Not used.

LINE_APPNEWCALL

Description

The LINE_APPNEWCALL message is sent to inform an application when a new call handle has been 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 passed into the function).

Function Details

LINE_APPNEWCALL
dwDevice = (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 has been created.

dwCallbackInstance

The callback instance supplied when opening the line belonging to the call.

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_CALLINFO

Description

The TAPI LINE_CALLINFO message is 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_CALLINFO
hDevice = (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 supplied when opening the call's line.

dwParam1

The call information item that has changed. Can be one or more of the
LINECALLINFOSTATE_ constants.

dwParam2

Not used.

dwParam3

Not used.

LINE_CALLSTATE

Description

The LINE_CALLSTATE message is sent when the status of the specified call has changed. Typically, several such messages are received during the lifetime of a call. Applications are 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_CALLSTATE
dwDevice = (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 supplied when opening the line belonging to this call.

dwParam1

The new call state. This parameter must be one and only one of the following LINECALLSTATE_ values:

LINECALLSTATE_IDLE - The call is idle—no call actually exists.

LINECALLSTATE_OFFERING - The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring; it does not affect any call states.

LINECALLSTATE_ACCEPTED - The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also indicates that alerting to both parties has started.

LINECALLSTATE_DIALTONE - The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.

LINECALLSTATE_DIALING - Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.

LINECALLSTATE_RINGBACK - The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.

LINECALLSTATE_BUSY - The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the station belonging to the remote party are in use.

LINECALLSTATE_SPECIALINFO - Special information is sent by the network. Special information is typically sent when the destination cannot be reached.

LINECALLSTATE_CONNECTED - The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.

LINECALLSTATE_PROCEEDING - Dialing has completed and the call is proceeding through the switch or telephone network.

LINECALLSTATE_ONHOLD - The call is on hold by the switch.

LINECALLSTATE_ONHOLDPENTRANSFER - The call is currently on hold awaiting transfer to another number.

LINECALLSTATE_DISCONNECTED - The remote party has disconnected from the call.

LINECALLSTATE_UNKNOWN - The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

dwParam2

Call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses the following LINEBUSYMODE_ constants:

LINEBUSYMODE_STATION - The busy signal indicates that the station belonging to the called party is busy. This is usually signaled by means of a "normal" busy tone.

LINEBUSYMODE_TRUNK - The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.

LINEBUSYMODE_UNKNOWN - The specific mode belonging to the busy signal is currently unknown, but may become known later.

LINEBUSYMODE_UNAVAIL - The specific mode belonging to the busy signal is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:

LINECONNECTEDMODE_ACTIVE - Indicates that the call is connected at the current station (the current station is a participant in the call).

LINECONNECTEDMODE_INACTIVE - Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constant:

LINEDIALTONEMODE_UNAVAIL - The dial tone mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:

If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:

LINEDISCONNECTMODE_NORMAL - This is a "normal" disconnect request by the remote party, the call was terminated normally.

LINEDISCONNECTMODE_UNKNOWN - The reason for the disconnect request is unknown.

LINEDISCONNECTMODE_REJECT - The remote user has rejected the call.

LINEDISCONNECTMODE_BUSY - The station belonging to the remote user is busy.

LINEDISCONNECTMODE_NOANSWER - The station belonging to the remote user does not answer.

LINEDISCONNECTMODE_CONGESTION - The network is congested.

LINEDISCONNECTMODE_UNAVAIL - The reason for the disconnect is unavailable and cannot become known later.

dwParam3

If zero, this parameter indicates that there has not been a 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 is given 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:

LINECALLPRIVILEGE_MONITOR - The application has monitor privilege.

LINECALLPRIVILEGE_OWNER - The application has owner privilege.

LINE_CLOSE

Description

The LINE_CLOSE message is 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 once this message has been sent.

Function Details

LINE_CLOSE
dwDevice = (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 supplied when opening the line belonging to this call.

dwParam1

Not used

dwParam2

Not used

dwParam3

Not used

LINE_CREATE

Description

The LINE_CREATE message is sent to inform the application of the creation of a new line device. This happens when a device is administered to a user that was not in the original device list when the TSP initialized.

Function Details

LINE_CREATE
dwDevice = (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 is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

See Set Status Messages, page 3-7 for details.

Function Details

LINE_DEVSPECIFIC
dwDevice = (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 supplied when opening the line.

dwParam1

Device specific

dwParam2

Device specific

dwParam3

Device specific

LINE_GENERATE

Description

The TAPI LINE_GENERATE message is sent to notify the application that the current digit or tone generation has terminated. Only one such generation request can be in progress an a given call at any time. This message is also sent when digit or tone generation is canceled.

Function Details

LINE_GENERATE
hDevice = (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 supplied when opening the line.

dwParam1

The reason why digit or tone generation was 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 is not used.

LINE_LINEDEVSTATE

Description

The TAPI LINE_LINEDEVSTATE message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

Function Details

LINE_LINEDEVSTATE
hDevice = (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 supplied when opening the line. 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 has 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 are numbers in the range one to dwNumRingModes, where dwNumRingModes is 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, then 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 the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then 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 is sent when a digit is detected. The sending of this message is controlled with the lineMonitorDigits function.

Function Details

LINE_MONITORDIGITS
dwDevice = (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 supplied when opening the line for this call.

dwParam1

The low-order byte contains the last digit received in ASCII.

dwParam2

The digit mode that was detected. This parameter must be one and only one of the following LINEDIGITMODE_ constant:

LINEDIGITMODE_DTMF - Detect digits as DTMF tones. Valid digits for DTMF are `0' through `9', `*', and `#'.

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 is not used.

LINE_MONITORTONE

Description

The LINE_MONITORTONE message is sent when a tone is detected. The sending of this message is controlled with the lineMonitorTones function.

Function Details

LINE_MONITORTONE
dwDevice = (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

CTI Manager cluster support, extension mobility and change notification can generate LINE_REMOVE/PHONE_REMOVE events. This is a newly supported message for CiscoTSP 3.1

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

Function Details

LINE_REMOVE
dwDevice = (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 is sent to report the results of function calls that completed asynchronously.

Function Details

LINE_REPLY
dwDevice = (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.

Zero indicates success;

a negative number indicates an error.

dwParam3

Not used.

LINE_REQUEST

Description

The TAPI LINE_REQUEST message is sent to report the arrival of a new request from another application.

Function Details

LINE_REQUEST
hDevice = (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 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 requesting the drop. Otherwise, dwParam2 is not 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 line device structures supported by the Cisco TSP, lists the possible values for the structure members as set by the TSP, and provides a cross reference to the functions that use them. If the value of a structure member is device, line or call specific then the value for each condition is noted.


LINEADDRESSCAPS

dwLineDeviceID

dwAddressSize

dwAddressOffset

dwAddressStates

LINEADDRESSSTATE_FORWARD

dwCallInfoStates

LINECALLINFOSTATE_CALLID |

LINECALLINFOSTATE_MEDIAMODE |

LINECALLINFOSTATE_ORIGIN |

LINECALLINFOSTATE_REASON |

LINECALLINFOSTATE_NUMOWNERINCR |

LINECALLINFOSTATE_NUMOWNERDECR |

LINECALLINFOSTATE_NUMMONITORS |

LINECALLINFOSTATE_CALLERID |

LINECALLINFOSTATE_CALLEDID |

LINECALLINFOSTATE_CONNECTEDID |

LINECALLINFOSTATE_MONITORMODES

dwCallerIDFlags

LINECALLPARTYID_UNKNOWN |

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME

dwCalledIDFlags

LINECALLPARTYID_UNKNOWN |

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME

dwConnectedIDFlags

LINECALLPARTYID_UNKNOWN |

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME

dwRedirectionIDFlags

LINECALLPARTYID_UNKNOWN |

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME

dwRedirectingIDFlags

LINECALLPARTYID_UNKNOWN |

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME

dwCallStates

LINECALLSTATE_IDLE |

LINECALLSTATE_OFFERING |

LINECALLSTATE_ACCEPTED |

LINECALLSTATE_DIALTONE | (Not set for CTI Route Points)

LINECALLSTATE_DIALING | (Not set for CTI Route Points)

LINECALLSTATE_CONNECTED | (Not set for CTI Route Points)

LINECALLSTATE_PROCEEDING | (Not set for CTI Route Points)

LINECALLSTATE_DISCONNECTED |

LINECALLSTATE_RINGBACK | (Not set for CTI Route Points)

LINECALLSTATE_BUSY | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLD | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDTRANSFER | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDCONF | (Not set for CTI Route Points)

LINECALLSTATE_UNKNOWN

dwDialToneModes

LINEDIALTONEMODE_UNAVAIL (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

dwBusyModes

LINEBUSYMODE_UNAVAIL (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

dwSpecialInfo

LINESPECIALINFO_UNAVAIL (Set for IP Phones and CTI Ports)

0 (set for CTI Route Points)

dwDisconnectModes

LINEDISCONNECTMODE_BADADDRESS |

LINEDISCONNECTMODE_FORWARDED |

LINEDISCONNECTMODE_UNREACHABLE |

LINEDISCONNECTMODE_NORMAL |

LINEDISCONNECTMODE_BUSY |

LINEDISCONNECTMODE_NOANSWER |

LINEDISCONNECTMODE_REJECT |

LINEDISCONNECTMODE_CONGESTION

dwMaxNumActiveCalls

1 (For IP Phones and CTI Ports)

dwMaxNumOnHoldCalls

1 (For IP Phones and CTI Ports)

dwMaxNumOnHoldPendingCalls

1 (For IP Phones and CTI Ports)

dwMaxNumConference

16 (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

dwMaxNumTransConf

0

dwAddrCapFlags

LINEADDRCAPFLAGS_DIALED | (Set for IP Phones and CTI Ports)

LINEADDRCAPFLAGS_PARTIALDIAL | (Set for IP Phones and CTI Ports)

LINEADDRCAPFLAGS_ACCEPTTOALERT | (Set for CTI Ports and CTI Route Points)

LINEADDRCAPFLAGS_FWDSTATUSVALID |

LINEADDRCAPFLAGS_ROUTEPOINT (Set for CTI Route Points)

dwCallFeatures

LINECALLFEATURE_ACCEPT |

LINECALLFEATURE_ANSWER | (Not set for CTI Route Points)

LINECALLFEATURE_DROP |

LINECALLFEATURE_BLINDTRANSFER | (Not set for CTI Route Points)

LINECALLFEATURE_MONITORDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_HOLD | (Not set for CTI Route Points)

LINECALLFEATURE_UNHOLD | (Not set for CTI Route Points)

LINECALLFEATURE_SETUPTRANSFER | (Not set for CTI Route Points)

LINECALLFEATURE_COMPLETETRANSF | (Not set for CTI Route Points)

LINECALLFEATURE_DIAL | (Not set for CTI Route Points)

LINECALLFEATURE_REDIRECT |

LINECALLFEATURE_GENERATETONE | (Not set for CTI Route Points)

LINECALLFEATURE_SETUPCONF | (Not set for CTI Route Points)

LINECALLFEATURE_ADDTOCONF | (Not set for CTI Route Points)

LINECALLFEATURE_PREPAREADDTOCONF | (Not set for CTI Route Points)

LINECALLFEATURE_GATHERDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_GENERATEDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_MONITORTONES

dwTransferModes

LINETRANSFERMODE_TRANSFER (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

dwForwardModes

LINEFORWARDMODE_UNCOND

dwMaxForwardEntries

1

dwAddressFeatures

LINEADDRFEATURE_FORWARD |

LINEADDRFEATURE_MAKECALL | (Not set for CTI Route Points)

LINEADDRFEATURE_FORWARDFWD

dwDeviceClassesSize

dwDeviceClassesOffset

"tapi/line", "tapi/phone", "wave/in", wave/out"

dwCallFeatures2

LINECALLFEATURE2_TRANSFERNORM (Not set for CTI Route Points)

dwMaxNoAnswerTimeout

4294967295 (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

dwConnectedModes

LINECONNECTEDMODE_ACTIVE (Set for IP Phones and CTI Ports)

0 (Set for CTI Route Points)

LINEADDRESSSTATUS

dwNumInUse

dwNumOnHoldCalls

dwNumOnHoldPendCalls

dwNumActiveCalls

dwAddressFeatures

LINEADDRFEATURE_MAKECALL | (Not set for CTI Route Points)

LINEADDRFEATURE_FORWARD |

LINEADDRFEATURE_FORWARDFWD

dwForwardNumEntries

dwForwardSize

dwForwardOffset

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 specifying 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 specifying 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 specifying the module filename of the application. This string can be used 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 provided by the application 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 when it opened the line dwPrivileges did not include LINECALLPRIVILEGE_OWNER.

dwAddressID

If the line handle was opened using LINEOPENOPTION_SINGLEADDRESS, contains the address identifier specified; set to 0xFFFFFFFF if the single address option was not used.

An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

LINECALLINFO

hLine

dwLineDeviceID

dwAddressID

0

dwBearerMode

LINEBEARERMODEVOICE |

LINEBEARERMODESPEECH

dwMediaMode

LINEMEDIAMODE_AUTOMATEDVOICE | (Not set for IP Phones)

LINEMEDIAMODE_INTERACTIVEVOICE

dwCallID

Contains the GlobalCallID of the call. The "GlobalCallID" is a unique identifier that allows applications to identify all of the call handles related to a call.

dwCallStates

LINECALLSTATE_IDLE |

LINECALLSTATE_OFFERING |

LINECALLSTATE_ACCEPTED |

LINECALLSTATE_DIALTONE | (Not set for CTI Route Points)

LINECALLSTATE_DIALING | (Not set for CTI Route Points)

LINECALLSTATE_CONNECTED | (Not set for CTI Route Points)

LINECALLSTATE_PROCEEDING | (Not set for CTI Route Points)

LINECALLSTATE_DISCONNECTED |

LINECALLSTATE_RINGBACK | (Not set for CTI Route Points)

LINECALLSTATE_BUSY | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLD | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDTRANSFER | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDCONF | (Not set for CTI Route Points)

LINECALLSTATE_UNKNOWN

dwMonitorDigitModes

LINEDIGITMODE_DTMF

dwMonitorMediaModes

LINEMEDIAMODE_AUTOMATEDVOICE | (Not set for IP Phones)

LINEMEDIAMODE_INTERACTIVEVOICE

dwOrigin

LINECALLORIGIN_CONFERENCE |

LINECALLORIGIN_EXTERNAL |

LINECALLORIGIN_INTERNAL |

LINECALLORIGIN_OUTBOUND |

LINECALLORIGIN_UNAVAIL |

LINECALLORIGIN_UNKNOWN

dwReason

LINECALLREASON_DIRECT |

LINECALLREASON_FWDBUSY |

LINECALLREASON_FWDNOANSWER |

LINECALLREASON_FWDUNCOND |

LINECALLREASON_PARKED |

LINECALLREASON_PICKUP |

LINECALLREASON_REDIRECT |

LINECALLREASON_TRANSFER |

LINECALLREASON_UNKNOWN

dwNumOwners

dwNumMonitors

dwTrunk

0xFFFFFFFF

dwCallerIDFlags

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME |

LINECALLPARTYID_UNKNOWN

dwCallerIDSize

dwCallerIDOffset

dwCallerIDNameSize

dwCallerIDNameOffset

dwCalledIDFlags

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME |

LINECALLPARTYID_UNKNOWN

dwCalledIDSize

dwCalledIDOffset

dwCalledIDNameSize

dwCalledIDNameOffset

dwConnectedIDFlags

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME |

LINECALLPARTYID_UNKNOWN

dwConnectedIDSize

dwConnectedIDOffset

dwConnectedIDNameSize

dwConnectedIDNameOffset

dwRedirectingIDFlags

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME |

LINECALLPARTYID_UNKNOWN

dwRedirectingIDSize

dwRedirectingIDOffset

dwRedirectingIDNameSize

dwRedirectingIDNameOffset.

dwRedirectingIDFlags

LINECALLPARTYID_ADDRESS |

LINECALLPARTYID_NAME |

LINECALLPARTYID_UNKNOWN

dwRedirectingIDSize

dwRedirectingIDOffset

dwRedirectingIDNameSize

dwRedirectingIDNameOffset

dwAppNameSize

dwAppNameOffset

LINECALLLIST

Description

The LINECALLLIST structure describes a list of call handles. A structure of this type is returned by the lineGetNewCalls and lineGetConfRelatedCalls functions.


Note This structure may not be extended.


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, 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

dwNoAnswerTimeout

LINECALLSTATUS

dwCallState

LINECALLSTATE_IDLE |

LINECALLSTATE_OFFERING |

LINECALLSTATE_ACCEPTED |

LINECALLSTATE_DIALTONE | (Not set for CTI Route Points)

LINECALLSTATE_DIALING | (Not set for CTI Route Points)

LINECALLSTATE_CONNECTED | (Not set for CTI Route Points)

LINECALLSTATE_PROCEEDING | (Not set for CTI Route Points)

LINECALLSTATE_DISCONNECTED |

LINECALLSTATE_RINGBACK | (Not set for CTI Route Points)

LINECALLSTATE_BUSY | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLD | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDTRANSFER | (Not set for CTI Route Points)

LINECALLSTATE_ONHOLDPENDCONF | (Not set for CTI Route Points)

LINECALLSTATE_UNKNOWN

dwCallStateMode

LINEBUSYMODE_STATION |

LINEBUSYMODE_UNAVAIL |

LINECONNECTEDMODE_ACTIVE |

LINEDIALTONEMODE_UNAVAIL |

LINEDIALTONEMODE_NORMAL |

LINEDISCONNECTMODE_BADADDRESS |

LINEDISCONNECTMODE_BUSY |

LINEDISCONNECTMODE_CONGESTION

LINEDISCONNECTMODE_FORWARDED |

LINEDISCONNECTMODE_NOANSWER |

LINEDISCONNECTMODE_NORMAL |

LINEDISCONNECTMODE_REJECT |

LINEDISCONNECTMODE_UNREACHABLE |

LINESPECIALINFO_UNAVAIL

dwCallPrivilege

LINECALLPRIVILEGE_MONITOR |

LINECALLPRIVILEGE_NONE |

LINECALLPRIVILEGE_OWNER

dwCallFeatures

LINECALLFEATURE_ACCEPT |

LINECALLFEATURE_ANSWER | (Not set for CTI Route Points)

LINECALLFEATURE_DROP |

LINECALLFEATURE_BLINDTRANSFER | (Not set for CTI Route Points)

LINECALLFEATURE_MONITORDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_HOLD | (Not set for CTI Route Points)

LINECALLFEATURE_UNHOLD | (Not set for CTI Route Points)

LINECALLFEATURE_SETUPTRANSFER | (Not set for CTI Route Points)

LINECALLFEATURE_COMPLETETRANSF | (Not set for CTI Route Points)

LINECALLFEATURE_DIAL | (Not set for CTI Route Points)

LINECALLFEATURE_REDIRECT |

LINECALLFEATURE_GENERATETONE | (Not set for CTI Route Points)

LINECALLFEATURE_SETUPCONF | (Not set for CTI Route Points)

LINECALLFEATURE_ADDTOCONF | (Not set for CTI Route Points)

LINECALLFEATURE_PREPAREADDTOCONF | (Not set for CTI Route Points)

LINECALLFEATURE_GATHERDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_GENERATEDIGITS | (Not set for CTI Route Points)

LINECALLFEATURE_MONITORTONES

dwCallFeatures2

LINECALLFEATURE2_TRANSFERNORM (Not set for CTI Route Points)

tStateEntryTime

LINECARDENTRY

Description

The LINECARDENTRY structure describes a calling card. The LINETRANSLATECAPS structure can contain an array of LINECARDENTRY structures.


Note This structure may not be extended.


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 is not returned for security reasons (it is stored in scrambled form by TAPI). The application can use this 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 is 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 defined for calls to numbers in the other areas in the same country or region. The rule is 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 defined for calls to numbers in other countries/regions. The rule is a null-terminated string.

dwOptions

Indicates other settings 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 is part of the LINECOUNTRYLIST structure that is returned by the lineGetCountry function.


Note This structure may not be extended.


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 is 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 represented by the entry (that is, the digits that would be dialed in an international call). Only this value should ever be displayed to users (country identifiers should never be displayed, as they would 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 is 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 are 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 giving 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 containing 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 containing 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 containing 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. LINECOUNTRYLIST is returned by the lineGetCountry function.


Note This structure may not be extended.


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, 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 present in the array denominated by dwCountryListSize and dwCountryListOffset.

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

dwProviderInfoSize

dwProviderInfoOffset

"Cisco TSPxxx.TSP: Cisco IP PBX Service Provider Ver. 3.1(x.x)" where the text before the colon is the file name of the TSP and the text after "Ver. " is the version of the TSP.

dwSwitchInfoSize

dwSwitchInfoOffset

"Cisco CallManager Ver. 3.1(x.x), Cisco CTI Manager Ver. 3.1(x.x)" where the text after "Ver." is the version of the Cisco CallManager and the CTI Manager respectively.

dwPermanentLineID

dwLineNameSize

dwLineNameOffset

"Cisco Line: [deviceName] (dirn)" where deviceName is the name of the device on which the line resides, and dirn is the directory number for the device.

dwStringFormat

STRINGFORMAT_ASCII

dwAddressModes

LINEADDRESSMODE_ADDRESSID

dwNumAddresses

1

dwBearerModes

LINEBEARERMODE_SPEECH |

LINEBEARERMODE_VOICE

dwMediaModes

LINEMEDIAMODE_INTERACTIVEVOICE |

LINEMEDIAMODE_AUTOMATEDVOICE (Set for CTI Ports)

dwGenerateToneModes

LINETONEMODE_BEEP (Not set for CTI Route Points)

dwGenerateDigitModes

LINEDIGITMODE_DTMF (Not set for CTI Route Points)

dwMonitorDigitModes

LINEDIGITMODE_DTMF (Not set for CTI Route Points)

dwDevCapFlags

LINEDEVCAPFLAGS_CLOSEDROP (Not set for IP Phones)

dwProviderInfo

Contains the string "CiscoTSP001.TSP: Cisco TSP Ver. 1.0a". The text before the colon is the file name of the TSP. The text after "Ver. " is the version of the TSP.

dwMaxNumActiveCalls

1 (Not set for CTI Route Points)

dwAnswerMode

LINEANSWERMODE_HOLD (Not set for CTI Route Points)

dwRingModes

1

dwLineStates

LINEDEVSTATE_RINGING |

LINEDEVSTATE_OPEN |

LINEDEVSTATE_CLOSE |

LINEDEVSTATE_NUMCALLS | (Not set for CTI Route Points)

LINEDEVSTATE_DEVSPECIFIC | (Not set for CTI Route Points)

LINEDEVSTATE_REINIT |

LINEDEVSTATE_TRANSLATECHANGE |

LINEDEVSTATE_INSERVICE |

LINEDEVSTATE_MSGWAITOFF | (Not set for CTI Route Points)

LINEDEVSTATE_MSGWAITON | (Not set for CTI Route Points)

LINEDEVSTATE_OUTOFSERVICE

dwLineFeatures

LINEFEATURE_MAKECALL | (Not set for CTI Route Points)

LINEFEATURE_DEVSPECIFIC | (Not set for CTI Route Points)

LINEFEATURE_FORWARD |

LINEFEATURE_FORWARDFWD

dwDeviceClasses

"tapi/line"

"tapi/phone"

"wave/in" (Set for CTI Ports)

"wave/out" (Set for CTI Ports)

LINEDEVSTATUS

dwNumOpens

dwOpenMediaModes

dwLineFeatures

LINEMEDIAMODE_INTERACTIVEVOICE | (Not set for CTI Route Points)

LINEMEDIAMODE_AUTOMATEDVOICE | (Not set for CTI Route Points)

LINEFEATURE_FORWARD |

LINEFEATURE_FORWARDFWD

dwNumActiveCalls

dwNumOnHoldCalls

dwNumOnHoldPendCalls

dwDevStatusFlags

LINEDEVSTATUSFLAGS_CONNECTED |

LINEDEVSTATUSFLAGS_INSERVICE |

LINEDEVSTATUSFLAGS_MSGWAIT (Not set for CTI Route Points)

dwAppInfoSize

dwAppInfoOffset

LINEEXTENSIONID

dwExtensionID0

0x8EBD6A50

dwExtensionID1

0x138011D2

dwExtensionID2

0x905B0060

dwExtensionID3

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 Currently this is the only supported forward mode by CiscoTSP.


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 are 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 containing 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 is set to zero if dwForwardMode is not one of the following: 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 containing 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 specified as ForwardList[ ].

ForwardList[ ]

An array of forwarding instruction. The array's entries are of type LINEFORWARD.

LINEGENERATETONE

Description

The LINEGENERATETONE structure contains information about a tone to be generated. This structure is used by the lineGenerateTone and TSPI_lineGenerateTone functions.


Note This structure may not be extended.


This structure is used only for the generation of tones. It is not 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 specified by the application to fit its resolution.

dwCadenceOn

The "on" duration, in milliseconds, of the cadence of the custom tone to be generated. Zero means no tone is 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 is to be generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 is silence.

LINEINITIALIZEEXPARAMS

Description

The LINEINITIZALIZEEXPARAMS structure describes parameters supplied when making calls 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, 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 the application desires 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 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 IlineInitializeEx for further information on these options.

LINELOCATIONENTRY

Description

The LINELOCATIONENTRY structure describes a location used to provide an address translation context. The LINETRANSLATECAPS structure can contain an array of LINELOCATIONENTRY structures.


Note This structure may not be extended.


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 specifying the city or area code associated with the location (the size includes the NULL). This information, along with the country code, can be used by applications to "default" entry fields for the user when entering 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 containing 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 containing 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 containing the toll prefix list for the location. The string contains only prefixes consisting of the digits "0" through "9", separated from each other by a single "," (comma) character.

dwCountryID

The country identifier of the country or region selected for the location. This can be used 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 containing 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, this may be indicated by dwCancelCallWaitingSize being set to zero, or by it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single NULL byte).

LINEMESSAGE

Description

The LINEMESSAGE structure contains parameter values specifying a change in status of the line 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 nature of this handle (line handle or call handle) can be determined by the context provided by dwMessageID.

dwMessageID

A line or call device message.

dwCallbackInstance

Instance data passed back to the application, which was specified by the application in the dwCallBackInstance parameter of lineInitializeEx. 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 about the parameter values passed in this structure, see TAPI Line Messages.

LINEMONITORTONE

Description

The LINEMONITORTONE structure defines a tone for the purpose of detection. This is used as an entry in an array. An array of tones is passed to the lineMonitorTones function which 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's information stream for silence.


Note This structure may not be extended.


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 is 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 is 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 is returned as part of the LINEPROVIDERLIST structure returned by the function lineGetProviderList.


Note This structure is not extensible.


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 containing the filename (path) of the service provider DLL (.TSP) file.

LINEPROVIDERLIST

Description

The LINEPROVIDERLIST structure describes a list of service providers. A structure of this type is returned by the lineGetProviderList function. The LINEPROVIDERLIST structure can contain an array of LINEPROVIDERENTRY structures.


Note This structure may not be extended.


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, 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 present in the array 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 initiated by a call to the lineGetRequest function.


Note This structure may not be extended.


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 can use the canonical address format or the dialable address format. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator. Longer strings are 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 is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator.

szCalledParty[TAPIMAXCALLEDPARTYSIZE]

The null-terminated user-friendly called-party name. The maximum length of the called-party information is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator.

szComment[TAPIMAXCOMMENTSIZE]

The null-terminated comment about the call request. The maximum length of the comment string is TAPIMAXCOMMENTSIZE characters, which includes 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 LINETRANSLATECAPS structure is returned by the lineGetTranslateCaps function.


Note This structure may not be extended.


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, 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 defined, including zero (default).

dwLocationListSize

dwLocationListOffset

List of locations known to the address translation. The list consists of 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 known to the address translation. It includes only non-hidden card entries and always includes card 0 (direct dial). The list consists of 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 This structure may not be extended.


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, 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 requiring a dialable string. The output is always a null-terminated string (NULL is included in the count in dwDialableStringSize). Ancillary fields such as name and subaddress are included in this output string if they were in the input string. This string may contain private information such as calling card numbers. It should not be displayed to the user, to prevent inadvertent visibility to unauthorized persons.

dwDisplayableStringSize

dwDisplayableStringOffset

Contains the translated output that can be displayed to the user for confirmation. It is identical to DialableString, except that calling card digits are replaced with the "friendly name" of the card enclosed within bracket characters (for example, "[AT&T Card]"), and ancillary fields such as name and subaddress are removed. It should normally be safe to display this string in call-status dialog boxes without exposing private information to unauthorized persons. This information is also appropriate to include in call logs.

dwCurrentCountry

Contains the country code configured in CurrentLocation. This value may be used 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 be passed to the dwCountryCode parameter of lineMakeCall and other dialing functions (so that the call progress tones of the destination country or region such as a busy signal are properly detected). This field is set to zero if the destination address passed to lineTranslateAddress is not in canonical format.

dwTranslateResults

Indicates the information derived from the translation process, which may assist the application in presenting user-interface elements. This field uses one of the LINETRANSLATERESULT_

TAPI Phone Functions

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


phoneCallbackFunc

Description

The phoneCallbackFunc function is a placeholder for the application-supplied function name.

All callbacks occur in the application's 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 associated with the callback.

dwMsg

A line or call device message.

dwCallbackInstance

Callback instance data passed back to the application in the callback. 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 more information about the parameters 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 to be closed. If the function succeeds, the handle is no longer valid.

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 to be queried.

dwAPIVersion

The version number 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. 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.

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 to be queried. See Table 2-7 for lamp IDs.

lpdwLampMode

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:

PHONELAMPMODE_FLASH - Flash means slow on and off.

PHONELAMPMODE_FLUTTER - Flutter means fast on and off.

PHONELAMPMODE_OFF - The lamp is off.

PHONELAMPMODE_STEADY - The lamp is continuously lit.

PHONELAMPMODE_WINK - The lamp is winking.

PHONELAMPMODE_UNKNOWN - The lamp mode is currently unknown.

PHONELAMPMODE_DUMMY - This value is used to describe a button/lamp position that has no corresponding lamp.

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 returned by phoneInitializeEx. 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 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 are:

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.

Four ring modes are supported.

Table 2-5 lists the valid ring modes.

Table 2-5 Ring Modes

Ring Modes
Definition

0

Off

1

Inside Ring

2

Outside Ring

3

Feature Ring


lpdwVolume

The volume level with which the phone is ringing. This parameter has no meaning, the value 0x8000 is always returned.

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. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are 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 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:

PHONESTATE_OTHER

PHONESTATE_CONNECTED

PHONESTATE_DISCONNECTED

PHONESTATE_OWNER

PHONESTATE_MONITORS

PHONESTATE_DISPLAY

PHONESTATE_LAMP

PHONESTATE_RINGMODE

PHONESTATE_RINGVOLUME

PHONESTATE_HANDSETHOOKSWITCH

PHONESTATE_HANDSETVOLUME

PHONESTATE_HANDSETGAIN

PHONESTATE_SPEAKERHOOKSWITCH

PHONESTATE_SPEAKERVOLUME

PHONESTATE_SPEAKERGAIN

PHONESTATE_HEADSETHOOKSWITCH

PHONESTATE_HEADSETVOLUME

PHONESTATE_HEADSETGAIN

PHONESTATE_SUSPEND

PHONESTATE_RESUMEF

PHONESTATE_DEVSPECIFIC

PHONESTATE_REINIT

PHONESTATE_CAPSCHANGE

PHONESTATE_REMOVED

lpdwButtonModes

A pointer to a DWORD containing 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 specifying 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 are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.

phoneInitialize

Description

The phoneInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications 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'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 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 is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application is the current owner of the phone device. This information can be useful for logging and status reporting purposes. If lpszAppName is NULL, the application's filename is used instead.

lpdwNumDevs

A pointer to DWORD. This location is loaded with the number of phone devices available to the application.

Return Values

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

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's use of TAPI for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices available to the application. A phone device is 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's 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). This parameter is 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 string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows function GetModuleFileName).

lpdwNumDevs

A pointer to a DWORD. Upon successful completion of this request, this location is filled with the number of phone devices available to the application.

lpdwAPIVersion

A pointer to a DWORD. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, 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 containing additional parameters used to establish the association between the application and TAPI (specifically, the application's 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 are:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

phoneNegotiateAPIVersion

Description

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use with the specified phone device. It returns the extension identifier supported by the phone device, 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's registration with TAPI.

dwDeviceID

The phone device to be queried.

dwAPILowVersion

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

dwAPIHighVersion

The most recent API version the application is compliant with. The high-order word is the major version number, the low-order word is 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 is in the range dwAPILowVersion to dwAPIHighVersion.

lpExtensionID

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

Return Values

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

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 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 belonging to the phone. An application that opens the phone device with monitor privilege is notified only about events that occur at the phone, such as hookswitch changes or button presses. Ownership of a phone device is exclusive. In other words, only one application can have a phone device opened with owner privilege at a time. The phone device can, however, be opened multiple times with monitor privilege.


Note In order to open a phone device on a CTI port, a corresponding line device must be open first.


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 have agreed to operate. This number is obtained 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. This number is obtained from phoneNegotiateExtVersion.


Note The Cisco TSP does not support any phone extensions.


dwCallbackInstance

User instance data passed back to the application with each message. This parameter is not interpreted by the Telephony API.

dwPrivilege

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

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

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

phoneSetDisplay

Description

The phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

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 is to be displayed.

dwColumn

The column position on the display where the new text is to be displayed.

lpsDisplay

A pointer to the memory location where the display content is stored. The display information must have the format specified in the dwStringFormat member of the device capabilities for this phone.

dwSize

The size in bytes of the information pointed to by lpsDisplay.

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. The application must be the owner of the phone.

dwButtonLampID

The button whose lamp is to be lit. See "Phone Button Values" Table 2-7 for lamp IDs.

dwLampMode

How the lamp is to be lit. The dwLampMode parameter can have only a single bit set. This parameter uses the following PHONELAMPMODE_ constants:

PHONELAMPMODE_FLASH - Flash means slow on and off.

PHONELAMPMODE_FLUTTER - Flutter means fast on and off.

PHONELAMPMODE_OFF - The lamp is off.

PHONELAMPMODE_STEADY - The lamp is continuously lit.

PHONELAMPMODE_WINK - The lamp is winking.

PHONELAMPMODE_DUMMY - This value is used to describe a button/lamp position that has no corresponding lamp.

phoneSetStatusMessages

Description

See "TAPI Phone Messages" section for supported messages.

The phoneSetStatusMessages function enables an application to monitor the specified phone device for selected status events.

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:

PHONESTATE_OTHER - Phone status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_OWNER - The number of owners for the phone device has changed.

PHONESTATE_MONITORS - The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY - The display of the phone has changed.

PHONESTATE_LAMP - A lamp of the phone has changed.

PHONESTATE_RINGMODE - The ring mode of the phone has changed.

PHONESTATE_SPEAKERHOOKSWITCH - The hookswitch state has changed for this speakerphone.

PHONESTATE_REINIT - Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices) the application should re-initialize its use of TAPI. New phoneInitialize, phoneInitializeEx, and phoneOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, because it applies to any of the lines in the system. Because of the critical nature of PHONESTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.

PHONESTATE_REMOVED - Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value is normally immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being re-initialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.

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:

PHONEBUTTONMODE_CALL - The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE - The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD - The button is one of the twelve keypad buttons, `0' through `9', `*', and `#'.

PHONEBUTTONMODE_DISPLAY - The button is a "soft" button associated with the phone display. A phone set can have zero or more display buttons.

dwButtonStates

The set of phone-button state changes for which the application can receive notification messages. If the dwButtonModes parameter is zero, dwButtonStates is ignored. If dwButtonModes has one or more bits set, this parameter must also have at least one bit set. This parameter uses the following PHONEBUTTONSTATE_ constants:

PHONEBUTTONSTATE_UP - The button is in the "up" state.

PHONEBUTTONSTATE_DOWN - The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN - Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL - Indicates that the up or down state of the button is not known to the service provider, and will not become known.

phoneShutdown

Description

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


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


Function Details

LONG WINAPI phoneShutdown(
  HPHONEAPP hPhoneApp  
);

Parameter

hPhoneApp

The application's 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:

PHONEERR_INVALAPPHANDLE, PHONEERR_NOMEM, PHONEERR_UNINITIALIZED, PHONEERR_RESOURCEUNAVAIL.

TAPI Phone Messages

Messages are used to notify the application of asynchronous events. All of these messages are 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), which the application can determine the type of from the message type.

Table 2-6 TAPI Phone Messages

TAPI Phone Messages

PHONE_BUTTON

PHONE_CLOSE

PHONE_CREATE

PHONE_REMOVE

PHONE_REPLY

PHONE_STATE


PHONE_BUTTON

Description

The PHONE_BUTTON message is sent to notify the application that button press monitoring is enabled if it has detected a button press on the local phone.

Function Details

PHONE_BUTTON
hPhone = (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 provided when opening the phone device for this application.

dwParam1

The button/lamp identifier of the button that was pressed. Note that button identifiers zero through 11 are always 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. Additional information about a button identifier is available with phoneGetDevCaps and phoneGetButtonInfo.

dwParam2

The button mode of the button. The button mode for each button ID is listed "Phone Button Values".

The TAPI service provider cannot detect button down or button up state changes. To conform to the TAPI specification, two messages will be sent simulating a down state followed by an up state in dwparam3.

This parameter uses the following PHONEBUTTONMODE_ constants:

PHONEBUTTONMODE_CALL - The button is assigned to a call appearance.

PHONEBUTTONMODE_FEATURE - The button is assigned to requesting features from the switch, such as hold, conference, and transfer.

PHONEBUTTONMODE_KEYPAD - The button is one of the twelve keypad buttons, `0' through `9', `*', and `#'.

PHONEBUTTONMODE_DISPLAY - The button is a "soft" button associated with the phone display. A phone set can have zero or more display buttons.

dwParam3

Specifies whether this is a button-down event or a button-up event. This parameter uses the following PHONEBUTTONSTATE_ constants:

PHONEBUTTONSTATE_UP - The button is in the "up" state.

PHONEBUTTONSTATE_DOWN - The button is in the "down" state (pressed down).

PHONEBUTTONSTATE_UNKNOWN - Indicates that the up or down state of the button is not known at this time, but may become known at a future time.

PHONEBUTTONSTATE_UNAVAIL - Indicates that the up or down state of the button is not known to the service provider, and cannot become known at a future time.

Button ID values of zero through eleven map to the keypad buttons as defined by TAPI. Values above eleven map to line and feature buttons. The low order part of the DWORD is the feature. The high order part of the DWORD is 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.

Table 2-7 Phone Button Values 

Value
Feature
Has Instance
Button Mode

0

Keypad button 0

No

Keypad

1

Keypad button 1

No

Keypad

2

Keypad button 2

No

Keypad

3

Keypad button 3

No

Keypad

4

Keypad button 4

No

Keypad

5

Keypad button 5

No

Keypad

6

Keypad button 6

No

Keypad

7

Keypad button 7

No

Keypad

8

Keypad button 8

No

Keypad

9

Keypad button 9

No

Keypad

10

Keypad button `*'

No

Keypad

11

Keypad button `#'

No

Keypad

12

Last Number Redial

No

Feature

13

Speed Dial

Yes

Feature

14

Hold

No

Feature

15

Transfer

No

Feature

16

Forward All (for line one)

No

Feature

17

Forward Busy (for line one)

No

Feature

18

Forward No Answer (for line one)

No

Feature

19

Display

No

Feature

20

Line

Yes

Call

21

Chat (for line one)

No

Feature

22

Whiteboard (for line one)

No

Feature

23

Application Sharing (for line one)

No

Feature

24

T120 File Transfer (for line one)

No

Feature

25

Video (for line one)

No

Feature

26

Voice Mail (for line one)

No

Feature

27

Answer Release

No

Feature

28

Auto-answer

No

Feature

44

Generic Custom Button 1

Yes

Feature

45

Generic Custom Button 2

Yes

Feature

46

Generic Custom Button 3

Yes

Feature

47

Generic Custom Button 4

Yes

Feature

48

Generic Custom Button 5

Yes

Feature


PHONE_CLOSE

Description

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

Function Details

PHONE_CLOSE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hPhone

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

dwCallbackInstance

The callback instance of the application that was provided when opening the phone device.

dwParam1

Not used.

dwParam2

Not used.

dwParam3

Not used.

PHONE_CREATE

Description

The PHONE_CREATE message is sent to inform applications of the creation of a new phone device.

Function Details

PHONE_CREATE
hPhone = (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

CTI Manager cluster support, extension mobility and change notification can generate LINE_REMOVE/PHONE_REMOVE events. This is a newly supported message for CiscoTSP 3.1

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

Function Details

PHONE_REMOVE
dwDevice = (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 is sent to an application to report the results of function call that completed asynchronously.

Function Details

PHONE_REPLY
hPhone = (HPHONE) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest;
dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

hPhone

Not used.

dwCallbackInstance

Returns the application's callback instance.

dwParam1

The request identifier for which this is the reply.

dwParam2

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

dwParam3

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_STATE
hPhone = (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 provided when opening the phone device for this application.

dwParam1

The phone state that has changed. This parameter uses the following PHONESTATE_ constants:

PHONESTATE_OTHER - Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.

PHONESTATE_CONNECTED - The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in while TAPI is active.

PHONESTATE_DISCONNECTED - The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.

PHONESTATE_OWNER - The number of owners for the phone device has changed.

PHONESTATE_MONITORS - The number of monitors for the phone device has changed.

PHONESTATE_DISPLAY - The display of the phone has changed.

PHONESTATE_LAMP - A lamp of the phone has changed.

PHONESTATE_RINGMODE - The ring mode of the phone has changed.

PHONESTATE_ HANDSETHOOKSWITCH - The hookswitch state has changed for this speakerphone.

PHONESTATE_REINIT - Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices), the application should re-initialize its use of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change as it applies to any of the phones in the system.

PHONESTATE_REMOVED - Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a PHONE_STATE message with this value is immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being re-initialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.

dwParam2

Phone state-dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have 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. Since the Cisco TSP cannot differentiate between hook switches for handsets, headsets, or speaker, the PHONESTATE_HANDSETHOOKSWITCH value will always be used for hook switches.

If dwparam2 is PHONESTATE_LAMP, then dwparam2 will be the button ID defined as in the PHONE_BUTTON message.

If dwParam1 is PHONESTATE_OWNER, then dwParam2 contains the new number of owners.

If dwParam1 is PHONESTATE_MONITORS, then dwParam2 contains the new number of monitors.

If dwParam1 is PHONESTATE_LAMP, then dwParam2 contains the button/lamp identifier of the lamp that has changed.

If dwParam1 is PHONESTATE_RINGMODE, then dwParam2 contains the new ring mode.

If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, then dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK - The microphone and speaker are both on hook for this device.

PHONEHOOKSWITCHMODE_MICSPEAKER - The microphone and speaker are both active for this device. The Cisco TSP cannot distinguish between handsets, headsets, or speakers, so this value is sent when the device is off hook.

dwParam3

The TAPI specification says that dwparam3 is zero. However, the Cisco 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 then the value for each condition is noted.

.

Table 2-8 TAPI Phone Structures

TAPI Phone Structure

PHONECAPS

PHONEINITIALIZEEXPARAMS

PHONEMESSAGE

VARSTRING


PHONECAPS

dwProviderInfoSize

dwProviderInfoOffset

"Cisco TSPxxx.TSP: Cisco IP PBX Service Provider Ver. 3.1(x.x)" where the text before the colon is the file name of the TSP and the text after "Ver. " is the version of the TSP.

dwPhoneInfoSize

dwPhoneInfoOffset

"DeviceType:[type]" where type is the device type specified in the Cisco CallManager database.

dwPermanentPhoneID

dwPhoneNameSize

dwPhoneNameOffset

"Cisco Phone: [deviceName]" where deviceName is the name of the device in the Cisco 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 used to establish the association between an application and TAPI; for example, the application's 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, 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 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 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 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 passed back to the application, which was specified by the application 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 passed in this structure, see TAPI Phone Messages.

VARSTRING

Description

The VARSTRING structure is used for returning variably sized strings. It is used both by the line device class and the phone device class.


Note No extensibility is available with VARSTRING.


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, 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 containing 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 are set in one of the following ways:

dwStringSize and dwStringOffset members are both set to zero.

dwStringOffset is nonzero and dwStringSize is zero.

dwStringOffset is nonzero, dwStringSize is 1, and the byte at the given offset is zero.

Wave

The AVAudio32.dll implements the Wave interfaces to the Cisco wave drivers. All APIs for input and output waveform devices are supported.

.


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 filled with a handle identifying the open waveform-audio output device. Use the handle to identify the device when calling other waveform-audio output functions. 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 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 The formats supported by the TAPI Wave Driver are 16-bit PCM at 8000Hz, 8-bit ulaw at 8000Hz, and 8-bit alaw at 8000Hz


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 related to the progress of the playback. If no callback function is required, this value can be zero. For more information on the callback function, see waveOutProc in the TAPI API.

dwCallbackInstance

User-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.

fdwOpen

Flags for opening the device. The following values are defined:

CALLBACK_EVENT - The dwCallback parameter is an event handle.

CALLBACK_FUNCTION - The dwCallback parameter is a callback procedure address.

CALLBACK_NULL - No callback mechanism. This is the default setting.

CALLBACK_THREAD - The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW - The dwCallback parameter is a window handle.

WAVE_ALLOWSYNC - If this flag is specified, a synchronous waveform-audio device can be opened. If this flag is not specified while opening a synchronous driver, the device will fail to open.

WAVE_FORMAT_DIRECT - If this flag is specified, the ACM driver does not perform conversions on the audio data.

WAVE_FORMAT_QUERY - If this flag is specified, waveOutOpen queries the device to determine if it supports the given format, but the device is not actually opened.

WAVE_MAPPED - If this flag is specified, the uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

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 is no longer 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 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 is 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.

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.

waveOutUnprepareHeader

Description

The waveOutUnprepareHeader function cleans up the preparation performed by the waveOUtPrepareHeader function. This function must be 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 identifying the data block to be cleaned up.

cbwh

Size, in bytes, of the WAVEHDR structure.

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.

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 containing information about the data block.

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 are marked as done and returned to the application.

Function Details

MMRESULT waveOutReset(
  HWAVEOUT hwo 
);

Parameter

hwo

Handle of the waveform-audio output device.

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 filled with a handle identifying 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 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 The formats supported by the TAPI Wave Driver are 16-bit PCM at 8000Hz, 8-bit ulaw at 8000Hz, and 8-bit alaw at 8000Hz


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 related to the progress of recording. If no callback function is required, this value can be zero. For more information on the callback function, see waveInProc in the TAPI API.

dwCallbackInstance

User-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.

fdwOpen

Flags for opening the device. The following values are defined:

CALLBACK_EVENT - The dwCallback parameter is an event handle.

CALLBACK_FUNCTION - The dwCallback parameter is a callback procedure address.

CALLBACK_NULL - No callback mechanism. This is the default setting.

CALLBACK_THREAD - The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW - The dwCallback parameter is a window handle.

WAVE_FORMAT_DIRECT - If this flag is specified, the ACM driver does not perform conversions on the audio data.

WAVE_FORMAT_QUERY - The function queries the device to determine whether it supports the given format, but it does not open the device.

WAVE_MAPPED - The uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

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 is no longer valid after this call.

waveInGetID

Description

The waveInGetID function gets the device identifier for the given waveform-audio input device.

This function is 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.

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.

waveInUnprepareHeader

Description

The waveInUnprepareHeader function cleans up the preparation performed by the waveInPrepareHeader function. 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 identifying the buffer to be cleaned up.

cbwh

Size, in bytes, of the WAVEHDR structure.

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 an MMTIME structure.

cbmmt

Size, in bytes, of the MMTIME structure.

waveInAddBuffer

Description

The waveInAddBuffer function sends an input buffer to the given waveform-audio input device. When the buffer is filled, the application is notified.

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.

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.

waveInReset

Description

The waveInReset function stops input on the given waveform-audio input device and resets the current position to zero. All pending buffers are marked as done and returned to the application.

Function Details

MMRESULT waveInReset(
  HWAVEIN hwi 
);

Parameter

hwi

Handle of the waveform-audio input device.