Cisco Unified CME TAPI Line Device

The Cisco Unified CME TAPI implementation comprises a set of classes that expose the call handling functionality of Cisco Unified CME IP phone to Windows applications. This API allows developers to create customized IP telephony applications for Cisco Unified CME without specific knowledge of the communication protocols between the Cisco Unified CME and the service provider. For example, a developer could create a TAPI application that provides a screen-based call management adjunct to an IP phone.

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

Cisco Unified CME TAPI Line Functions

Cisco Unified CME TSP 2.1 supports only one IP phone device. It supports both "first-party" call control that allows the application to terminate the media and "third-party" call control that allows an application to control the calls made or received on the associated IP phone.

This chapter documents the function calls handled by the TSP. For information about the TAPI calls handled by TAPISRV, please refer to the Microsoft documents.

lineAddtoConference

Description

The lineAddtoConference function takes the consultation call that is specified by hConsultCall and adds it to the conference call that is specified by hConfCall.

Function Details

LONG lineAddToConference(

HCALL hConfCall,

HCALL hConsultCall

);

Parameters

hConfCall

A pointer to the conference call handle. The state of the conference call must be OnHoldPendingConference or OnHold.

hConsultCall

A pointer to the consultation 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 consultation call must be in the connected state.

Return Values

LINEERR_INVALCONFCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, 
LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE,

Further Details

If LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added call is invalid.

The call handle of the added party remains valid after adding the call to a conference. Its state typically changes to conferenced while the state of the conference call typically becomes connected.

lineAnswer

Description

Note Cisco Unified CME places the previous call on the device in the connected call state on hold before answering the new call. If the previous call is in not in the connected state (such as when ringing or dialing), then that call can be dropped.

Function Details

LONG lineAnswer(

HCALL hCall,

LPCSTR lpsUserUserInfo,

DWORD dwSize

);

Parameters

hCall

A handle to the call to be answered. The application must be an owner of this call. The call state of hCall must be offering or accepted.

lpsUserUserInfo

A pointer to a string that contains user-user information to be sent to the remote party at the time the call is answered.¹

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

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE.

Further Details

When a new call arrives, applications with an interest in the call are sent a LINE_CALLSTATE message to provide the new call handle and to inform the application about the call's state and the privileges to the new call (such as monitor or owner). The application with owner privilege for the call can answer this call using lineAnswer. After the call has been successfully answered, the call typically transitions to the connected state.

If a call comes in (is offered) at the time another call is already active, invoking lineAnswer connects to the new call. The effect this has on the existing active call depends on the line's device capabilities. The first call can be unaffected, it can automatically be dropped, or it can automatically be placed on hold. The appropriate LINE_CALLSTATE messages report state transitions to the application about both calls.

lineBlindTransfer

Description

The lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

Note When the CME is configured for Consultation-Transfer, the lineBlindTransfer function is implemented as a single-step transfer in that the TSP automatically sends Transfer-Complete.

Function Details

LONG lineBlindTransfer(

HCALL hCall,

LPCSTR lpszDestAddress,

DWORD dwCountryCode

);

Parameters

hCall

A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be connected.

lpszDestAddress

A pointer to a NULL-terminated string that identifies the location to which the call is to be transferred. The destination address uses the standard dial number format.

dwCountryCode

The country code of the destination. The implementation uses this parameter to select the call progress protocols for the destination address. If a value of 0 is specified, the defined default call-progress protocol is used.

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED.

Further Details

Blind transfer differs from a consultation transfer in that no consultation call is made visible to the application. After the blind transfer successfully completes, the specified call is typically cleared from the application's line, and it transitions to the idle state.

The application's call handle remains valid after the transfer has completed. The application must deallocate its handle using lineDeallocateCall when it is no longer interested in the transferred call. If the consultation call fails, and does not ring back, then transfer does not complete and the application is responsible for clearing all related call handles.

lineCallbackFunc

Description

The lineCallbackFunc function provides a placeholder for the application-supplied function name.

Function Details

VOID FAR PASCAL lineCallbackFunc(

DWORD hDevice,

DWORD dwMsg,

DWORD dwCallbackInstance,

DWORD dwParam1,

DWORD dwParam2,

DWORD dwParam3

);

Parameters

hDevice

A handle to either a line device or a call that is associated with the callback. The context provided by dwMsg determines the nature of this handle (line handle or call handle). Applications must use the DWORD type for this parameter because using the HANDLE type may generate an error.

dwMsg

dwCallbackInstance

Callback instance data that is passed back to the application in the callback. TAPI does not interpret DWORD.

dwParam1

dwParam2

dwParam3

Further Details

All callbacks occur in the application's context. The callback function must reside in a DLL or application module.

lineClose

Description

Function Details

LONG lineClose(

HLINE hLine

);

Parameters

hLine

A handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. A possible return values is:

LINEERR_INVALLINEHANDLE.

Further Details

If an application calls lineClose while it still has active calls on the opened line, the application's ownership of these calls is revoked. If the application was the sole owner of these calls, the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an opened line by explicitly relinquishing ownership and/or by dropping these calls prior to closing the line.

If the line was closed successfully, a LINE_LINEDEVSTATE message is sent to all applications that are monitoring the line status of open/close changes. Outstanding asynchronous replies are suppressed.

lineCompleteCall

Description

The lineCompleteCall function specifies how a call that could not be connected normally should be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer. The application can request that the call be completed in one of a number of ways.

Function Details

LONG WINAPI lineCompleteCall(

HCALL hCall,

LPDWORD lpwdCompletionID,

DWORD dwCompletionMode,

DWORD dwMessageID

);

Parameters

hCall

A handle to the call whose completion is requested. The application must be an owner of the call. The call state of hCall must be busy, ringback.

lpdwCompletionID

A pointer to a DWORD-sized memory location. The completion identifier is used to identify individual completion requests in progress. A completion identifier becomes invalid and can be reused after the request completes or after an outstanding request is canceled.

dwCompletionMode

The way in which the call is to be completed. This parameter uses one and only one of the LINECALLCOMPLMODE_ constants.

Note Only LINECALLCOMPLMODE_CALLBACK is supported by Cisco Unified CME TSP 2.1.

dwMessageID

The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages.

Return Values

LINEERR_INVALCALLCOMPLMODE, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILE.

Further Details

This function is considered complete when the request has been accepted by the network or switch; not when the request is fully completed in the way specified. After this function completes, the call typically transitions to idle.

lineCompleteTransfer

Description

The lineCompleteTransfer function completes the transfer of the specified call to the party that is connected in the consultation call.

Note Cisco Unified CME TSP 2.1 only supports the transfer operation—not conference.

Function Details

LONG lineCompleteTransfer(

HCALL hCall,

HCALL hConsultCall,

LPHCALL lphConfCall,

DWORD dwTransferMode

);

Parameters

hCall

A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer.

hConsultCall

A handle to the call that represents a connection with the destination of the transfer. The application must be an owner of this call. The call state of hConsultCall must be connected, ringback, busy, or proceeding.

lphConfCall

A pointer to a memory location where an hCall handle can be returned. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned in lphConfCall and the application becomes the sole owner of the conference call. Otherwise, this parameter is ignored by TAPI.

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.

•

LINETRANSFERMODE_CONFERENCE — The transfer is resolved by establishing a three-way conference between the application, the party connected to the initial call, and the party connected to the consultation call. Selecting this option creates a conference call.

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, 
LINEERR_INVALCONSULTCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALTRANSFERMODE.

Further Details

The LINE_REPLY message sent in response to a call to the lineCompleteTransfer function is based on the status of the call specified by the hCall parameter.

This operation completes the transfer of the original call, hCall, to the party currently connected by hConsultCall. The consultation call is typically dialed on the consultation call allocated as part of lineSetupTransfer.

The transfer request can only be resolved as a transfer; completion as three-way conference call is not supported. When resolved as a transfer, the parties connected by hCall and hConsultCall are connected to each other, and both hCall and hConsultCall are typically cleared from the application's line and transition to the idle state. The application's call handle remains valid after the transfer has completed. The application must deallocate its handle with lineDeallocateCall when it is no longer interested in the transferred call.

lineConfigProvider

Description

The lineConfigProvider function causes a service provider to display its configuration dialog box. This basically provides a straight pass-through to TSPI_providerConfig.

Function Details

LONG WINAPI lineConfigProvider(

HWND hwndOwner,

DWORD dwPermanentProviderID

);

Parameters

hwndOwner

A handle to a window to which the configuration dialog box displayed by (TSPI_providerConfig) is attached. This parameter can be NULL to indicate that any window that is created during the function should have no owner window.

dwPermanentProviderID

Return Values

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

LINEERR_INVALPARAM,

LINEERR_OPERATIONFAILED.

lineDeallocateCall

Description

Function Details

LONG lineDeallocateCall(

HCALL hCall

);

Parameters

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.

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE.

lineDevSpecificFeature

Description

The lineDevSpecificFeature function enables service providers to provide access to features not offered by other TAPI functions. The meaning of these extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

Function Details

LONG lineDevSpecific(

HLINE hLine,

DWORD dwAddressID,

HCALL hCall,

LPVOID lpParams,

DWORD dwSize

);

Parameters

hLine

dwFeature

The feature to invoke on the line device. This parameter uses the PHONEBUTTONFUNCTION_ constants.

PHONEBUTTONFUNCTION_PRESSBUTTON,

PHONEBUTTONFUNCTION_PLAYFILE,

PHONEBUTTONFUNCTION_STOPFILE,

PHONEBUTTONFUNCTION_MONITOR.

lpParams

A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific and its contents are passed through by TAPI to or from the service provider.

dwSize

Return Values

LINEERR_INVALFEATURE,

LINEERR_INVALLINEHANDLE,

LINEERR_OPERATIONFAILED

lineDial

Description

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

dwCountryCode

The country code of the destination. The implementation uses this code to select the call progress protocols for the destination address. If a value of 0 is specified, the default call progress protocol is used.

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE.

Further Details

The lineDial function is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated, and the lineDial function would be used to perform the dialing of this consultation call. The lineDial function can be invoked multiple times in the course of multistage dialing, if the line's device capabilities allow it.

Dialing is considered complete after the address has been passed to the service provider; not after the call is finally connected. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use lineDrop.

lineDrop

Description

Function Details

LONG lineDrop(

HCALL hCall,

LPCSTR lpsUserUserInfo,

DWORD dwSize

);

Parameters

hCall

A handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.

lpsUserUserInfo

A pointer to a string that contains user-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-user information is to be sent.1

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

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE.

Further Details

When invoking lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call can drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state.

lineForward

Description

The lineForward function forwards calls that are destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the switch deflects the specified incoming calls for that address to the other number. This function provides a combination of forward all feature. This API allows calls to be forwarded unconditionally to a forwarded destination. This function can also cancel forwarding that currently is in effect. To indicate that the forward is set/reset, upon completion of lineForward, TAPI fires LINEADDRESSSTATE events that indicate the change in the line forward status. Change forward destination with a call to lineForward without canceling the current forwarding set on that line.

Note The lineForward implementation of Cisco Unified CME TSP 2.1 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

bAllAddresses

Specifies whether all originating addresses on the line or just the one that is specified are to be forwarded. If TRUE, all addresses on the line get forwarded, and dwAddressID is ignored; if FALSE, only the address that is specified as dwAddressID is forwarded.

dwAddressID

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

lpForwardList

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

lpForwardList

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 This parameter is not used because this version of Cisco Unified CME TSP 2.1 does not support call forward no answer.

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 ignored because Cisco Unified CME TSP 2.1 does not use a consultation call to set 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 get used. Otherwise, the specified call parameters get used for establishing hConsultCall.

Note This parameter must be NULL because Cisco Unified CME TSP 2.1 does not create a consultation call.

Return Values

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

LINEERR_INVALLINEHANDLE,

LINEERR_INVALADDRESSID,

LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED,

LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Note For lpForwardList[0].dwForwardMode other than UNCOND, lineForward returns LINEERR_OPERATIONUNAVAIL. For lpForwardList.dwNumEntries more than 1, lineForward returns LINEERR_INVALPARAM.

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

dwDeviceID

The line device that contains the address to be queried. Only one address is supported per line, so dwAddressID must be zero.

dwAddressID

dwAPIVersion

The version number, obtained by lineNegotiateAPIVersion, of the telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number.

dwExtVersion

The version number of the extensions to be used. This number can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number and the low-order word contains the minor version number.

lpAddressCaps

A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure 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 that is available to TAPI for returning information.

Further Details

LINEADDRESSSHARING_PRIVATE |

LINEADDRESSSHARING_BRIDGEDEXCL;

LINEADDRESSSTATE_INUSEZERO |

LINEADDRESSSTATE_INUSEONE |

LINEADDRESSSTATE_NUMCALLS;

LINECALLINFOSTATE_APPSPECIFIC |

LINECALLINFOSTATE_ORIGIN |

LINECALLINFOSTATE_REASON;

LINECALLSTATE_IDLE |

LINECALLSTATE_OFFERING |

LINECALLSTATE_ACCEPTED |

LINECALLSTATE_DIALTONE |

LINECALLSTATE_DIALING |

LINECALLSTATE_RINGBACK |

LINECALLSTATE_BUSY |

LINECALLSTATE_CONNECTED |

LINECALLSTATE_PROCEEDING |

LINECALLSTATE_ONHOLD|

LINECALLSTATE_CONFERENCED|

LINECALLSTATE_ONHOLDPENDCONF|

LINECALLSTATE_ONHOLDPENDTRANSFER|

LINECALLSTATE_DISCONNECTED;

LINEADDRFEATURE_SETMEDIACONTROL |

LINEADDRFEATURE_SETTERMINAL |

LINEADDRFEATURE_FORWARD|

LINEADDRFEATURE_PICKUP|

LINEADDRFEATURE_PICKUPDIRECT|

LINEADDRFEATURE_PICKUPGROUP|

LINEADDRFEATURE_UNPARK|

LINEADDRFEATURE_SETUPCONF;

LINECALLFEATURE_ACCEPT |

LINECALLFEATURE_ADDTOCONF|

LINECALLFEATURE_ANSWER|

LINECALLFEATURE_COMPLETETRANSF|

LINECALLFEATURE_DIAL|

LINECALLFEATURE_DROP|

LINECALLFEATURE_HOLD|

LINECALLFEATURE_PARK|

LINECALLFEATURE_PREPAREADDCONF|

LINECALLFEATURE_REMOVEFROMCONF|

LINECALLFEATURE_SETUPCONF|

LINECALLFEATURE_SETUPTRANSFER|

LINECALLFEATURE_UNHOLD |

LINECALLFEATURE_COMPLETECALL |

LINECALLFEATURE_BLINDTRANSFER;

LINECALLFEATURE2_COMPLCALLBACK ;

LINECALLSTATE_IDLE;

LINETRANSFERMODE_TRANSFER|

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

dwAddressID

lpAddressStatus

A pointer to a variably sized data structure of type LINEADDRESSSTATUS. Prior to calling lineGetAddressStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.

Return Values

LINEERR_RESOURCEUNAVAIL,

LINEERR_INVALADDRESSID;

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

lpCallInfo

A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, call-related information fills this structure. Prior to calling lineGetCallInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.

Return Values

LINEERR_INVALAPPHANDLE;

lineGetCallStatus

Description

The lineGetCallStatus function returns the current status of the specified call.

Function Details

LONG lineGetCallStatus(

HCALL hCall,

LPLINECALLSTATUS lpCallStatus

);

Parameters

hCall

lpCallStatus

A pointer to a variably sized data structure of type LINECALLSTATUS. Upon successful completion of the request, call status information fills this structure. Prior to calling lineGetCallStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

LINEERR_INVALAPPHANDLE;

lineGetDevCaps

Description

The lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information applies for all addresses on the line device.

Function Details

LONG lineGetDevCaps(

HLINEAPP hLineApp,

DWORD dwDeviceID,

DWORD dwAPIVersion,

DWORD dwExtVersion,

LPLINEDEVCAPS lpLineDevCaps

);

Parameters

hLineApp

dwDeviceID

dwAPIVersion

The version number, obtained by lineNegotiateAPIVersion, of the telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number.

dwExtVersion

The version number, obtained by lineNegotiateExtVersion, of the extensions to be used. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.

lpLineDevCaps

A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure 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 that is available to TAPI for returning information.

lineGetID

Description

The lineGetID function returns a device identifier for the specified device class that is associated with the selected line, address, or call.

Function Details

LONG lineGetID(

HLINE hLine,

DWORD dwAddressID,

HCALL hCall,

DWORD dwSelect,

LPVARSTRING lpDeviceID,

LPCSTR lpszDeviceClass

);

Parameters

hLine

dwAddressID

hCall

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, the device identifier fills this location. The format of the returned information depends on the method the device class API uses for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.

lpszDeviceClass

A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose identifier is requested. Device classes include wave/in, wave/out and tapi/line. Valid device class strings are those that are used in the SYSTEM.INI section to identify device classes.

Return Values

LINEERR_OPERATIONFAILED,

LINEERR_INVALAPPHANDLE,

LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODEVICE;

lineHold

Description

Function Details

LONG lineHold(

HCALL hCall

);

Parameters

hCall

A handle to the call that is to be placed on hold. Ensure the application is an owner of the call and the call state of hCall is connected.

Return Values

LINEERR_INVALAPPHANDLE,

LINEERR_INVALCALLSTATE;

lineInitializeEx

Description

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

Function Details

LONG lineInitializeEx(

LPHLINEAPP lphLineApp,

HINSTANCE hInstance,

LINECALLBACK lpfnCallback,

LPCSTR lpszFriendlyAppName,

LPDWORD lpdwNumDevs,

LPDWORD lpdwAPIVersion,

LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams

);

Parameters

lphLineApp

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

hInstance

The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process (for purposes of identifying call hand-off targets and media mode priorities).

lpfnCallback

The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification. This parameter 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. The LINECALLINFO structure provides this name to indicate, in a user-friendly way, which application originated, originally accepted, or answered the call. This information can prove useful for call-logging purposes. If lpszFriendlyAppName is NULL, the module filename of the application 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 that are available to the application.

lpdwAPIVersion

A pointer to a DWORD-sized location. Before calling this function, the application must initialize this DWORD to the highest API version that it is designed to support (for example, the same value that it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Make sure that artificially high values are not used; the value must be set to 0x00020000. TAPI translates any newer messages or structures into values or formats that the application supports. Upon successful completion of this request, this location is filled with the highest API version that TAPI, 0x00020000, supports thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.

lpLineInitializeExParams

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

lineMakeCall

Description

The lineMakeCall function places a call on the specified line to the specified destination address. Optionally, you can specify call parameters if anything but default call setup parameters are requested.

Function Details

LONG lineMakeCall(

HLINE hLine,

LPHCALL lphCall,

LPCSTR lpszDestAddress,

DWORD dwCountryCode,

LPLINECALLPARAMS const lpCallParams

);

Parameters

hLine

lphCall

A pointer to an HCALL handle. The handle is only valid after the application receives LINE_REPLY message that indicates that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application initially acts as the sole owner of this call. This handle registers as void if the function returns an error (synchronously or asynchronously by the reply message).

lpszDestAddress

A pointer to the destination address. This parameter follows the standard dialable number format. This pointer can be NULL for non-dialed addresses or when all dialing is performed by using lineDial. In the latter case, lineMakeCall allocates an available call appearance that would typically remain in the dial tone state until dialing begins. The country code of the called party. If a value of 0 is specified, the implementation uses a default.

lpCallParams

The dwNoAnswerTimeout attribute of the lpCallParams field is checked and if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.

Return Values

LINEERR_INVALBEARERMODE,

LINEERR_INVALAPPHANDLE,

LINEERR_INVALPOINTER, LINEERR_INVALMEDIAMODE,

LINEERR_INVALCALLPARAMS,

LINEERR_CALLUNAVAIL,

LINEERR_NODEVICE;

lineNegotiateAPIVersion

Description

The lineNegotiateAPIVersion function allows an application to negotiate an API version to use. Cisco Unified CME TSP 2.1 supports TAPI 2.2.

Function Details

LONG lineNegotiateAPIVersion(

HLINEAPP hLineApp,

DWORD dwDeviceID,

DWORD dwAPILowVersion,

DWORD dwAPIHighVersion,

LPDWORD lpdwAPIVersion,

LPLINEEXTENSIONID lpExtensionID

);

Parameters

hLineApp

dwDeviceID

dwAPILowVersion

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

dwAPIHighVersion

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

lpdwAPIVersion

A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation succeeds, this number falls in the range between dwAPILowVersion and dwAPIHighVersion.

lpExtensionID

A pointer to a structure of type LINEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, upon a successful negotiation, this structure 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.

Return Values

LINEERR_INCOMPATIBLEAPIVERSION

lineOpen

Description

The lineOpen function opens the line device that its device identifier specifies and returns a line handle for the corresponding opened line device. Subsequent operations on the line device use this line handle.

Function Details

LONG lineOpen(

HLINEAPP hLineApp,

DWORD dwDeviceID,

LPHLINE lphLine,

DWORD dwAPIVersion,

DWORD dwExtVersion,

DWORD dwCallbackInstance,

DWORD dwPrivileges,

DWORD dwMediaModes,

LPLINECALLPARAMS const lpCallParams

);

Parameters

hLineApp

dwDeviceID

Identifies the line device to be opened. It either can be a valid device identifier or the value LINEMAPPER.

Note Cisco Unified CME TSP 2.1 does not support LINEMAPPER. LphLine is a pointer to an HLINE handle that is then loaded with the handle representing the opened line device. Use this handle to identify the device when you are invoking other functions on the open line device.

dwAPIVersion

The API version number under which the application and telephony API operate. Obtain this number with lineNegotiateAPIVersion.

dwExtVersion

The extension version number under which the application and the service provider operate. This number remains zero if the application does not use any extensions. Obtain this number with lineNegotiateExtVersion.

dwCallbackInstance

User-instance data that is passed back to the application with each message that is associated with this line or with addresses or calls on this line. The telephony API does not interpret this parameter.

dwPrivileges

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

•

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

•

LINECALLPRIVILEGE_OWNER — The application can own only incoming calls of the types that are specified in dwMediaModes.

•

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

dwMediaModes

The media mode or modes of interest to the application. Use this parameter to register the application as a potential target for incoming call and call hand-off for the specified media mode. This parameter proves meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not). This parameter uses the LINEMEDIAMODE_INTERACTIVEVOICE constant where the application can handle calls of the interactive voice media type; that is, it manages voice calls with the user on this end of the call. Use this parameter for third-party call control of physical phones and CTI port and CTI route point devices that other applications opened.

lpCallParams

The dwNoAnswerTimeout attribute of the lpCallParams field is checked, and if it is non-zero, used to automatically disconnect a call that is not answered after the specified time.

Return Values

LINEERR_RESOURCEUNAVAIL,

LINEERR_OPERATIONUNAVAIL,

LINEERR_BADDEVICEID;

linePark

Description

The linePark function parks the specified call according to the specified park mode.

Function Details

LONG WINAPI linePark(

HCALL hCall,

DWORD dwParkMode,

LPCSTR lpszDirAddress,

LPVARSTRING lpNonDirAddress

);

Parameters

hCall

Handle to the call to be parked. The application must act as an owner of the call. The call state of hcall must be connected.

dwParkMode

Park mode with which the call is to be parked. This parameter can have only a single flag set and uses one of the LINEPARKMODE_ constants.

LINEPARKMODE_DIRECTED

LINEPARKMODE_NONDIRECTED

Note Cisco Unified CME TSP 2.1 transfers a call to the number supplied in DirAddress when the mode is set to LINEPARK_DIRECTED. The Cisco Unified CME park function is called when the park mode is set to LINEPARKMODE_NONDIRECTED. All address information is ignored for park.

lpszDirAddress

Pointer to a null-terminated string that indicates the address where the call is to be parked when directed park is used. The address specifies in dialable number format. This parameter is ignored for nondirected park.

lpNonDirAddress

Pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer that contains a null-terminated string), and the terminating NULL must be accounted for in the dwStringSize. Before calling linePark, the application must set the dwTotalSize member of this structure to indicate the amount of memory that is available to TAPI for returning information.

Return Values

LINEERR_INVALCALLHANDLE,

linePickup

Description

The linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device, lpszGroupID specifies the group identifier to which the alerting station belongs.

Function Details

LONG WINAPI linePickup(

  HLINE hLine,

  DWORD dwAddressID,

  LPHCALL lphCall,

  LPCSTR lpszDestAddress,

  LPCSTR lpszGroupID

);

Parameters

hLine

dwAddressID

Address on hLine at which the pickup is to be originated. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

lphCall

Pointer to a memory location where the handle to the picked up call is returned. The application is the initial sole owner of the call.

lpszDestAddress

Pointer to a null-terminated character buffer that contains the address whose call is to be picked up. The address is in standard dialable address format.

lpszGroupID

Pointer to a null-terminated character buffer containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

The lpszGroupID parameter can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device.

Return Values

LINEERR_INVALADDRESS, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, 
LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, 
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Further Details

When a call has been picked up successfully, the application is notified by the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available using lineGetCallInfo.

lineRemoveProvider

Description

The lineRemoveProvider function removes an existing telephony service provider from the telephony system.

Function Details

LONG WINAPI lineRemoveProvider(

DWORD dwPermanentProviderID,

HWND hwndOwner

);

Parameters

dwPermanentProviderID

The permanent provider identifier of the service provider that is to be removed.

hwndOwner

A handle to a window to which any dialog boxes that need to be displayed as part of the removal process (for example, a confirmation dialog box by the service provider's TSPI_providerRemove function) would be attached. The parameter can be a NULL value to indicate that any window that is created during the function should have no owner window.

Return Values

LINEERR_INIFILECORRUPT, LINEERR_NOMEM,

LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

lineSetupConference

Description

The lineSetupConference function initiates a conference given an existing two-party call that the hCall parameter specifies. A conference call and consultation call are established and the handles return to the application. Use a consultation call to dial the third party and the conference call replaces the initial two-party call.

Function Details

LONG lineSetupConference (

HCALL hCall,

HLINE hLine,

LPHCALL lphConfCall,

LPHCALL lphConsultCall,

DWORD dwNumParties,

LPLINECALLPARAMS const lpCallParams

);

Parameters

hCall

The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.

lphConsultCall

A pointer to an hCall handle. This location is then loaded with a handle that identifies the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated to enable lineDial to dial the address that is associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCall does not apply. This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and remove the hold on an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. The address capabilities of the call specifies which forms of transfer are available.

lpCallParams

The dwNoAnswerTimeout attribute of the lpCallParams field is checked and, if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.

Return Values

LINEERR_CALLUNAVAIL, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, 
LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED,

lineSetupTransfer

Description

The lineSetupTransfer function initiates a transfer of the call that the hCall parameter specifies. It establishes a consultation call, lphConsultCall, to the party who can become the transfer destination. The application acquires owner privilege to the lphConsultCall parameter.

Function Details

LONG lineSetupTransfer(

HCALL hCall,

LPHCALL lphConsultCall,

LPLINECALLPARAMS const lpCallParams

);

Parameters

hCall

The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.

lphConsultCall

A pointer to an hCall handle. This location is then loaded with a handle that identifies the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated to enable lineDial to dial the address that is associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCall does not apply. This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and remove the hold on an existing held call using (lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. The address capabilities of the call specifies which forms of transfer are available.

lpCallParams

The dwNoAnswerTimeout attribute of the lpCallParams field is checked and, if is non-zero, used to automatically disconnect a call if it is not answered after the specified time.

Return Values

LINEERR_CALLUNAVAIL,

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE,

LINEERR_INVALLINEHANDLE,

lineUnhold

Description

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.

Return Values

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE,

LINEERR_OPERATIONFAILED,

lineUnpark

Description

The lineUnpark function retrieves the call that is parked at the specified address and returns a call handle for it.

Function Details

LONG WINAPI lineUnpark(

HLINE hLine,

DWORD dwAddressID,

LPHCALL lphCall,

LPCSTR lpszDestAddress

);

Parameters

hLine

dwAddressID

Address on hLine at which the unpark is to be originated. An address identifier permanently associates with an address; the identifier remains constant across operating system upgrades.

lphCall

Pointer to the location of type HCALL where the handle to the unparked call is returned. This handle is unrelated to any other handle that previously may have been associated with the retrieved call, such as the handle that might have been associated with the call when it was originally parked. The application acts as the initial sole owner of this call.

lpszDestAddress

Pointer to a null-terminated character buffer that contains the address where the call is parked. The address displays in standard dialable address format.

Return Values

LINEERR_INVALLINEHANDLE,

Cisco Unified CME TAPI Line Messages

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

Note TAPI Line Messages
LINE_ADDRESSSTATE
LINE_APPNEWCALL
LINE_CALLINFO
LINE_CALLSTATE
LINE_CLOSE
LINE_CREATE
LINE_DEVSPECIFICFEATURE
LINE_LINEDEVSTATE
LINE_REMOVE
LINE_REPLY
LINE_REQUEST

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

dwCallbackInstance

dwParam1

dwParam2

•

LINEADDRESSSTATE_OTHER — Changed address-status items other than those listed below. The application should check the current address status to determine which items changed.

•

LINEADDRESSSTATE_DEVSPECIFIC — Device-specific item of the changed address status.

•

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

•

LINEADDRESSSTATE_INUSEONE — The address changed from idle or from being used by many bridged stations to being used by just one station.

•

LINEADDRESSSTATE_INUSEMANY — The monitored or bridged address changed from being used by one station to being used by more than one station.

•

LINEADDRESSSTATE_NUMCALLS — The number of calls on the address has changed. This change results from events such as a new inbound call, an outbound call on the address, or a call changing its hold status.

•

LINEADDRESSSTATE_FORWARD — The forwarding status of the address changed, including the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.

•

LINEADDRESSSTATE_TERMINALS — The terminal settings for the address changed.

•

LINEADDRESSSTATE_CAPSCHANGE — Indicates that due to configuration changes that the user made (or other circumstances), one or more of the members in the LINEADDRESSCAPS structure for the address changed. The application should use lineGetAddressCaps to read the updated structure. Applications that support API versions earlier than 1.4 receive a LINEDEVSTATE_REINIT message that requires them to shut down and re-initialize their connection to TAPI to obtain the updated information.

dwParam3

LINE_APPNEWCALL

Description

The LINE_APPNEWCALL message informs an application when a new call handle was spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter that 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

dwCallbackInstance

The callback instance that is supplied when the line belonging to the call is opened.

dwParam1

dwParam2

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

dwCallbackInstance

dwParam1

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

dwParam2

dwParam3

LINE_CALLSTATE

Description

The LINE_CALLSTATE message is sent when the status of the specified call changes. Typically, several such messages are received during the lifetime of a call. Applications get notified of new incoming calls with this message; the new call is in the offering state. The application can use the lineGetCallStatus function to retrieve more detailed information about the current status of the call.

Function Details

LINE_CALLSTATE

dwDevice = (DWORD) hCall;

dwCallbackInstance = (DWORD) hCallback;

dwParam1 = (DWORD) CallState;

dwParam2 = (DWORD) CallStateDetail;

dwParam3 = (DWORD) CallPrivilege;

Parameters

dwDevice

dwCallbackInstance

The callback instance that is supplied when the line belonging to this call is opened.

dwParam1

•

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. The switch instructing the line to ring does alerts; 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_CONFERENCED — The call is a member of a conference call and is logically in the connected state.

•

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. The 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_ONHOLDPENDCONF — The call is currently on hold while it is being added to a conference.

•

LINECALLSTATE_CONNECTED — The call has been established and the connection is made. Information can flow over the call between the originating address and the destination address.

•

LINECALLSTATE_PROCEEDING — Dialing completed, and the call is proceeding through the switch or telephone network.

•

LINECALLSTATE_ONHOLDPENDTRANSFER — The call is currently on hold awaiting transfer to another number.

•

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

Note If application negotiates extension version 0x00050001 or greater can receive device-specific CLDSMT_CALL_PROGRESSING_STATE =0x01000000 with LINECALLSTATE_UNKNOWN. This is a device-specific TAPI call state supported by Cisco Unified CME.

dwParam2

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

•

LINECONNECTEDMODE_ACTIVE — The call is connected at the current station (the current station acts as a participant in the call).

•

LINECONNECTEDMODE_INACTIVE — The call is active at one or more other stations, but the current station is not a participant in the call. When a call is disconnected with cause code = DISCONNECTMODE_TEMPFAILURE and the lineState = LINEDEVSTATE_INSERVICE, applications must take care of dropping the call. If the application is terminating media for a device, then it is also the responsibility of the application to stop the RTP streams for the same call. The TSP will not provide Stop Transmission/Reception events to applications in this scenario. The behavior is exactly the same with IP phones. The user must hang up the failed call on the IP phone to stop the media. The application is also responsible for stopping the RTP streams in case the line goes out of service (LINEDEVSTATE_OUTOFSERVICE) and the call on a line is reported as IDLE.

Note If an application with negotiated extension version 0x00050001 or greater receives device-specific CLDSMT_CALL_PROGRESSING_STATE = 0x01000000 with LINECALLSTATE_UNKNOWN, then the cause code will be reported as the standard Q931 cause codes in dwParam2.

If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode.

This parameter uses the LINEDIALTONEMODE_UNAVAIL constant, where 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 LINEOFFERINGMODE_ACTIVE constant, where the call alerts at the current station (accompanied by LINEDEVSTATE_RINGING messages) and, if an application is set up to automatically answer, it answers. For TAPI versions 1.4 and later, if the call state mode is ZERO, the application assumes that the value is active (which is the situation on a non-bridged address).

Note Cisco Unified CME TSP 2.1 does not send LINEDEVSTATE_RINGING messages until the call is accepted and moves to the LINECALLSTATE_ACCEPTED state. IP phones auto-accept calls.

Computer telephony integration (CTI) ports and CTI route points do not auto-accept calls. Call the lineAccept() function to accept the call at these types of devices. If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:

•

LINEDISCONNECTMODE_NORMAL — This specifies a "normal" disconnect request by the remote party, the call terminated normally.

•

LINEDISCONNECTMODE_UNKNOWN — The reason for the disconnect request is unknown.

•

LINEDISCONNECTMODE_BUSY — The station that belongs to the remote user is busy.

•

LINEDISCONNECTMODE_NOANSWER — The station that belongs to the remote user does not answer.

•

LINEDISCONNECTMODE_UNAVAIL — The reason for the disconnect is unavailable and cannot be determined later.

•

LINEDISCONNECTMODE_FACCMC — The call has been disconnected by the Forced Authorization Code (FAC) and Client Matter Code (CMC) feature.

Note LINEDISCONNECTMODE_FACCMC is only returned if the extension version negotiated on the line is 0x00050000 (5.0) or higher. If the negotiated extension version is not at least 0x00050000, then the TSP will set the disconnect mode to LINEDISCONNECTMODE_UNAVAIL.

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 receives a handle to this call; (2) When the application is the target of a call hand-off (even if the application already was an owner of the call). This parameter uses the following LINECALLPRIVILEGE_ constants:

LINE_CLOSE

Description

The LINE_CLOSE message 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 after 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

dwCallbackInstance

The callback instance that is supplied when the line belonging to this call is opened.

dwParam1

dwParam2

dwParam3

LINE_CREATE

Description

The LINE_CREATE message informs the application of the creation of a new line device.

Note CTI Manager cluster support, extension mobility, change notification, and user addition to the directory can generate LINE_CREATE events.

Function Details

LINE_CREATE

dwDevice = (DWORD) 0;

dwCallbackInstance = (DWORD) 0;

dwParam1 = (DWORD) idDevice;

dwParam2 = (DWORD) 0;

dwParam3 = (DWORD) 0;

Parameters

dwDevice

dwCallbackInstance

dwParam1

dwParam2

dwParam3

LINE_DEVSPECIFIC

Description

The LINE_DEVSPECIFIC message notifies the application about device-specific events that are occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

Function Details

LINE_DEVSPECIFIC

dwDevice = (DWORD) hLineOrCall;

dwCallbackInstance = (DWORD) hCallback;

dwParam1 = (DWORD) DeviceSpecific1;

dwParam2 = (DWORD) DeviceSpecific2;

dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice

dwCallbackInstance

dwParam1

dwParam2

dwParam3

LINE_DEVSTATE

Description

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

Function Details

LINE_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 that is supplied when the line is opened. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.

dwParam1

The line device status item that changed. The parameter can be one or more of the LINEDEVSTATE_ constants.

dwParam2

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes include numbers in the range one to dwNumRingModes, where dwNumRingModes specifies a line device capability. If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.

dwParam3

The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero. If dwParam1 is LINEDEVSTATE_REINIT, and TAPI issued the message as a result of translation of a new API message into a REINIT message, dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).

LINE_REMOVE

Description

The LINE_REMOVE message informs an application of the removal (deletion from the system) of a line device. Generally, this parameter does not get used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider, if TAPI were re-initialized.

Note CTI Manager cluster support, extension mobility, change notification, and user deletion from the directory can generate LINE_REMOVE events.

Function Details

LINE_REMOVE

dwDevice = (DWORD) 0;

dwCallbackInstance = (DWORD) 0;

dwParam1 = (DWORD) dwDeviceID;

dwParam2 = (DWORD) 0;

dwParam3 = (DWORD) 0;

Parameters

dwDevice

dwCallbackInstance

dwParam1

dwParam2

dwParam3

LINE_REPLY

Description

The LINE_REPLY message reports the results of function calls that completed asynchronously.

Function Details

LINE_REPLY

dwDevice = (DWORD) 0;

dwCallbackInstance = (DWORD) 0;

dwParam1 = (DWORD) idRequest;

dwParam2 = (DWORD) Status;

dwParam3 = (DWORD) 0;

Parameters

hDevice

dwCallbackInstance

The registration instance of the application that is specified on lineRegisterRequestRecipient.

dwParam1

The request mode of the newly pending request. This parameter uses the LINEREQUESTMODE_ constants.

dwParam2

If dwParam1 is set to LINEREQUESTMODE_DROP, dwParam2 contains the hWnd of the application that requests the drop. Otherwise, dwParam2 does not get used.

dwParam3

If dwParam1 is set to LINEREQUESTMODE_DROP, the low-order word of dwParam3 contains the wRequestID as specified by the application requesting the drop. Otherwise, dwParam3 is not used.

Cisco Unified CME TAPI Line Structures

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

LINEADDRESSCAPS

Description

The LINEADDRESSCAPS structure describes the capabilities of a specified address. The lineGetAddressCaps function and the TSPI_lineGetAddressCaps function return the LINEADDRESSCAPS structure.

Function Details

typedef struct lineaddresscaps_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwLineDeviceID;

  DWORD  dwAddressSize;

  DWORD  dwAddressOffset;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

  DWORD  dwAddressSharing;

  DWORD  dwAddressStates;

  DWORD  dwCallInfoStates;

  DWORD  dwCallerIDFlags;

  DWORD  dwCalledIDFlags;

  DWORD  dwConnectedIDFlags;

  DWORD  dwRedirectionIDFlags;

  DWORD  dwRedirectingIDFlags;

  DWORD  dwCallStates;

  DWORD  dwDialToneModes;

  DWORD  dwBusyModes;

  DWORD  dwSpecialInfo;

  DWORD  dwDisconnectModes;

  DWORD  dwMaxNumActiveCalls;

  DWORD  dwMaxNumOnHoldCalls;

  DWORD  dwMaxNumOnHoldPendingCalls;

  DWORD  dwMaxNumConference;

  DWORD  dwMaxNumTransConf;

  DWORD  dwAddrCapFlags;

  DWORD  dwCallFeatures;

  DWORD  dwRemoveFromConfCaps;

  DWORD  dwRemoveFromConfState;

  DWORD  dwTransferModes;

  DWORD  dwParkModes;

  DWORD  dwForwardModes;

  DWORD  dwMaxForwardEntries;

  DWORD  dwMaxSpecificEntries;

  DWORD  dwMinFwdNumRings;

  DWORD  dwMaxFwdNumRings;

  DWORD  dwMaxCallCompletions;

  DWORD  dwCallCompletionConds;

  DWORD  dwCallCompletionModes;

  DWORD  dwNumCompletionMessages;

  DWORD  dwCompletionMsgTextEntrySize;

  DWORD  dwCompletionMsgTextSize;

  DWORD  dwCompletionMsgTextOffset;

  DWORD  dwAddressFeatures;

  DWORD  dwPredictiveAutoTransferStates;

  DWORD  dwNumCallTreatments;

  DWORD  dwCallTreatmentListSize;

  DWORD  dwCallTreatmentListOffset;

  DWORD  dwDeviceClassesSize;

  DWORD  dwDeviceClassesOffset;

  DWORD  dwMaxCallDataSize;

  DWORD  dwCallFeatures2;

  DWORD  dwMaxNoAnswerTimeout;

  DWORD  dwConnectedModes;

  DWORD  dwOfferingModes;

  DWORD  dwAvailableMediaModes;

} LINEADDRESSCAPS, FAR *LPLINEADDRESSCAPS;

Parameters

dwTotalSize

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.

dwLineDeviceID

dwAddressSize

dwAddressOffset

The size, in bytes, of the variably sized address field and the offset, in bytes, from the beginning of this data structure.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably sized device-specific field and the offset, in bytes, from the beginning of this data structure.

dwAddressSharing

The sharing mode of the address. This member can be one of the LINEADDRESSSHARING_ constants.

dwAddressStates

Contains the address states changes for which the application may get notified in the LINE_ADDRESSSTATE message. This member uses one or more of the LINEADDRESSSTATE_ constants.

dwCallInfoStates

Describes the call information elements that are meaningful for all calls on this address. An application may get notified about changes in some of these states in LINE_CALLINFO messages. This member uses one or more of the LINECALLINFOSTATE_ constants.

dwCallerIDFlags

dwCalledIDFlags

dwConnectedIDFlags

dwRedirectionIDFlags

dwRedirectingIDFlags

Describes the various party identifier information types that can be provided for calls on this address. The caller is the originator of the session, "called" refers to the original destination, "redirection" is the new destination, and "redirecting" is the address which invoked redirection. These members uses one or more of the LINECALLPARTYID_ constants.

dwCallStates

Describes the various call states that can be reported for calls on this address. This member uses one or more of the LINECALLSTATE_ constants.

dwDialToneModes

Describes the various dial tone modes that can be reported for calls made on this address. This member is meaningful only if the dialtone call state can be reported. This member uses one or more of the LINEDIALTONEMODE_ constants.

dwBusyModes

Describes the various busy modes that can be reported for calls made on this address. This member is meaningful only if the busy call state can be reported. This member uses one or more of the LINEBUSYMODE_ constants.

dwSpecialInfo

Describes the various special information types that can be reported for calls made on this address. This member is meaningful only if the specialInfo call state can be reported. This member uses one or more of the LINESPECIALINFO_ constants.

dwDisconnectModes

Describes the various disconnect modes that can be reported for calls made on this address. This member is meaningful only if the disconnected call state can be reported. This member uses one or more of the LINEDISCONNECTMODE_ constants.

dwMaxNumActiveCalls

Contains the maximum number of active call appearances that the address can handle. This number does not include calls on hold or calls on hold pending transfer or conference.

dwMaxNumOnHoldCalls

Contains the maximum number of call appearances at the address that can be on hold.

dwMaxNumOnHoldPendingCalls

Contains the maximum number of call appearances at the address that can be on hold pending transfer or conference.

dwMaxNumConference

Contains the maximum number of parties that can join a single conference call on this address.

dwMaxNumTransConf

Specifies the number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using lineSetupTransfer.

dwAddrCapFlags

Contains a series of packed bit flags that describe a variety of address capabilities. This member uses one or more of the LINEADDRCAPFLAGS_ constants.

dwCallFeatures

Specifies the switching capabilities or features available for all calls on this address using the LINECALLFEATURE_ constants. This member represents the call-related features that may possibly be available on an address (static availability as opposed to dynamic availability). Invoking a supported feature requires the call to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the application has the right privileges to the call and the call is in the appropriate state for the operation to be meaningful. This member allows an application to discover which call features can be (and which can never be) supported by the address.

dwRemoveFromConfCaps

Specifies the address's capabilities for removing calls from a conference call. This member uses one of the LINEREMOVEFROMCONF_ constants.

dwRemoveFromConfState

Uses the LINECALLSTATE_ constants to specify the state of the call after it has been removed from a conference call.

dwTransferModes

Specifies the address's capabilities for resolving transfer requests. This member uses one of the LINETRANSFERMODE_ constants.

dwParkModes

Specifies the different call park modes available at this address. This member uses one of the LINEPARKMODE_ constants.

dwForwardModes

Specifies the different modes of forwarding available for this address. This member uses the LINEFORWARDMODE_ constants.

dwMaxForwardEntries

Specifies the maximum number of entries that can be passed to lineForward in the lpForwardList parameter.

dwMaxSpecificEntries

Specifies the maximum number of entries in the lpForwardList parameter passed to lineForward that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This member is zero if selective call forwarding is not supported.

dwMinFwdNumRings

Specifies the minimum number of rings that can be set to determine when a call is officially considered "no answer."

dwMaxFwdNumRings

Specifies the maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings are equal.

dwMaxCallCompletions

Specifies the maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.

dwCallCompletionConds

Specifies the different call conditions under which call completion can be requested. This member uses one or more of the LINECALLCOMPLCOND_ constants.

dwCallCompletionModes

Specifies the way in which the call can be completed. This member uses one of the LINECALLCOMPLMODE_ constants.

dwNumCompletionMessages

Specifies the number of call completion messages that can be selected from when using the LINECALLCOMPLMODE_MESSAGE option. Individual messages are identified by values in the range zero through one less than dwNumCompletionMessages.

dwCompletionMsgTextEntrySize

Specifies the size, in bytes, of each of the call completion text descriptions pointed at by dwCompletionMsgTextSize and dwCompletionMsgTextOffset.

dwCompletionMsgTextSize

dwCompletionMsgTextOffset

The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field containing descriptive text about each of the call completion messages. Each message is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.

dwAddressFeatures

Specifies the features available for this address using the LINEADDRFEATURE_ constants.

Invoking a supported feature requires the address to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the address is in the appropriate state for the operation to be meaningful. This member allows an application to discover which address features can be (and which can never be) supported by the address.

dwPredictiveAutoTransferStates

The call state or states upon which a call made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_ constants. The value 0 indicates automatic transfer based on call state is unavailable.

dwNumCallTreatments

The number of entries in the array of LINECALLTREATMENTENTRY structures delimited by dwCallTreatmentListSize and dwCallTreatmentListOffset.

dwCallTreatmentListSize

dwCallTreatmentListOffset

The total size, in bytes, and offset from the beginning of LINEADDRESSCAPS of an array of LINECALLTREATMENTENTRY structures, indicating the call treatments supported on the address (that can be selected using lineSetCallTreatment). The value is dwNumCallTreatments times SIZEOF(LINECALLTREATMENTENTRY).

dwDeviceClassesSize

dwDeviceClassesOffset

Length in bytes and offset from the beginning of LINEADDRESSCAPS of a string consisting of the device class identifiers supported on this address for use with lineGetID, separated by NULLs; the last class identifier is followed by two NULLs.

dwMaxCallDataSize

The maximum number of bytes that an application can set in LINECALLINFO using lineSetCallData.

dwCallFeatures2

Specifies additional switching capabilities or features available for all calls on this address using the LINECALLFEATURE2_ constants. It is an extension of the dwCallFeatures member.

dwMaxNoAnswerTimeout

The maximum value in seconds that can be set in the dwNoAnswerTimeout member in LINECALLPARAMS when making a call. A value of 0 indicates that automatic abandonment of unanswered calls is not supported by the service provider, or that the timeout value is not adjustable by applications.

dwConnectedModes

Specifies the LINECONNECTEDMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.

dwOfferingModes

Specifies the LINEOFFERINGMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.

dwAvailableMediaModes

Indicates the media types (modes) that can be invoked on new calls created on this address, when the dwAddressFeatures member indicates that new calls are possible. If this number is zero, it indicates that the service provider either does not know or cannot indicate which media types are available, in which case any or all of the media types indicated in the dwMediaModes member in LINEDEVCAPS may be available.

LINEADDRESSSTATUS

Description

The LINEADDRESSSTATUS structure describes the current status of an address. The lineGetAddressStatus function and the TSPI_lineGetAddressStatus function return the LINEADDRESSSTATUS structure.

Function Details

typedef struct lineaddressstatus_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwNumInUse;

  DWORD  dwNumActiveCalls;

  DWORD  dwNumOnHoldCalls;

  DWORD  dwNumOnHoldPendCalls;

  DWORD  dwAddressFeatures;

  DWORD  dwNumRingsNoAnswer;

  DWORD  dwForwardNumEntries;

  DWORD  dwForwardSize;

  DWORD  dwForwardOffset;

  DWORD  dwTerminalModesSize;

  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

} LINEADDRESSSTATUS, FAR *LPLINEADDRESSSTATUS;

Parameters

dwTotalSize

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.

dwNumInUse

dwNumActiveCalls

The number of calls on the address that are in call states other than idle, on hold, on hold pending transfer, and on hold pending conference.

dwNumOnHoldCalls

dwNumOnHoldPendCalls

The number of calls on the address in the on-hold-pending-transfer or on-hold-pending-conference state.

dwAddressFeatures

Specifies the address-related API functions that can be invoked on the address in its current state. This member uses one or more of the LINEADDRFEATURE_ constants.

dwNumRingsNoAnswer

The number of rings set for this address before an unanswered call is considered as no answer.

dwForwardNumEntries

The number of entries in the array referred to by dwForwardSize and dwForwardOffset.

dwForwardSize

dwForwardOffset

The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field that describes the address' forwarding information.

This information is an array of dwForwardNumEntries LINEFORWARD elements, which are relative to the beginning of the LINEADDRESSSTATUS structure. You must call upon the dwCallerAddressOffset and dwDestAddressOffset offset values in the LINEFORWARD field to derive the dwForwardSize and dwForwardOffset LINEADDRESSSTATUS offset values.

dwTerminalModesSize

dwTerminalModesOffset

The size and the offset, in bytes, from the beginning of the device field data structure containing an array with DWORD-sized entries using one or more of the LINETERMMODE_ constants.

Terminal identifiers access the range from zero to the dwNumTerminals value minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using a lineSetTerminal function to determine the address.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized device-specific field.

LINEAAPPINFO

Description

The LINEAPPINFO structure contains information about the application that is currently running. The LINEDEVSTATUS structure can contain an array of LINEAPPINFO structures.

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

Parameters

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 hand-off 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

Description

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call. Multiple functions use LINECALLINFO. The structure is returned by the lineGetCallInfo function and the TSPI_lineGetCallInfo function. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which information item has changed.

Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned by a call to the lineGetCallStatus function.

Function Details

typedef struct linecallinfo_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

 HLINE  hLine;

  DWORD  dwLineDeviceID;

  DWORD  dwAddressID;

  DWORD  dwBearerMode;

  DWORD  dwRate;

   DWORD  dwMediaMode;

  DWORD  dwAppSpecific;

  DWORD  dwCallID;

  DWORD  dwRelatedCallID;

  DWORD  dwCallParamFlags;

  DWORD  dwCallStates;

  DWORD  dwMonitorDigitModes;

  DWORD  dwMonitorMediaModes;

 LINEDIALPARAMS  DialParams;

  DWORD  dwOrigin;

  DWORD  dwReason;

  DWORD  dwCompletionID;

  DWORD  dwNumOwners;

  DWORD  dwNumMonitors;

  DWORD  dwCountryCode;

  DWORD  dwTrunk;

  DWORD  dwCallerIDFlags;

  DWORD  dwCallerIDSize;

  DWORD  dwCallerIDOffset;

  DWORD  dwCallerIDNameSize;

  DWORD  dwCallerIDNameOffset;

  DWORD  dwCalledIDFlags;

  DWORD  dwCalledIDSize;

  DWORD  dwCalledIDOffset;

  DWORD  dwCalledIDNameSize;

  DWORD  dwCalledIDNameOffset;

  DWORD  dwConnectedIDFlags;

  DWORD  dwConnectedIDSize;

  DWORD  dwConnectedIDOffset;

  DWORD  dwConnectedIDNameSize;

  DWORD  dwConnectedIDNameOffset;

  DWORD  dwRedirectionIDFlags;

  DWORD  dwRedirectionIDSize;

  DWORD  dwRedirectionIDOffset;

  DWORD  dwRedirectionIDNameSize;

  DWORD  dwRedirectionIDNameOffset;

  DWORD  dwRedirectingIDFlags;

  DWORD  dwRedirectingIDSize;

  DWORD  dwRedirectingIDOffset;

  DWORD  dwRedirectingIDNameSize;

  DWORD  dwRedirectingIDNameOffset;

  DWORD  dwAppNameSize;

  DWORD  dwAppNameOffset;

  DWORD  dwDisplayableAddressSize;

  DWORD  dwDisplayableAddressOffset;

  DWORD  dwCalledPartySize;

  DWORD  dwCalledPartyOffset;

  DWORD  dwCommentSize;

  DWORD  dwCommentOffset;

  DWORD  dwDisplaySize;

  DWORD  dwDisplayOffset;

  DWORD  dwUserUserInfoSize;

  DWORD  dwUserUserInfoOffset;

  DWORD  dwHighLevelCompSize;

  DWORD  dwHighLevelCompOffset;

  DWORD  dwLowLevelCompSize;

  DWORD  dwLowLevelCompOffset;

  DWORD  dwChargingInfoSize;

  DWORD  dwChargingInfoOffset;

  DWORD  dwTerminalModesSize;

  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

  DWORD  dwCallTreatment;

  DWORD  dwCallDataSize;

  DWORD  dwCallDataOffset;

  DWORD  dwSendingFlowspecSize;

  DWORD  dwSendingFlowspecOffset;

  DWORD  dwReceivingFlowspecSize;

  DWORD  dwReceivingFlowspecOffset;

} LINECALLINFO, FAR *LPLINECALLINFO;Parameters

Parameters

dwTotalSize

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.

hLine

dwLineDeviceID

dwAddressID

The address identifier of the address on the line on which this call exists. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

dwBearerMode

The current bearer mode of the call. This member uses one of the LINEBEARERMODE_ constants.

dwRate

dwMediaMode

Specifies the media type of the information stream currently on the call. This is the media type as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by the LINE_MONITORMEDIA messages. This member uses the LINEMEDIAMODE_ constants.

dwAppSpecific

Not interpreted by the API implementation and service provider. It can be set by any owner application of this call with the lineSetAppSpecific function.

dwCallID

In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call IDs and their scope is service provider-defined. The dwCallID member makes this unique identifier available to the applications.

dwRelatedCallID

Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID member may be used by the service provider for this purpose.

dwCallParamFlags

A collection of call-related parameters when the call is outgoing. These are the same call parameters specified in lineMakeCall, one or more of the LINECALLPARAMFLAGS_ constants.

dwCallStates

The call states, one or more of the LINECALLSTATE_ constants, for which the application can be notified on this call. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state.

dwMonitorDigitModes

The various digit modes, one or more of the LINEDIGITMODE_ constants, for which monitoring is currently enabled.

dwMonitorMediaModes

The various media types for which monitoring is currently enabled, one or more of the LINEMEDIAMODE_ constants.

DialParams

The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values are the same as the defaults used in the LINEDEVCAPS structure.

dwOrigin

dwReason

dwCompletionID

The completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.

dwNumOwners

The number of application modules with different call handles and owner privilege for the call.

dwNumMonitors

The number of application modules with different call handles and monitor privilege for the call.

dwCountryCode

dwTrunk

The number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls. The dwTrunk member should be set to 0xFFFFFFFF if it is unknown.

dwCallerIDFlags

Determines the validity and content of the caller, or originator, party identifier information. This member uses one of the LINECALLPARTYID_ constants.

dwCallerIDSize

dwCallerIDOffset

The size, in bytes, of the variably sized field containing the caller party ID number information, and the offset, in bytes, from the beginning of this data structure.

dwCallerIDNameSize

dwCallerIDNameOffset

The size, in bytes, of the variably sized field containing the caller party ID name information, and the offset, in bytes, from the beginning of this data structure.

dwCalledIDFlags

Determines the validity and content of the called-party ID information. The called party corresponds to the originally addressed party. This member uses one of the LINECALLPARTYID_ constants.

dwCalledIDSize

dwCalledIDOffset

The size, in bytes, of the variably sized field containing the called-party ID number information, and the offset, in bytes, from the beginning of this data structure.

dwCalledIDNameSize

dwCalledIDNameOffset

The size, in bytes, of the variably sized field containing the called-party ID name information, and the offset, in bytes, from the beginning of this data structure.

dwConnectedIDFlags

Determines the validity and content of the connected-party ID information. The connected party is the party that was actually connected to. This may be different from the called-party ID if the call was diverted. This member uses one of the LINECALLPARTYID_ constants.

dwConnectedIDSize

dwConnectedIDOffset

The size, in bytes, of the variably sized field containing the connected party identifier number information, and the offset, in bytes, from the beginning of this data structure.

dwConnectedIDNameSize

dwConnectedIDNameOffset

The size, in bytes, of the variably sized field containing the connected party identifier name information, and the offset, in bytes, from the beginning of this data structure.

dwRedirectionIDFlags

Determines the validity and content of the redirection party identifier information. The redirection party identifies the address to which the session was redirected. This member uses one of the LINECALLPARTYID_ constants.

dwRedirectionIDSize

dwRedirectionIDOffset

The size, in bytes, of the variably sized field containing the redirection party identifier number information, and the offset, in bytes, from the beginning of this data structure.

dwRedirectionIDNameSize

dwRedirectionIDNameOffset

The size, in bytes, of the variably sized field containing the redirection party identifier name information, and the offset, in bytes, from the beginning of this data structure.

dwRedirectingIDFlags

Determines the validity and content of the redirecting party identifier information. The redirecting party identifies the address which redirect the session. This member uses one of the LINECALLPARTYID_ constants.

dwRedirectingIDSize

dwRedirectingIDOffset

The size, in bytes, of the variably sized field containing the redirecting party identifier number information, and the offset, in bytes, from the beginning of this data structure.

dwRedirectingIDNameSize

dwRedirectingIDNameOffset

The size, in bytes, of the variably sized field containing the redirecting party identifier name information, and the offset, in bytes, from the beginning of this data structure.

dwAppNameSize

dwAppNameOffset

The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application's module filename is used instead.

dwDisplayableAddressSize

dwDisplayableAddressOffset

The string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that initiate calls. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.

dwCalledPartySize

dwCalledPartyOffset

The size, in bytes, of the variably sized field holding a user-friendly description of the called party, and the offset, in bytes, from the beginning of this data structure. This information can be specified with lineMakeCall and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.

dwCommentSize

dwCommentOffset

The size, in bytes, of the variably sized field holding a comment about the call provided by the application that originated the call using lineMakeCall, and the offset, in bytes, from the beginning of this data structure. This information can be optionally specified in the lpCallParams parameter whenever a new call is established.

dwDisplaySize

dwDisplayOffset

The size, in bytes, of the variably sized field holding raw display information, and the offset, in bytes, from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional information from this member pair for formatting and presentation most appropriate for this telephony configuration.

dwUserUserInfoSize

dwUserUserInfoOffset

The size, in bytes, of the variably sized field holding user-user information, and the offset, in bytes, from the beginning of this data structure The protocol discriminator field for the user-user information, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is accounted for in dwUserUserInfoSize.³

dwHighLevelCompSize

dwHighLevelCompOffset

The size, in bytes, of the variably sized field holding high-level compatibility information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).

dwLowLevelCompSize

dwLowLevelCompOffset

The size, in bytes, of the variably sized field holding low-level compatibility information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).

dwChargingInfoSize

dwChargingInfoOffset

The size, in bytes, of the variably sized field holding charging information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).

dwTerminalModesSize

dwTerminalModesOffset

The size, in bytes, of the variably sized device field containing an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. Array entries are indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this call's media stream, as specified by one of the LINETERMMODE_ constants.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably-sized field holding device-specific information, and the offset, in bytes, from the beginning of this data structure.

dwCallTreatment

The call treatment currently being applied on the call or that is applied when the call enters the next applicable state. Can be zero if call treatments are not supported.

dwCallDataSize

dwCallDataOffset

The size, in bytes, and offset from the beginning of LINECALLINFO of the application-specified call data.

dwSendingFlowspecSize

dwSendingFlowspecOffset

The total size, in bytes, and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it to the application.

dwReceivingFlowspecSize

dwReceivingFlowspecOffset

LINECALLLIST

Description

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

Function Details

typedef struct linecalllist_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwCallsNumEntries;

  DWORD  dwCallsSize;

  DWORD  dwCallsOffset;

} LINECALLLIST, FAR *LPLINECALLLIST;

Parameters

dwTotalSize

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

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

LINECALLPARMS

Description

The LINECALLPARAMS structure describes parameters supplied when making calls using the lineMakeCall and TSPI_lineMakeCall functions. The LINECALLPARAMS structure is also used as a parameter in other operations, such as the lineOpen function.

The comments to the right of the syntax block indicate the default values used when this structure is not provided to lineMakeCall.

Function Details

typedef struct linecallparams_tag {  // Defaults:

  DWORD  dwTotalSize;       // ---------

  DWORD  dwBearerMode;      // voice

  DWORD  dwMinRate;         // (3.1kHz)

  DWORD  dwMaxRate;         // (3.1kHz)

  DWORD  dwMediaMode;       // interactiveVoice

  DWORD  dwCallParamFlags;          // 0

  DWORD  dwAddressMode;     // addressID

  DWORD  dwAddressID;       // (any available)

  LINEDIALPARAMS DialParams; // (0, 0, 0, 0)

  DWORD  dwOrigAddressSize;         // 0

  DWORD  dwOrigAddressOffset;

  DWORD  dwDisplayableAddressSize;  // 0

  DWORD  dwDisplayableAddressOffset;

  DWORD  dwCalledPartySize;         // 0

  DWORD  dwCalledPartyOffset;

  DWORD  dwCommentSize;             // 0

  DWORD  dwCommentOffset;

  DWORD  dwUserUserInfoSize;        // 0

  DWORD  dwUserUserInfoOffset;

  DWORD  dwHighLevelCompSize;       // 0

  DWORD  dwHighLevelCompOffset;

  DWORD  dwLowLevelCompSize;        // 0

  DWORD  dwLowLevelCompOffset;

  DWORD  dwDevSpecificSize;         // 0

  DWORD  dwDevSpecificOffset;

;//TAPI Version 2.1

  DWORD  dwPredictiveAutoTransferStates;

  DWORD  dwTargetAddressSize;

  DWORD  dwTargetAddressOffset;

  DWORD  dwSendingFlowspecSize;

  DWORD  dwSendingFlowspecOffset;

  DWORD  dwReceivingFlowspecSize;

  DWORD  dwReceivingFlowspecOffset;

  DWORD  dwDeviceClassSize;

  DWORD  dwDeviceClassOffset;

  DWORD  dwDeviceConfigSize;

  DWORD  dwDeviceConfigOffset;

  DWORD  dwCallDataSize;

  DWORD  dwCallDataOffset;

  DWORD  dwNoAnswerTimeout;

  DWORD  dwCallingPartyIDSize;

  DWORD  dwCallingPartyIDOffset;

//TAPI Version 3.0 and higher

  DWORD  dwAddressType;

} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Parameters

dwTotalSize

The total size, in bytes, allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.

dwBearerMode

The bearer mode for the call. This member uses one of the LINEBEARERMODE_ constants.

dwMinRate

dwMaxRate

The data rate range requested for the call's data stream in bps (bits per second). When making a call, the service provider attempts to provide the highest available rate in the requested range. If a specific data rate is required, both the minimum and maxim should be set to that value. If an application works best with one rate but is able to degrade to lower rates, the application should specify these as the maximum and minimum rates, respectively. If dwMaxRate is zero, the default value is as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the maximum rate supported by the device.

dwMediaMode

The expected media type of the call. This member uses one of the LINEMEDIAMODE_ constants.

dwCallParamFlags

These flags specify a collection of Boolean call-setup parameters. This member uses one or more of the LINECALLPARAMFLAGS_ constants.

dwAddressMode

The mode by which the originating address is specified. The dwAddressMode member cannot be LINEADDRESSMODE_ADDRESSID for the lineOpen function call. This member uses one of the LINEADDRESSMODE_ constants.

dwAddressID

The address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

DialParams

Dial parameters to be used on this call, of type LINEDIALPARAMS. When a value of 0 is specified for this field, the default value for the field is used as indicated in the DefaultDialParams member of the LINEDEVCAPS structure. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.

dwOrigAddressSize

dwOrigAddressOffset

The size, in bytes, of the variably sized field holding the originating address, and the offset, in bytes, from the beginning of this data structure. The format of this address is dependent on the dwAddressMode member.

dwDisplayableAddressSize

dwDisplayableAddressOffset

The displayable string is used for logging purposes. The content of these members is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize members of the call's LINECALLINFO message. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.

dwCalledPartySize

dwCalledPartyOffset

The size, in bytes, of the variably sized field holding called-party information, and the offset, in bytes, from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.

dwCommentSize

dwCommentOffset

The size, in bytes, of the variably sized field holding comments about the call, and the offset, in bytes, from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.

dwUserUserInfoSize

dwUserUserInfoOffset

The size, in bytes, of the variably sized field holding user-user information, and the offset, in bytes, from the beginning of this data structure. The protocol discriminator field for the user-user information, if required, should appear as the first byte of the data pointed to by dwUserUserInfoOffset, and must be accounted for in dwUserUserInfoSize.⁴

dwHighLevelCompSize

dwHighLevelCompOffset

The size, in bytes, of the variably sized field holding high-level compatibility information, and the offset, in bytes, from the beginning of this data structure.

dwLowLevelCompSize

dwLowLevelCompOffset

The size, in bytes, of the variably sized field holding low-level compatibility information, and the offset, in bytes, from the beginning of this data structure.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably sized field holding device-specific information, and the offset, in bytes, from the beginning of this data structure.

dwPredictiveAutoTransferStates

The LINECALLSTATE_ constants, entry into which causes the call to be blind-transferred to the specified target address. Set to zero if automatic transfer is not desired.

dwTargetAddressSize

dwTargetAddressOffset

The size, in bytes, and offset from the beginning of LINECALLPARAMS of a string specifying the target dialable address (not dwAddressID); used in the case of certain automatic actions. In the case of predictive dialing, specifies the address to which the call should be automatically transferred. This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were not being used. Set to zero if automatic transfer is not desired. In the case of a No Hold Conference, specifies the address that should be conferenced to the call. In the case of a One Step Transfer, specifies the address to dial on the consultation call.

dwSendingFlowspecSize

dwSendingFlowspecOffset

The total size, in bytes, and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it t to the application.

dwReceivingFlowspecSize

dwReceivingFlowspecOffset

The total size, in bytes, and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it to the application.

dwDeviceClassSize

dwDeviceClassOffset

The size, in bytes, and offset from the beginning of LINECALLPARAMS of a null-terminated string (the size includes the NULL) that indicates the device class of the device whose configuration is specified in DeviceConfig. Valid device class strings are the same as those specified for the lineGetID function.

dwDeviceConfigSize

dwDeviceConfigOffset

The number of bytes and offset from the beginning of LINECALLPARAMS of the opaque configuration data structure pointed to by dwDevConfigOffset. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is zero, the default device configuration is used. This allows the application to set the device configuration before the call is initiated.

dwCallDataSize

dwCallDataOffset

The size, in bytes, and offset from the beginning of LINECALLPARAMS of the application-specified call data to be initially attached to the call.

dwNoAnswerTimeout

The number of seconds, after the completion of dialing, that the call should be allowed to wait in the PROCEEDING or RINGBACK states, before it is automatically abandoned by the service provider with a LINECALLSTATE_DISCONNECTED and LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment.

dwCallingPartyIDSize

dwCallingPartyIDOffset

The size, in bytes, and offset from the beginning of LINECALLPARAMS of a null-terminated string (the size includes the NULL) that specifies the identity of the party placing the call. If the content of the identifier is acceptable and a path is available, the service provider passes the identifier along to the called party to indicate the identity of the calling party.

dwAddressType

The address type used for the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

LINECALLSTATUS

Description

The LINECALLSTATUS structure describes the current status of a call. The information in this structure depends on the device capabilities of the address, the ownership of the call by the invoking application, and the current state of the call being queried. The lineGetCallStatus and TSPI_lineGetCallStatus functions return the LINECALLSTATUS structure.

Function Details

typedef struct linecallstatus_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwCallState;

  DWORD  dwCallStateMode;

  DWORD  dwCallPrivilege;

  DWORD  dwCallFeatures;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

  DWORD  dwCallFeatures2;

  SYSTEMTIME  tStateEntryTime;

} LINECALLSTATUS, FAR *LPLINECALLSTATUS;

Parameters

dwTotalSize

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.

dwCallState

Specifies the current call state of the call using one of the LINECALLSTATE_ constants.

dwCallStateMode

The interpretation of the dwCallStateMode member is call-state-dependent. In many cases, the value will be zero.

dwCallPrivilege

The application's privilege for this call. This member uses one or more of the LINECALLPRIVILEGE_ constants.

dwCallFeatures

These flags indicate the telephony API functions that can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the call in its current state; a one indicates the feature can be invoked. This member uses LINECALLFEATURE_ constants.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.

dwCallFeatures2

Indicates additional functions can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. An extension of the dwCallFeatures member. This member uses LINECALLFEATURE2_ constants.

tStateEntryTime

LINEDEVCAPS

Description

The LINEDEVCAPS structure describes the capabilities of a line device. The lineGetDevCaps function and the TSPI_lineGetDevCaps function return the LINEDEVCAPS structure.

Function Details

typedef struct linedevcaps_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwProviderInfoSize;

  DWORD  dwProviderInfoOffset;

  DWORD  dwSwitchInfoSize;

  DWORD  dwSwitchInfoOffset;

  DWORD  dwPermanentLineID;

  DWORD  dwLineNameSize;

  DWORD  dwLineNameOffset;

  DWORD  dwStringFormat;

  DWORD  dwAddressModes;

  DWORD  dwNumAddresses;

  DWORD  dwBearerModes;

  DWORD  dwMaxRate;

  DWORD  dwMediaModes;

  DWORD  dwGenerateToneModes;

  DWORD  dwGenerateToneMaxNumFreq;

  DWORD  dwGenerateDigitModes;

  DWORD  dwMonitorToneMaxNumFreq;

  DWORD  dwMonitorToneMaxNumEntries;

  DWORD  dwMonitorDigitModes;

  DWORD  dwGatherDigitsMinTimeout;

  DWORD  dwGatherDigitsMaxTimeout;

  DWORD  dwMedCtlDigitMaxListSize;

  DWORD  dwMedCtlMediaMaxListSize;

  DWORD  dwMedCtlToneMaxListSize;

  DWORD  dwMedCtlCallStateMaxListSize;

  DWORD  dwDevCapFlags;

  DWORD  dwMaxNumActiveCalls;

  DWORD  dwAnswerMode;

  DWORD  dwRingModes;

  DWORD  dwLineStates;

  DWORD  dwUUIAcceptSize;

  DWORD  dwUUIAnswerSize;

  DWORD  dwUUIMakeCallSize;

  DWORD  dwUUIDropSize;

  DWORD  dwUUISendUserUserInfoSize;

  DWORD  dwUUICallInfoSize;

  LINEDIALPARAMS  MinDialParams;

  LINEDIALPARAMS  MaxDialParams;

  LINEDIALPARAMS  DefaultDialParams;

  DWORD  dwNumTerminals;

  DWORD  dwTerminalCapsSize;

  DWORD  dwTerminalCapsOffset;

  DWORD  dwTerminalTextEntrySize;

  DWORD  dwTerminalTextSize;

  DWORD  dwTerminalTextOffset;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

  DWORD  dwLineFeatures;

  DWORD  dwSettableDevStatus;

  DWORD  dwDeviceClassesSize;

  DWORD  dwDeviceClassesOffset;

//TAPI Version 2.2

  GUID   PermanentLineGuid;

//TAPI Version 3.0

  DWORD  dwAddressTypes;

  GUID   ProtocolGuid;

  DWORD  dwAvailableTracking;

} LINEDEVCAPS, FAR *LPLINEDEVCAPS;

Parameters

dwTotalSize

dwNeededSize

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

dwUsedSize

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

dwProviderInfoSize

dwProviderInfoOffset

The size, in bytes, of the variably sized field containing service provider information, and the offset, in bytes, from the beginning of this data structure. The dwProviderInfoSize/Offset member is intended to provide information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwSwitchInfoSize

dwSwitchInfoOffset

The size, in bytes, of the variably sized device field containing switch information, and the offset, in bytes, from the beginning of this data structure. The dwSwitchInfoSize/Offset member is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.

dwPermanentLineID

The permanent DWORD identifier by which the line device is known in the system's configuration. This permanent name, as opposed to dwDevice ID, does not change as lines are added or removed from the system and persists through operating system upgrades. It can therefore be used to link line-specific information in .ini files (or other files) in a way that is not affected by adding or removing other lines or by changing the operating system.

dwLineNameSize

dwLineNameOffset

The size, in bytes, of the variably sized device field containing a user-configurable name for this line device, and the offset, in bytes, from the beginning of this data structure. This name can be configured by the user when configuring the line device's service provider, and is provided for the user's convenience.

dwStringFormat

The string format used with this line device. This member uses one of the STRINGFORMAT_ constants.

dwAddressModes

The mode by which the originating address is specified. This member uses the LINEADDRESSMODE_ constants.

dwNumAddresses

The number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.

dwBearerModes

Flag array that indicates the different bearer modes that the address is able to support. This member uses one or more of the LINEBEARERMODE_ constants.

dwMaxRate

Contains the maximum data rate, in bits per second, for information exchange over the call.

dwMediaModes

Flag array that indicates the different media types the address is able to support. This member uses one or more of the LINEMEDIAMODE_ constants.

dwGenerateToneModes

The different kinds of tones that can be generated on this line. This member uses one or more of the LINETONEMODE_ constants.

dwGenerateToneMaxNumFreq

Specifies the maximum number of frequencies you can configure for the lineGenerateTone setting in the LINEGENERATETONE data structure. A value of 0 indicates that tone generation is not available.

dwGenerateDigitModes

Specifies the digit modes than can be generated on this line. This member uses one or more of the LINEDIGITMODE_ constants.

dwMonitorToneMaxNumFreq

Specifies the maximum number of frequencies you can configure for the lineMonitorTones setting in the the LINEMONITORTONE data structure. A value of 0 indicates that tone monitor is not available.

dwMonitorToneMaxNumEntries

Contains the maximum number of entries that can be specified in a tone list to lineMonitorTones.

dwMonitorDigitModes

Specifies the digit modes than can be detected on this line. This member uses one or more of the LINEDIGITMODE_ constants.

dwGatherDigitsMinTimeout

dwGatherDigitsMaxTimeout

These members contain the minimum and maximum values, in milliseconds, that can be specified for both the first digit and inter-digit timeout values used by lineGatherDigits. If both these members are zero, timeouts are not supported.

dwMedCtlDigitMaxListSize

dwMedCtlMediaMaxListSize

dwMedCtlToneMaxListSize

dwMedCtlCallStateMaxListSize

These members contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of lineSetMediaControl respectively.

dwDevCapFlags

Specifies various Boolean device capabilities. This member uses one or more of the LINEDEVCAPFLAGS_ constants.

dwMaxNumActiveCalls

Provides the maximum number of (minimum bandwidth) calls that can be active connected on the line at any one time. The actual number of active calls may be lower if higher bandwidth calls have been established on the line.

dwAnswerMode

Specifies the effect on the active call when answering another offering call on a line device. This member uses one of the LINEANSWERMODE_ constants.

dwRingModes

Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.

dwLineStates

Specifies the different line status components for which the application may be notified in a LINE_LINEDEVSTATE message on this line. This member uses one or more of the LINEDEVSTATE_ constants.

dwUUIAcceptSize

Specifies the maximum size of user-user information that can be sent during a call accept.⁵

dwUUIAnswerSize

Specifies the maximum size of user-user information that can be sent during a call answer.1

dwUUIMakeCallSize

Specifies the maximum size of user-user information that can be sent during a make call.1

dwUUIDropSize

Specifies the maximum size of user-user information that can be sent during a call drop.1

dwUUISendUserUserInfoSize

Specifies the maximum size of user-user information that can be sent separately any time during a call with lineSendUserUserInfo.1

dwUUICallInfoSize

Specifies the maximum size of user-user information that can be received in the LINECALLINFO structure.1

MinDialParams

MaxDialParams

These members contain the minimum and maximum values, in milliseconds, for the dial parameters that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings is service provider-specific.

DefaultDialParams

Contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.

dwNumTerminals

The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal IDs and range from zero to one less than the value indicated by dwNumTerminals.

dwTerminalCapsSize

dwTerminalCapsOffset

The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.

dwTerminalTextEntrySize

The size, in bytes, of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.

dwTerminalTextSize

dwTerminalTextOffset

The size, in bytes, of the variably sized field containing descriptive text about each of the line's available terminals, and the offset, in bytes, from the beginning of this data structure. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.

dwLineFeatures

Specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member allows an application to discover which line features can be (and which can never be) supported by the device.

dwSettableDevStatus

dwDeviceClassesSize

dwDeviceClassesOffset

Length, in bytes, and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by NULLs; the last identifier in the list is followed by two NULLs.

PermanentLineGuid

dwAddressTypes

The address type used for the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

ProtocolGuid

The current TAPI Protocol. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher. The protocols are declared in tapi3.h.

dwAvailableTracking

Available tracking, as represented by a LINECALLHUBTRACKING constant. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

LINEDEVSTATUS

Description

The LINEDEVSTATUS structure describes the current status of a line device. The lineGetLineDevStatus function and the TSPI_lineGetLineDevStatus function return the LINEDEVSTATUS structure.

Function Details

typedef struct linedevstatus_tag {

  DWORD  dwTotalSize;

  DWORD  dwNeededSize;

  DWORD  dwUsedSize;

  DWORD  dwNumOpens;

  DWORD  dwOpenMediaModes;

  DWORD  dwNumActiveCalls;

  DWORD  dwNumOnHoldCalls;

  DWORD  dwNumOnHoldPendCalls;

  DWORD  dwLineFeatures;

  DWORD  dwNumCallCompletions;

  DWORD  dwRingMode;

  DWORD  dwSignalLevel;

  DWORD  dwBatteryLevel;

  DWORD  dwRoamMode;

  DWORD  dwDevStatusFlags;

  DWORD  dwTerminalModesSize;

  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;

  DWORD  dwDevSpecificOffset;

  DWORD dwAvailableMediaModes;

  DWORD dwAppInfoSize;

  DWORD dwAppInfoOffset;

} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Parameters

dwTotalSize

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.

dwNumOpens

dwOpenMediaModes

Bit array that indicates for which media types the line device is currently open.

dwNumActiveCalls

The number of calls on the line in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.

dwNumOnHoldCalls

dwNumOnHoldPendCalls

The number of calls on the line in the onholdpendingtransfer or onholdpendingconference state.

dwLineFeatures

Specifies the line-related API functions that are currently available on this line. This member uses one or more of the LINEFEATURE_ constants.

dwNumCallCompletions

dwRingMode

dwSignalLevel

The current signal level of the connection on the line. This is a value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).

dwBatteryLevel

The current battery level of the line device hardware. This is a value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).

dwRoamMode

The current roam mode of the line device. This member uses one of the LINEROAMMODE_ constants.

dwDevStatusFlags

The status flags indicate information such as whether the device is locked. It consists of one or more members of LINEDEVSTATUSFLAGS_ constants.

dwTerminalModesSize

dwTerminalModesOffset

The size, in bytes, of the variably sized device field containing an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using the lineSetTerminal function for this line. Each entry uses one or more of the LINETERMMODE_ constants.

dwDevSpecificSize

dwDevSpecificOffset

The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.

dwAvailableMediaModes

Indicates the media types that can be invoked on new calls created on this line device, when the dwLineFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media types are available, in which case any or all of the media types indicated in the dwMediaModes member in LINEDEVCAPS may be available.

dwAppInfoSize

dwAppInfoOffset

Length, in bytes, and offset from the beginning of LINEDEVSTATUS of an array of LINEAPPINFO structures. The dwNumOpens member indicates the number of elements in the array. Each element in the array identifies an application that has the line open.

LINEFORWARD

Description

The LINEFORWARD structure describes an entry of the forwarding instructions. The LINEFORWARDLIST and the LINEADDRESSSTATUS structures can contain an array of LINEFORWARD structures.

Function Details

typedef struct lineforward_tag {

  DWORD  dwForwardMode;

  DWORD  dwCallerAddressSize;

  DWORD  dwCallerAddressOffset;

  DWORD  dwDestCountryCode;

  DWORD  dwDestAddressSize;

  DWORD  dwDestAddressOffset;

// TAPI version 3.1

  DWORD  dwCallerAddressType;

  DWORD  dwDestAddressType

} LINEFORWARD, FAR *LPLINEFORWARD;

Parameters

dwForwardMode

The types of forwarding. This member uses one of the LINEFORWARDMODE_ constants.

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.

dwCallerAddressType

Windows XP: The address type of the caller. This member of the structure is available only if the negotiated version of TAPI is 3.1 or higher.

dwDestAddressType

Windows XP: The address type for the called destination. This member of the structure is available only if the negotiated version of TAPI is 3.1 or higher.

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.

Function Details

typedef struct linemessage_tag {

  DWORD  hDevice;

  DWORD  dwMessageID;

  DWORD_PTR  dwCallbackInstance;

  DWORD_PTR  dwParam1;

  DWORD_PTR  dwParam2;

  DWORD_PTR  dwParam3;

} LINEMESSAGE, FAR *LPLINEMESSAGE;

Parameters

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

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

dwParam2

dwParam3

¹ Cisco Unified CME TSP 2.1 does not support user-user information. This should be set to NULL.

² Cisco Unified CME TSP 2.1 does not support user-user information. This should be set to NULL.

³ Cisco Unified CME TSP 2.1 does not support user-user information. This should be set to NULL.

⁴ Cisco Unified CME TSP 2.1 does not support user-user information. This should be set to NULL.

⁵ Cisco Unified CME TSP 2.1 does not support user-user information. This should be set to NULL.

Table Of Contents