TAPI Developer Guide for Cisco CME/SRST

Telephony Application Programmer's Interface (TAPI) is the set of classes and principles of operation that constitute a telephony application programming interface. TAPI implementations are the interface between computer telephony applications and telephony services.

The Cisco TAPI Service Provider (TSP) allows PC software developers to create customized IP telephony applications for Cisco IP Phone users; for example, Contact Management applications that require telephony integration to handle inbound and outbound telephone calls. The Cisco TSP enables the Cisco IP Telephony system to integrate with Microsoft Windows™ user-level applications that support the Microsoft Windows TAPI standard.

The Cisco TAPI implementation uses the Microsoft™ TAPI specification to support Cisco IP Telephony Solutions. To enable a Cisco TAPI-based solutions, the following are essential:

Purpose

This document describes the Cisco TAPI implementation for Cisco CallManager Express (CME) and Cisco Survivable Site Telephony (SRST), detailing the functions that comprise the implementation software and illustrating how to use these functions to create applications that support the Cisco IP Telephony hardware, software, and processes.

One of the primary goals of a standard Application Programming Interface (API), such as TAPI, is to provide an unchanging programming interface under which varied implementations may stand. Cisco's TAPI implementation is designed to conform as closely as possible to the TAPI specification.

Audience

This document is intended for telephony software engineers who are developing Cisco telephony applications that require TAPI. This document assumes that the engineer is familiar with both the C or C++ languages and the Microsoft™ TAPI specification.

Related Documentation

For more information about TAPI specifications, creating an application to use TAPI, or TAPI administration see:

•

The Microsoft Telephony Application Programming Interface (TAPI) Programmer's Reference

Conventions

Cisco Connection Online

Cisco Connection Online (CCO) is Cisco Systems' primary, real-time support channel. Maintenance customers and partners can self-register on CCO to obtain additional information and services.

Convention	Description
boldface font	Commands and keywords are in boldface.
italic font	Arguments for which you supply values are in italics.
[ ]	Elements in square brackets are optional.
{ x \| y \| z }	Alternative keywords are grouped in braces and separated by vertical bars.
[ x \| y \| z ]	Optional alternative keywords are grouped in brackets and separated by vertical bars.
string	An unquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.
screen font	Terminal sessions and information the system displays are in screen font.
boldface screen font	Information you must enter is in boldface screen font.
italic screen	Arguments for which you supply values are in italic screen font.

Available 24 hours a day, 7 days a week, CCO provides a wealth of standard and value-added services to Cisco's customers and business partners. CCO services include product information, product documentation, software updates, release notes, technical tips, the Bug Navigator, configuration notes, brochures, descriptions of service offerings, and download access to public and authorized files.

CCO serves a wide variety of users through two interfaces that are updated and enhanced simultaneously: a character-based version and a multimedia version that resides on the World Wide Web (WWW). The character-based CCO supports Zmodem, Kermit, Xmodem, FTP, and Internet e-mail, and it is excellent for quick access to information over lower bandwidths. The WWW version of CCO provides richly formatted documents with photographs, figures, graphics, and video, as well as hyperlinks to related information.

•

Modem: From North America, 408 526-8070; from Europe, 33 1 64 46 40 82. Use the following terminal settings: VT100 emulation; databits: 8; parity: none; stop bits: 1; and connection rates up to 28.8 kbps.

For a copy of CCO's Frequently Asked Questions (FAQ), contact cco-help@cisco.com. For additional information, contact cco-team@cisco.com.

Note If you are a network administrator and need personal technical assistance with a Cisco product that is under warranty or covered by a maintenance contract, contact Cisco's Technical Assistance Center (TAC) at 800 553-2447, 408 526-7209, or tac@cisco.com. To obtain general information about Cisco Systems, Cisco products, or upgrades, contact 800 553-6387, 408 526-7208, or cs-rep@cisco.com.

Documentation CD-ROM

Cisco documentation and additional literature are available in a CD-ROM package, which ships with your product. The Documentation CD-ROM, a member of the Cisco Connection Family, is updated monthly. Therefore, it might be more current than printed documentation. To order additional copies of the Documentation CD-ROM, contact your local sales representative or call customer service. The CD-ROM package is available as a single package or as an annual subscription. You can also access Cisco documentation on the World Wide Web at http://www.cisco.com, http://www-china.cisco.com, or http://www-europe.cisco.com.

If you are reading Cisco product documentation on the World Wide Web, you can submit comments electronically. Click Feedback in the toolbar and select Documentation. After you complete the form, click Submit to send it to Cisco. We appreciate your comments.

Architecture

Cisco CallManager Express provides support for SCCP-based IP phones, allowing access to IOS Voice Gateway services, to IOS telephony interfaces for connection to the PSTN, and to Voice-over-Packet interfaces for VoIP calls using H.323 and SIP. See Figure 1.

From the perspective of most, general, IOS Voice Gateway services, the SCCP-based IP phones appear as normal FXS-port-connected analog phones. This enables IOS Voice Gateway services to route calls to and from SCCP IP phones in the same way it routes calls to and from analog phones that are directly connected to FXS voice ports on the router. This also allows SCCP IP phones to benefit from and leverage the standard IOS Voice Gateway VoIP protocols for making VoIP calls across the WAN/Internet.

The Cisco CME TAPI interface allows a TAPI-aware application program running under Microsoft Windows™ on a Personal Computer to assert simple 1-to-1 remote control of an individual IP phone.

Note The TAPI interface does not allow a single PC to simultaneously control multiple IP phones.

The TAPI interface is designed to support only signaling operations, such as placing and receiving calls. The TAPI interface does not support the sending of voice media packets to and from the PC.

The TAPI interface can be used to control the on-hook and off-hook state of a single phone line on a single IP phone. It also supports the sending of dialing digits from the PC to Cisco CME so that the PC can instruct the Cisco CME to place an outbound call using the IP phone, as in address-book dialing.

When an incoming call is presented to the SCCP phone, a notification message can also be sent to the PC that includes incoming caller-id information. The TAPI-aware application can use this information to cause a "screen-pop" notification of the incoming call to PC user. The PC can then instruct the IP phone to answer the call (in speakerphone mode or with a headset), or reject the call and forward it elsewhere, such as to voicemail.

The Cisco CME TAPI interface is designed to support personal productivity software applications running on an individual PC, and to help automate the handling of incoming and outgoing calls to an IP phone.

The Microsoft Windows™ TSP driver for Cisco CME plugs into the TSPI layer interface provided by Microsoft TAPI and converts the TSPI function calls into SCCP control messages that are sent across TCP/IP to the IOS router. SCCP messages indicate operations such as on-hook, off-hook, keypad-digit press, and soft-key press. The Cisco CME router also sends SCCP messages to the TSP driver to indicate operations such as ringer-on, ringer-off, dial-tone, call-display information, and call state.

Restrictions

•

The TAPI interface does not allow a single PC to simultaneously control multiple IP phones.

TAPI/TSPI Implementation

Table 1 lists the supported TAPI/TSPI functions. For more details about these functions, see the Microsoft™ TSPI reference.

Table 1 Supported TAPI/TSPI Line Functions at a Glance
TAPI Function	TSPI Function	Description
lineAnswer	TSPI_lineAnswer	Answers the specified offering call.
lineAddToConference	TSPI_lineAddToConference
lineBlindTransfer	TSPI_lineBlindTransfer	Performs a blind or single-step transfer of the specified call to the specified destination address.
lineClose	TSPI_lineCloseCall	Closes the specified open line device after completing or aborting all outstanding calls and asynchronous operations on the device.
lineCompleteTransfer	TSPI_lineCompleteTransfer	Completes the transfer of the specified call to the party connected in the consultation call.
lineDial	TSPI_lineDial	Dials the specified dialable number on the specified call.
lineDrop	TSPI_lineDrop	Drops or disconnects the specified call.
lineGetAddressID	TSPI_lineGetAddressID	Returns the address identifier associated with address in a different format on the specified line.
	TSPI_lineGetCallAddressID	Retrieves the address identifier for the indicated call.
lineGetCallInfo	TSPI_lineGetCallInfo	Returns detailed information about the specified call.
lineGetCallStatus	TSPI_lineGetCallStatus	Returns the current status of the specified call.
lineGetDevConfig	TSPI_lineGetDevConfig	Returns a data structure object, the contents of which are specific to the line (service provider) and device class, giving the current configuration of a device associated one-to-one with the line device.
	TSPI_lineGetExtensionID	Returns the extension identifier that the service provider supports for the indicated line device.
lineGetID	TSPI_lineGetID	Returns a device identifier for the specified device class associated with the selected line, address, or call.
	TSPI_lineGetNumAddressIDs	Retrieves the number of address identifiers supported on the indicated line.
lineHold	TSPI_lineHold	Places the specified call on hold.
lineMakeCall	TSPI_lineMakeCall	Places a call on the specified line to the specified destination address.
lineNegotiateExtVersion	TSPI_lineNegotiateExtVersion	Returns the highest extension version number the service provider can operate under for this device, given the range of possible extension versions.
	TSPI_lineNegotiateTSPIVersion	Returns the highest SPI version the service provider can operate under for this device, given the range of possible SPI versions.
lineOpen	TSPI_lineOpen	Opens the line device whose device identifier is given, returning the service provider's handle for the device.
lineSetCallParams	TSPI_lineSetCallParams	Sets certain parameters for an existing call.
	TSPI_lineSetDefaultMediaDetection	Tells the service provider the new set of media types to detect for the indicated line, replacing any previous set.
lineSetStatusMessages	TSPI_lineSetStatusMessages	Enables TAPI to specify which notification messages the service provider should generate for events related to status changes for the specified line or any of its addresses.
lineSetupTransfer	TSPI_lineSwapHold	Initiates a transfer of the call specified by hdCall.
lineUnhold	TSPI_lineUnhold	Retrieves the specified held call.

Call Control Functions

Flow Diagrams

Initialization

Application to Skinny IP Phone

Hold Call

Call Transfer

Appendix A

This section provides an quick reference for supported TSPI functions and messages. For complete information on TAPI and TSPI functions, see Microsoft™ TSPI reference.

TSPI Line Functions

TSPI_lineAddToConference

The TSPI_lineAddToConference function adds a call to a conference call. The call being added and the conference call are specified by hdConfCall.

•

hdConfCall—The handle to the conference call. The call state of hdConfCall can be onHoldPendingConference or onHold.

•

hdConsultCall —The handle to the call to be added to the conference call. This call cannot be either a parent of another conference or a participant in any conference.

Depending on the device capabilities indicated in LINEADDRESSCAPS, the hdConsultCall parameter may not necessarily have been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference.

The call state of hdConsultCall can be connected, onHold, proceeding, or ringback.

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

•

The service provider returns LINEERR_INVALCALLHANDLE if hdConsultCall is a parent of another conference or already a participant in a conference.

•

It also provides the same return value if hdConsultCall cannot be added or if it has been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference.

•

Any monitoring (media, tones, digits) on a conference call applies only to the hdConfCall parameter, not to the individual participating calls.

TSPI_lineAnswer

•

hdCall—The service provider's handle to the call to be answered. The call state of hdCall can be offering or accepted.

•

lpsUserUserInfo—A pointer to a null-terminated string containing user-user information to be sent to the remote party at the time of answering the call. If this pointer is NULL, it indicates that no user-user information is to be sent. User-user information is only sent if supported by the underlying network, as indicated in LINEDEVCAPS.

•

dwSize—The size, in bytes, of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

•

When a new call arrives, the service provider sends TAPI a LINE_NEWCALL message to exchange handles for the call. The service provider follows this with a LINE_CALLSTATE message to inform TAPI and its client applications of the call's state. A client application typically answers the call using TSPI_lineAnswer. Typically, after the call is successfully answered, the call transitions to the connected state.

•

In some telephony environments, like ISDN, where user alerting is separate from call offering, TAPI and its client applications may have the option to first accept a call prior to answering, or instead to reject or redirect the offering call.

•

If a call is offered at the time another call is already active, the new call is connected to by invoking TSPI_lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold. The appropriate LINE_CALLSTATE messages are used to report state transitions to TAPI about both calls.

TSPI_lineBlindTransfer

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

•

hdCall—The service provider's handle to the call to be transferred. The call state of hdCall can be connected.

•

lpszDestAddress—A pointer to a null-terminated Unicode string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.

•

dwCountryCode—The country code of the destination. The implementation should use this to select the call progress protocols for the destination address. If a value of 0 is specified, the service provider should use a default. TAPI does not validate dwCountryCode when this function is called.

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding async_completion is zero if the function succeeds or an error number if an error occurs.

•

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

•

In a blind transfer, no consultation call is made visible to TAPI. Typically, after the blind transfer is completed, the specified call is cleared from the line it was on and transitions to the idle state.

•

The service provider call handle must remain valid after the transfer is completed. The handle becomes invalid when it is no longer interested in the transferred call using TSPI_lineCloseCall.

TSPI_lineCloseCall

The TSPI_lineClose function closes the specified open line device after completing or aborting all outstanding calls and asynchronous operations on the device.

•

hdLine—The service provider's handle to the line to be closed. After the line is successfully closed, this handle is no longer valid.

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

•

The service provider must report completion for every asynchronous operation. If TSPI_lineClose is called for a line on which there are outstanding asynchronous operations, the operations are reported complete with an appropriate result or error code before this procedure returns.

•

A similar requirement exists for active calls on the line. Outstanding operations must be reported complete with appropriate result or error codes. Active calls must also be dropped, if required, and if this behavior was indicated by the LINEDEVCAPFLAGS_CLOSEDROP bit in the LINEDEVCAPS structure.

•

After this procedure returns, the service provider must report no further htCall on the line or calls that were on the line. The service provider handles for the line and calls on the line become "invalid."

•

The service provider must relinquish nonsharable resources it reserves while the line is open. For example, closing a line accessed through a comm port and modem should result in closing the comm port, making it once again available for use by other applications.

•

The service provider does not issue the LINE_LINEDEVSTATE message in response to this function invocation because the line closes and there is no longer any interest in its state changes.

TSPI_lineCompleteCall

The TSPI_lineCompleteCall function specifies how to connect a call that cannot be normally completed. 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.

•

hdCall—The service provider's handle to the call whose completion is requested. The call state of hdCall can be busy, ringback, or proceeding.

•

lpdwCompletionID—A pointer to a DWORD-sized memory location where the service provider writes a completion identifier. This uniquely identifies a completion request in progress on the line that contains the hdCall. A completion identifier becomes invalid after the request completes or is canceled using the TSPI_lineUncompleteCall function. The service provider is free to reuse the completion identifier as soon as it becomes invalid.

•

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

•

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. This parameter is not validated by TAPI when this function is called.

Returns dwRequestID or an error number if an error occurs. The lResult parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

This function is considered complete when the request is accepted by the network or switch.

When the called station or network enters a state where the call can be completed as requested, the service provider must send a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well.

It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling TSPI_lineUncompleteCall.

TSPI_lineCompleteTransfer

The TSPI_lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the original call handle is changed to a conference call. Otherwise, the service provider should send call state messages changing the calls to idle.

•

hdCall—The service provider's handle to the call to be transferred. The call state of hdCall can be onHoldPendingTransfer.

•

hdConsultCall—A handle to the call that represents a connection to the destination of the transfer. The call state of hdConsultCall can be connected, ringback, busy, or proceeding.

•

htConfCall—This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must save this parameter value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. Otherwise this parameter is ignored.

•

lphdConfCall—A pointer to an HDRVCALL representing the service provider's identifier for the call. This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must fill this location with its handle for the new conference call before returning from this function.

•

dwTransferMode—Specifies how the initiated transfer request is to be resolved. This parameter uses one of the LINETRANSFERMODE_ constants.

•

This function completes the transfer of the original call, hdCall, to the party currently connected through hdConsultCall. The consultation call is typically dialed on the consultation call allocated as part of TSPI_lineSetupTransfer, but it can be any call to which the switch is capable of transferring hdCall.

•

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected through hdCall and hdConsultCall are connected to each other, and both hdCall and hdConsultCall transition to the idle state.

•

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid, but transition to the conferenced state. A conference call handle is created and returned, and it transitions to the connected state.

•

It may also be possible to perform a blind transfer of a call using TSPI_lineBlindTransfer.

•

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT message for the new call or include it in call counts in messages or status data structures for the line.

TSPI_lineDial

The TSPI_lineDial function dials the specified dialable number on the specified call.

•

hdCall—The service provider's handle to the call to be dialed. The call state of hdCall can be any state except idle and disconnected.

•

lpszDestAddress—Pointer to a null-terminated Unicode string that specifies the destination to be dialed using the standard dialable number format.

•

dwCountryCode—The country code of the destination. The implementation uses this to select the call progress protocols for the destination address. If a value of 0 is specified, a default call-progress protocol defined by the service provider is used. TAPI does not validate this parameter when this function is called.

•

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow dialing.

•

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

•

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineDial (for example, no partial dialing, and no going offhook). This is because the service provider should pre-scan the number for unsupported characters first.

•

TSPI_lineDial is used for dialing on an existing call appearance; for example, call handles returned from TSPI_lineMakeCall with NULL as the lpszDestAddress or ending in ';', call handles returned from TSPI_lineSetupTransfer or TSPI_lineSetupConference. TSPI_lineDial can be invoked multiple times in the course of dialing in the case of multistage dialing, if the line's device capabilities permit it.

•

If the string pointed to by the lpszDestAddress parameter in the previous call to the TSPI_lineMakeCall or TSPI_lineDial function is terminated with a semicolon, an empty string in the current call to TSPI_lineDial indicates that dialing is complete.

•

Multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses, and return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

•

Dialing is considered complete after the address has been accepted by the service provider, not after the call is finally connected. Service providers that provide inverse multiplexing may allow multiple addresses to be provided at once. The service provider must send LINE_CALLSTATE messages to TAPI to inform it about the progress of the call.

TSPI_lineDrop

The TSPI_lineDrop function drops or disconnects the specified call. User-user information can optionally be transmitted as part of the call disconnect. This function can be called by the application at any time. When TSPI_lineDrop returns, the call should be idle.

•

hdCall—The service provider's handle to the call to be dropped. The call state of hdCall can be any state except idle.

•

lpsUserUserInfo—This pointer is only valid if dwSize is nonzero. It specifies a pointer to a null-terminated string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

•

dwSize—The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

•

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow the call to be dropped.

•

When invoking TSPI_lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to TAPI for all calls whose call state is affected. Typically, a dropped call transitions to the idle state. Invoking TSPI_lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

•

In situations where the call to be dropped is a consultation call established during transfer or conference call establishment, the original call that was placed in the OnHoldPending state is reconnected to and it typically re-enters the connected call state.

•

TAPI has the option to send user-user information at the time of the drop. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

Note In various bridged or party line configurations when multiple parties are on the call, TSPI_lineDrop may not actually clear the call.

TSPI_lineGetAddressID

The TSPI_lineGetAddressID function returns the address identifier associated with address in a different format on the specified line.

•

hdLine—The service provider's handle to the line whose address is to be retrieved.

•

lpdwAddressID—A pointer to a DWORD-sized memory location where the address identifier is returned.

•

dwAddressMode—The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have one and only one of the LINEADDRESSMODE_ constants.

•

lpsAddress—A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by the dwAddressMode parameter. If it is LINEADDRESSMODE_DIALABLEADDR, the lpsAddress parameter uses the common dialable number format and is NULL terminated.

•

dwSize—The size of the address contained in lpsAddress. The parameter dwSize must be set to the length of the string (plus one for the NULL) if LINEADDRESSMODE_DIALABLEADDR is used. If an extended LINEADDRESSMODE is used, the length should match the size of whatever is actually passed in (the DLL checks to be sure it can read the number of bytes specified from the given pointer).

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

This function is used to map a phone number (address) assigned to a line device back to its dwAddressID (in the range from 0 through the number of addresses minus one) that is returned in the line's device capabilities.

TSPI_lineGetCallAddressID

The TSPI_lineGetCallAddressID function retrieves the address identifier for the indicated call.

•

hdCall—The service provider's handle to the call whose address identifier is to be retrieved. The call state of hdCall can be any state.

•

lpdwAddressID—A pointer to a DWORD into which the service provider writes the call's address identifier.

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

•

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers it should consistently choose one of these address identifiers as the primary identifier reported by this function and in the LINECALLINFO data structure.

•

This function has no direct correspondence at the TAPI level. It gives TAPI sufficient information to implement the lineGetNewCalls function invoked with the LINECALLSELECT_ADDRESS option.

TSPI_lineGetCallInfo

The TSPI_lineGetCallInfo function returns detailed information about the specified call.

•

hdCall—The service provider's handle to the call whose call information is to be retrieved. The call state of hdCall can be any state.

•

lpCallInfo—A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information.

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

Table 2 indicates which members of the LINECALLINFO data structure are filled in by TAPI and which members are filled in by the service provider. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Table 2 LINECALLINFO Data Structure
Member name	TAPI	Service provider
dwTotalSize;	X
dwNeededSize;		X
dwUsedSize;		X
hLine;	X
dwLineDeviceID;		X
dwAddressID;		X
dwBearerMode;		X
dwRate;		X
dwMediaMode;		X
dwAppSpecific;		X
dwCallID;		X
dwRelatedCallID;		X
dwCallParamFlags;		X
dwCallStates;	X	X
dwMonitorDigitModes;	X
dwMonitorMediaModes;	X
DialParams;		X
dwOrigin;		X
dwReason;		X
dwCompletionID;		X
dwNumOwners;	X
dwNumMonitors;	X
dwCountryCode;		X
dwTrunk;		X
dwCallerIDFlags;		X
dwCallerIDSize;		X
dwCallerIDOffset;		X
dwCallerIDNameSize;		X
dwCallerIDNameOffset;		X
dwCalledIDFlags;		X
dwCalledIDSize;		X
dwCalledIDOffset;		X
dwCalledIDNameSize;		X
dwCalledIDNameOffset;		X
dwConnectedIDFlags;		X
dwConnectedIDSize;		X
dwConnectedIDOffset;		X
dwConnectedIDNameSize;		X
dwConnectedIDNameOffset;		X
dwRedirectionIDFlags;		X
dwRedirectionIDSize;		X
dwRedirectionIDOffset;		X
dwRedirectionIDNameSize;		X
dwRedirectionIDNameOffset;		X
dwRedirectingIDFlags;		X
dwRedirectingIDSize;		X
dwRedirectingIDOffset;		X
dwRedirectingIDNameSize;		X
dwRedirectingIDNameOffset;		X
dwAppNameSize;	X
dwAppNameOffset;	X
dwDisplayableAddressSize;	X
dwDisplayableAddressOffset;	X
dwCalledPartySize;	X
dwCalledPartyOffset;	X
dwCommentSize;	X
dwCommentOffset;	X
dwDisplaySize;		X
dwDisplayOffset;		X
dwUserUserInfoSize;		X
dwUserUserInfoOffset;		X
dwHighLevelCompSize;		X
dwHighLevelCompOffset;		X
dwLowLevelCompSize;		X
dwLowLevelCompOffset;		X
dwChargingInfoSize;		X
dwChargingInfoOffset;		X
dwTerminalModesSize;		X
dwTerminalModesOffset;		X
dwDevSpecificSize;		X
dwDevSpecificOffset;		X

TAPI fills in the size and offset fields for the dwAppNameSize/Offset, dwCalledPartySize/Offset, and dwCommentSize/Offset members and updates the value in dwUsedSize to reflect these after calling the service provider.

After the service provider returns from the TSPI_lineGetCallInfo function, TAPI sets the dwCallStates member of the LINECALLINFO structure as follows:

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers, it should consistently choose one of these address identifiers as the primary identifier reported by this function in the LINECALLINFO data structure.

TSPI_lineGetCallStatus

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

•

hdCall—The service provider's handle to the call to be queried for its status. The call state of hdCall can be any state.

•

lpCallStatus—A pointer to a variably sized data structure of type LINECALLSTATUS. This structure is filled with call status information.

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

•

The following table indicates which members of the LINECALLSTATUS data structure are filled in by the service provider and which members are filled in by TAPI. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Table 3
Member name	TAPI	Service provider
dwTotalSize;	X
dwNeededSize;		X
dwUsedSize;		X
dwCallState;		X
dwCallStateMode;		X
dwCallPrivilege;	X
dwCallFeatures;		X
dwDevSpecificSize;		X
dwDevSpecificOffset;		X

•

TSPI_lineGetCallStatus returns the dynamic status of a call, whereas TSPI_lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available TSPI functions TAPI can invoke on the call while the call is in this state.

TSPI_lineGetDevConfig

The TSPI_lineGetDevConfig function returns a data structure object, the contents of which are specific to the line (service provider) and device class, giving the current configuration of a device associated one-to-one with the line device.

•

lpDeviceConfig—A pointer to a data structure of type VARSTRING where the device configuration structure of the associated device is returned. Upon successful completion of the request, the service provider fills this data structure with the device configuration. The dwStringFormat member in the VARSTRING structure must be set to STRINGFORMAT_BINARY. If the dwTotalSize member of the VARSTRING structure pointed to by the lpDeviceConfig parameter is greater than or equal to the size of the fixed portion of the structure, the service provider sets the dwNeededSize member to the required size and returns zero.

•

lpszDeviceClass—A pointer to a null-terminated Unicode string that specifies the device class of the device whose configuration is requested. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a line device (dwSelect has the value LINECALLSELECT_LINE).

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

Table Of Contents