3.1.7 Overall comparison with TAPI

The TSPI specification is very closely related to the TAPI specification. Most of the functions in one interface have a corresponding function in the other interface. The usual correspondence is as follows:

TSPI functions have the same names as TAPI functions except that they are prepended with "TSPI_". For example, the TAPI function lineAccept corresponds to the TSPI function TSPI_lineAccept. The only functions that differ from this naming convention are the callback functions. In the case of callback functions only a procedure-pointer type name is defined, rather than a procedure name. Actual names of callbacks are "hidden" inside the TAPI DLL.
Procedures that allow asynchronous operation insert a dwRequestID parameter of type DRV_REQUESTID as their first parameter. This parameter specifies the value to be returned to indicate asynchronous operation and to report asynchronous completion.
hCall parameters of type HCALL are replaced with hdCall parameters of type HDRVCALL, indicating the Service Provider's opaque handle for the call.
hLine parameters of type HLINE are replaced with hdLine parameters of type HDRVLINE, indicating the Service Provider's opaque handle for the line.
hPhone parameters of type HPHONE are replaced with hdPhone parameters of type HDRVPHONE, indicating the Service Provider's opaque handle for the phone.
Procedures that create a new call, such as TSPI_lineMakeCall, replace a single lphCall parameter with two parameters: a htCall of type HTAPICALL that passes in the TAPI DLL's opaque handle for the call, and a lphdCall of type LPHDRVCALL that indicates the location to which the Service Provider must write its new opaque handle for the call. A similar split of parameters occurs in TSPI_lineOpen and TSPI_phoneOpen.
At the TSPI level, there is no notion of "privilege" associated with device handles. Furthermore, there is only ever one outstanding handle for a line, phone, or call device at a time. As a consequence the error codes and status messages relating to privilege and number of clients using a device do not appear at the TSPI level.

In the descriptions that follow comparisons that fall under the categories listed above are usually not mentioned explicitly. In cases where the function differs from the corresonding TAPI function in other ways, there is usually a "comparison" section describing the difference.

3.1.7.0 ASYNC_LINE_COMPLETION

Syntax

ASYNC_LINE_COMPLETION Line_Completion;void (* Line_Completion) (dwRequestID, lResult)

This type is a placeholder for a callback function implemented by the TAPI DLL and supplied to the Service Provider early in the initialization sequence. The Service Provider calls this function to report the completion of a line-oriented request that it executes asynchronously.

3.1.7.0 ASYNC_PHONE_COMPLETION

Syntax

ASYNC_PHONE_COMPLETION Phone_Completion;void (* Phone_Completion) (dwRequestID, lResult)

This type is a placeholder for a callback function implemented by the TAPI DLL and supplied to the Service Provider early in the initialization sequence. The Service Provider calls this function to report the completion of a phone-oriented request that it executes asynchronously.

3.1.7.0 LINEEVENT

Syntax

LINEEVENT Line_Event; void (* Line_Event) (htLine, htCall, dwMsg, dwParam1, dwParam2, dwParam3)

This type is a placeholder for a callback function implemented by the TAPI DLL and supplied to the Service Provider at the time a line device is opened. The Service Provider calls this function to report spontaneously occurring events on the line or on calls on the line.

3.1.7.0 PHONEEVENT

Syntax

PHONEEVENT Phone_Event;void (* Phone_Event) (htPhone, dwMsg, dwParam1, dwParam2, dwParam3)

This type is a placeholder for a callback function implemented by the TAPI DLL and supplied to the Service Provider at the time a phone device is opened. The Service Provider calls this function to report spontaneously occurring events on the phone.

3.1.7.0 TSPI_lineAccept

Syntax

LONG TSPI_lineAccept(dwRequestID, hdCall, lpsUserUserInfo, dwSize) This function accepts the specified offered call. It may optionally send the specified user-to-user information to the calling party.
Specifies a far pointer to a string containing user-to-user information to be sent to the remote party as part of the call accept. This pointer is NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see ).
Specifies the size in bytes of the user-to-user information in . If is NULL, no user-to-user information is sent to the calling party and is ignored.

3.1.7.0 TSPI_lineAddToConference

Parameters

DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

3.1.7.0 TSPI_lineAnswer

Syntax

LONG TSPI_lineAnswer(dwRequestID, hdCall, lpsUserUserInfo, dwSize)

This function answers the specified offering call.
Specifies a far pointer to a string containing user-to-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-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see ).
Specifies the size in bytes of the user-to-user information in . If is NULL, no user-to-user information is sent to the calling party and is ignored.

3.1.7.0 TSPI_lineBlindTransfer

Syntax

LONG TSPI_lineBlindTransfer(dwRequestID, hdCall, lpszDestAddress, dwCountryCode) This function performs a blind or single-step transfer of the specified call to the specified destination address.

3.1.7.0 TSPI_lineClose

Syntax void TSPI_lineClose(hdLine)

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

Parameters HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Value None. This function is presumed to complete successfully and synchronously.

Call States Not applicable

Comments The Service Provider has the responsibility to (eventually) report completion for every operation it decides to execute asynchronously. If this procedure is called for a line on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. Generally the TAPI DLL would wait for these to complete in an orderly fashion. However, the Service Provider should be prepared to handle an early call to TSPI_lineClose in "abort" or "emergency shutdown" situtations.

A similar requirement exists for active calls on the line. Such calls must be dropped, with outstanding operations reported complete with appropriate result or error codes.

After this procedure returns the Service Provider must report no further events on the line or calls that were on the line. The Service Provider's opaque handles for the line and calls on the line become "invalid".

The Service Provider must relinquish non-sharable 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 available for use by other applications.

Comparison This operation is strictly synchronous with presumed success in contrast to the lineClose function defined at the TAPI level which allows for failure and asynchronous operation.

The Service Provider does not issue the LINE_LINEDEVSTATE message in response to this function invocation, since the line becomes closed and there is no longer any interest in its state changes.

See Also Messages: LINE_CLOSE, LINE_LINEDEVSTATE

3.1.7.0 TSPI_lineCloseCall

Syntax void TSPI_lineCloseCall(hdCall)

This function deletes the call after completing or aborting all outstanding asynchronous operations on the call.

Parameters HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be deleted. After the call has been successfully deleted, this handle is no longer valid.

Return Value None. This function is presumed to complete successfully and synchronously.

Call States Any

Comments The Service Provider has the responsibility to (eventually) report completion for every operation it decides to execute asynchronously. If this procedure is called for a call on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. If there is an active call on the line at the time of TSPI_lineCloseCall, the call must bedropped. Generally the TAPI DLL would wait for calls to be finished and asynchronous operations to complete in an orderly fashion. However, the Service Provider should be prepared to handle an early call to TSPI_lineCloseCall in "abort" or "emergency shutdown" situtations.

After this procedure returns the Service Provider must report no further events on the call. The Service Provider's opaque handle for the call becomes "invalid".

Comparison There is no function that directly corresonds to this operation at the TAPI level. The nearest thing is lineHandoff when invoked with parameters requesting that a call handle be invalidated. The TAPI DLL generally calls TSPI_lineCloseCall when the the call has been dropped using TSPI_lineDrop (completed successfully) and the last application interested in the call invalidates its handle.

See Also Functions: TSPI_lineDrop

3.1.7.0 TSPI_lineCompleteCall

Syntax LONG TSPI_lineCompleteCall(dwRequestID, hdCall, lpdwCompletionID, dwCompletionMode, dwMessageID)

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

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call whose completion is requested.

LPDWORD lpdwCompletionID

Specifies a far pointer to a DWORD-sized memory location where the Service Provider writes a completion ID. This uniquely identifies a completion request in progress on the line that contains the hdCall. Otherwise the TAPI DLL can make no assumptions about its value. In particular, a completion ID becomes invalid after the request completes or is cancelled using the function TSPI_lineUncompleteCall. The Service Provider is free to reuse the completion ID as soon as it becomes invalid.

DWORD dwCompletionMode

Specifies the way in which the call is to be completed, of type LINECALLCOMPLMODE. Values are:

LINECALLCOMPLMODE_CAMPON

Queues the call until the call can be completed. The call remains in a non idle state while queued.

LINECALLCOMPLMODE_CALLBACK

Requests the called station to return the call when it returns to idle.

LINECALLCOMPLMODE_INTRUDE

Requests that the call be added to an existing physical call at the called station (barge in).

LINECALLCOMPLMODE_MESSAGE

Leave a short predefined message for the called station (Leave Word Calling). The message to be sent is specified via dwMessageID.

DWORD dwMessageID

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

Return Value Returns zero if the function is successful, the (positive) dwRequestID value if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_INVALCALLCOMPLMODE

The specified completion is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_COMPLETIONOVERRUN

The maximum number of outstanding call completions has been exceeded.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall busy, noAnswer

Comments 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 will typically transition to idle. When the called station or network enters a state where the call can be completed as requested, the TAPI DLL will be notified via a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record will list the reason for the call as CALLCOMPLETION and provide the completion ID as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion ID is also used to refer to each individual request so requests can be canceled by calling TSPI_lineUncompleteCall.

See Also Functions: TSPI_lineGetCallInfo, TSPI_lineUncompleteCall

Messages: LINE_CALLSTATE

Data Types: LINECALLSTATUS, LINECALLINFO, LINECALLCOMPLMODE

3.1.7.0 TSPI_lineCompleteTransfer

Syntax LONG TSPI_lineCompleteTransfer(dwRequestID, hdCall, hdConsultCall, htConfCall, lphdConfCall, dwTransferMode)

This function completes the transfer of the specified call to the party connected in the consultation call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be transferred.

HDRVCALL hdConsultCall

Specifies a handle to the call that represents a connection with the destination of the transfer.

HTAPICALL htConfCall

Specifies the TAPI DLL's opaque handle to the new call. If dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE then the Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. Otherwise this parameter is ignored.

LPHDRVCALL lphdConfCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the call. If dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE then the Service Provider must fill this location with its opaque handle for the new conference call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously). If dwTransferMode is some other value this parameter is ignored.

DWORD dwTransferMode

Specifies how the initiated transfer request is to be resolved, of type LINETRANSFERMODE. Values are:

LINETRANSFERMODE_TRANSFER

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

LINETRANSFERMODE_CONFERENCE

Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the TAPI DLL.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCONSULTCALLHANDLE

The specified consultation call handle is invalid.

LINEERR_INVALCALLSTATE

One or both calls are not in a valid state for the requested operation.

LINEERR_INVALTRANSFERMODE

The specified transfer mode parameter is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall onHoldPendingTransfer

hdConsultCall connected, ringback, busy

Comments This operation completes the transfer of the original call, hdCall, to the party currently connected via hdConsultCall. The consultation call will typically have been dialed on the consultation call allocated as part of TSPI_lineSetupTransfer, but it may 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 via hdCall and hdConsultCall will be connected to each other, and both hdCall and hdConsultCall will typically be removed from the line they were on and both will transition to the idle state. Note that the Service Provider's opaque handles for these calls must remain valid after the transfer has completed. The TAPI DLL causes these handles to be invalidated when it is no longer interested in them using TSPI_lineCloseCall.

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

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

See Also Functions: TSPI_lineSetupTransfer, TSPI_lineCloseCall, TSPI_lineBlindTransfer

Messages: LINE_CALLSTATE

3.1.7.0 TSPI_lineConditionalMediaDetection

Syntax LONG TSPI_lineConditionalMediaDetection(hdLine, dwMediaModes, lpCallParams)

If the Service Provider can monitor for the indicated set of media modes AND support the capabilities indicated in lpCallParams, then it sets the indicated media moditoring modes for the line and replies with a "success" indication. Otherwise, it leaves the media monitoring modes for the line unchanged and replies with a "failure" indication. The function operates strictly synchronously.

Parameters HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to have media monitoring and parameter capabilities tested and set.

DWORD dwMediaModes

Specifies the media mode(s) of interest to the app, of type LINEMEDIAMODE. The dwMediaModes parameter is used to register the app as a potential target for inbound call and call hand off for the specified media mode. This parameter is ignored if the OWNER flag is not set in dwPrivileges. Values are:

LINEMEDIAMODE_NONE

This is used as a NULL value for the data type. The app is not interested to be the target of any handoff or inbound calls.

LINEMEDIAMODE_UNKNOWN

The app wants to handle calls of unknown media type; i.e., unclassified calls.

LINEMEDIAMODE_INTERACTIVEVOICE

The app wants to handle calls of the interactive voice media type; i.e., it manages live voice calls.

LINEMEDIAMODE_AUTOMATEDVOICE

The app wants to handle calls in which there is voice data managed by an automated application. In cases where the Service Provider does not distinguish between automated or interactive voice, this should be treated the same as interactive voice.

LINEMEDIAMODE_DIGITALDATA

The app wants to handle calls of the digital data media type.

LINEMEDIAMODE_G3FAX

The app wants to handle calls of the group 3 fax media type.

LINEMEDIAMODE_G4FAX

The app wants to handle calls of the group 4 fax media type.

LINEMEDIAMODE_DATAMODEM

The app wants to handle calls with the data modem media mode.

LINEMEDIAMODE_TELETEX

The app wants to handle calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The app wants to handle calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The app wants to handle calls with the telex media mode.

LINEMEDIAMODE_MIXED

The app wants to handle calls with the ISDN mixed media mode.

LINEMEDIAMODE_TDD

The app wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_ADSI

The app wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

LPLINECALLPARAMS const lpCallParams

Specifies a far pointer to a structure of type LINECALLPARAMS. It describes the call parameters that the line device should be able to provide. The only relevant fields of lpCallParams for the purposes of this test are the following:

DWORD dwBearerMode; dwMinRate; dwMaxRate; dwMediaMode; dwCallParamFlags;

Return Value Returns zero if the function is successful, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_NOMEM

Unable to allocate or lock memory.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_NODRIVER

The driver was not properly installed.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States Not applicable.

Comments A TAPI lineOpen that specifies the device ID LINE_MAPPER typically results in calling this procedure for multiple line devices to hunt for a suitable line, possibly also opening as-yet unopened lines. A "success" result indicates that the line is suitable for the calling application's requirements. Note that the media monitoring modes demanded at the TSPI level are the union of monitoring modes demanded by multiple applications at the TAPI level. As a consequence of this, it is most common for multiple media mode flags to be set simultaneously at this level. The Service Provider test to determine if it can support at least the specified set regardless of what modes are currently in effect.

The Device ID LINE_MAPPER is never used at the TSPI level.

Comparison There is no directly corresponding function at the TAPI level. This procedure corresponds to the "test" implied for each individual line by the lineOpen procedure when it is called with the device ID LINE_MAPPER.

See Also Functions: lineClose

Data Types: LINEMEDIAMODE, LINECALLPARAMS

3.1.7.0 TSPI_lineDevSpecific

Syntax LONG TSPI_lineDevSpecific(dwRequestID, hdLine, dwAddressID, hdCall, lpParams, dwSize)

This function is used as a general extension mechanism to enable service providers to provide access to features not described in other operations. The meaning of the extensions are device-specific, and taking advantage of these extensions requires the application to be fully aware of them.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to be operated on.

DWORD dwAddressID

Specifies the address on the specified line to be operated on.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be operated on.

LPVOID lpParams

Specifies a far pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific.

DWORD dwSize

The size in bytes of the parameter block area.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Additional error returns are device specific.

Call States hdCall Device specific

Comments This operation provides a generic parameter profile. The interpretation of the parameter structure is device specific. In particular, any of the hdLine, dwAddressID, and hdCall parameters may be unused. Indications and replies sent back to the application that are device specific should use the LINE_DEVSPECIFIC message.

This function is called in direct response to an application calling the TAPI function lineDevSpecific. The TAPI DLL translates the hLine and hCall parameters used at the TAPI level to the corresponding hdLine and hdCall parameters used at the TSPI level. The lpParams buffer is passed through unmodified.

Note also that the lpParams data structure should not contain any pointers since they would not be properly translated (thunked) when running a 16 bit application in a 32 bit version of the Telephony DLL and vice versa.

A service provider can provide access to device specific functions by defining parameters for use with this operation. Applications that want to make use of these device specific extensions should consult the device specific (i.e., vendor specific) documentation that describes what extensions are defined. Note that an app that relies on these device specific extensions will typically not be portable to work with other service provider environments.

This operation is part of the extended telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if the TAPI DLL has successfully negotiated and selected a device-specific extension version.

See Also Messages: LINE_DEVSPECIFIC

3.1.7.0 TSPI_lineDevSpecificFeature

Syntax LONG TSPI_lineDevSpecificFeature(dwRequestID, hdLine, dwFeature, lpParams, dwSize)

This function is used as an extension mechanism to enable service providers to provide access to features not described in other operations. The meaning of these extensions are device-specific, and taking advantage of these extensions requires the TAPI DLL or its client application to be fully aware of them.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line device.

DWORD dwFeature

Specifies the feature to invoke on the line device, of type PHONEBUTTONFUNCTION.

LPVOID lpParams

Specifies a far pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific.

DWORD dwSize

Specifies the size of the buffer in bytes.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Additional error returns are device specific.

Call States hdCall Device specific.

Comments This function provides the TAPI DLL and its client applications with phone feature button emulation capabilities. When the TAPI DLL invokes this operation on behalf of a client application, it specifies the equivalent of a button press event. This method of invoking features is highly device dependent, as the API does not define the their meaning. Note that an app that relies on these device specific extensions will typically not be portable to work with other service provider environments.

This function is called in direct response to an application calling the TAPI function lineDevSpecificFeature. The TAPI DLL translates the hLine parameter used at the TAPI level to the corresponding hdLine parameter used at the TSPI level. The lpParams buffer is passed through unmodified.

See Also Messages: LINE_DEVSPECIFICFEATURE

Data Types: PHONEBUTTONFUNCTION

3.1.7.0 TSPI_lineDial

Syntax LONG TSPI_lineDial(dwRequestID, hdCall, lpszDestAddress, dwCountryCode)

This function dials the specified dialable number on the specified call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be dialed.

LPCSTR const lpszDestAddress

Specifies the destination to be dialed using the standard dialable number format.

DWORD dwCountryCode

Specifies the country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, then a service provider defined default call progress protocol is used.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_INVALADDRESS

The specified character buffer for the destination address to be dialed contains invalid characters or digits (i.e., syntax error); no dialing has been done.

LINEERR_INVALPARAM

The specified country code is invalid.

LINEERR_INVALCALLSTATE

The current state of the call does not allow dialing.

LINEERR_ADDRESSBLOCKED

The specified address is blocked from being dialed on the specified call.

LINEERR_BILLINGREJECTED

The billing information specified as part of the destination address has been rejected.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall Any state except idle and disconnected

Comments TSPI_lineDial 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. TSPI_lineDial would be used to perform the dialing of this consultation call. Note that TSPI_lineDial may be invoked multiple times in the course of dialing in the case of multi-stage dialing, if the line's device capabilities allows it. Also, multiple addresses may 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 completed 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 require multiple addresses to be provided at onece. The service provider sends LINE_CALLSTATE messages to the TAPI DLL to inform it about the progress of the call. To abort a call attempt while a call is being established, the TAPI DLL may invoke TSPI_lineDrop.

See Also Messages: LINE_CALLSTATE

3.1.7.0 TSPI_lineDrop

Syntax LONG TSPI_lineDrop(dwRequestID, hdCall, lpsUserUserInfo, dwSize)

This functions drops or disconnects the specified call. The TAPI DLL has the option to specify user-to-user information to be transmitted as part of the call disconnect.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be dropped.

LPCSTR const lpsUserUserInfo

Specifies a far pointer to a string containing user-to-user information to be sent to the remote party as part of the call disconnect. This pointer is unused if dwUserUserInfoSize is zero and no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize

Specifies the size in bytes of the user-to-user information in lpsUserUserInfo. If zero, then lpsUserUserInfo can be left NULL, and no user-to-user information will be sent to the remote party.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_INVALCALLSTATE

The current state of the call does not allow the call to be dropped.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall any state

Comments When invoking TSPI_lineDrop related calls may sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to the TAPI DLL for all calls whose call state is affected. A dropped call will typically transition to the idle state.

Invoking TSPI_lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

Invoking TSPI_lineDrop on a consultation call that was set up using either TSPI_lineSetupTransfer or TSPI_lineSetupConference, will cancel the consultation call. Some switches automatically unhold the other call.

The TAPI DLL has the option to send user-to-user information at the time of the drop. Even if user-to-user information can be sent, often no guarantees are made that the network will deliver this information to the remote party.

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

See Also Functions: TSPI_lineGetDevCaps

3.1.7.0 TSPI_lineForward

Syntax LONG TSPI_lineForward(dwRequestID, hdLine, bAllAddresses, dwAddressID, lpForwardList, dwNumRingsNoAnswer, htConsultCall, lphdConsultCall)

This function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel specific forwarding currently in effect.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to be forwarded.

BOOL bAllAddresses

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

DWORD dwAddressID

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

LPLINEFORWARDLIST const lpForwardList

Specifies a far pointer to a variable size data structure that describes the specific forwarding instructions, of type LINEFORWARDLIST.

DWORD dwNumRingsNoAnswer

Specifies the number of rings before a call is considered a "no answer".

HTAPICALL htConsultCall

Specifies the TAPI DLL's opaque handle to the new call. In some telephony environments, forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to. In such an environment, the Service Provider creates the new consutation call and must save this value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. If no consultation call is created, this value is ignored.

LPHDRVCALL lphdConsultCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the call. In telephony environments where forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to, the Service Provider must fill this location with its opaque handle for the call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. The Service Provider is permitted to do callbacks regarding the new call before it returns from this procedure If no consultation call is created, the HDRVCALL must be left NULL.

LINEERR_INVALLINEHANDLE

The specified line device handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALPARAM

The specified forward list parameter contains invalid information.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States Not applicable.

Comments Forwarding of the address(es) remains in effect until this function is called again. The most recent forwarding list replaces the old one. Forwarding can be canceled by specifying a NULL pointer as lpForwardList. If a NULL destination address is specified for an entry in the forwarding list, then the operation acts as a do not disturb.

Be aware that forwarding status of an address may also be affected externally. For example via administrative actions at the switch, or by a user from another station. It may not be possible for the service provider to be aware of this state change, and may not be able to keep in sync with the forwarding state known to the switch.

Since the NULL value returned into lphdConsultCall is the only way for the TAPI DLL to determine whether or not the Service Provider created a consultation call, the Service Provider can not use NULL as a valid opaque call handle.

Comparison This function differs from the TAPI in that it follows the TSPI model for beginning the lifetime of a call; the TAPI DLL and Service Provider exchange opaque handles representing the call with one another. In addition, the Service Provider is permitted to do callbacks regarding the new call before it returns from this procedure.

See Also Functions: lineGetAddressStatus

Messages: LINE_ADDRESSSTATUS

Data Types: LINEFORWARDLIST

3.1.7.0 TSPI_lineGatherDigits

Syntax LONG TSPI_lineGatherDigits(dwRequestID, hdCall, dwEndToEndID, dwDigitModes, lpsDigits, dwNumDigits, lpszTerminationDigits, dwFirstDigitTimeout, dwInterDigitTimeout)

This function initiates the buffered gathering of digits on the specified call. The TAPI DLL specifies a buffer in which to place the digits and the maximum number of digits to be collected.

Digit collection is terminated in a variety of ways. Firstly, the requested number of digits has been collected. Secondly, one of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned. Thirdly, one of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, etc. digit is not received within that time amount from the previously detected digit, and a partial buffer is returned. A fourth method for terminating (i.e., canceling) digit detection is by calling this operation again while collection is in progress. The old collection session is terminated and the content of the old buffer is undefined. The mechanism for canceling digit gathering without initiating another is by invoking this operation with lpsDigits equal to NULL.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call on which digit gathering is to be performed.

DWORD dwEndToEndID

Specifies a unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GATHERDIGITS message is sent. The Service Provider includes this identifier as one of the parameters in the message.

DWORD dwDigitModes

Specifies the digit mode(s) that are to be monitored, of type LINEDIGITMODE.

LINEDIGITMODE_PULSE

Detect digits as audible click that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

LPSTR lpsDigits

Specifies a far pointer to the buffer where detected digits are to be stored as ASCII characters. Note that digits may not show up in the buffer one at a time as they are collected. Only after a LINE_GATHERDIGITS message is received should the content of the buffer be assumed to be valid. If lpsDigits is specified as NULL the digit gathering currently in progress on the call is canceled and the dwNumDigits parameter is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.

DWORD dwNumDigits

Specifies the number of digits to be collected before a LINE_GATHERDIGITS message is sent to the TAPI DLL. dwNumDigits is ignored when lpsDigits is NULL. This function will fail if dwNumDigits is zero.

LPCSTR const lpszTerminationDigits

Specifies a NULL-terminated string of termination digits as ASCII characters. If one of the digits in the string is detected, then that termination digit is appended to the buffer, digit collection is terminated and the LINE_GATHERDIGITS message is sent to the TAPI DLL.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

DWORD dwFirstDigitTimeout

Specifies the time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, then digit collection is aborted and a LINE_GATHERDIGITS message is sent to the TAPI DLL. The buffer only contains the NULL character, indicating no digits were received and the first digit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported.

DWORD dwInterDigitTimeout

Specifies the maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, then digit collection is aborted and a LINE_GATHERDIGITS message is sent to the TAPI DLL. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALDIGITMODE

The specified digit mode is not available.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALDIGITS

The specified termination digits are not valid.

LINEERR_INVALPARAM

The dwNumDigits parameter is invalid.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall any state

Comments This function is considered successful if digit collection has been correctly initiated; not when digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an ASCII NULL character.

Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the connected state.

The message LINE_GATHERDIGITS is ordinarily sent when the digit buffer becomes filled. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled via another TSPI_lineGatherDigits request on the call. Only one gather digits request can be active at a time.

The TAPI DLL can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to the TAPI DLL. Both buffered and unbuffered digit detection can be enabled for the same call simultaneously.

The Service Provider is allowed some variation in the quality of timing it uses for this function, including not doing timings at all. The quality of timing is reported in LINEDEVCAPS, in the fields dwGatherDigitsMinTimeout and dwGatherDigitsMaxTimeout.

See Also Functions: TSPI_lineGetDevCaps, TSPI_lineMonitorDigits

Messages: LINE_GATHERDIGITS

Data Types: LINEDEVCAPS, LINEDIGITMODE

3.1.7.0 TSPI_lineGenerateDigits

Syntax LONG TSPI_lineGenerateDigits(dwRequestID, hdCall, dwEndToEndID, dwDigitMode, lpszDigits, dwDuration)

This function initiates the generation of the specified digits on the specified call as in-band tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking TSPI_lineGenerateDigits or TSPI_lineGenerateTone while digit generation is in progress aborts the current digit generation or tone generation in progress and initiates the generation of the most recently specified digits or tone.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call on which digit generation is to be done.

DWORD dwEndToEndID

Specifies a unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GENERATE message is sent. The Service Provider includes this identifier as one of the parameters in the message.

DWORD dwDigitMode

Indicates the format to be used for signaling these digits, of type LINEDIGITMODE. Values are:

LINEDIGITMODE_PULSE

Uses pulse/rotary for digit signaling. Valid digits for pulse mode are '0' through '9'.

LINEDIGITMODE_DTMF

Uses DTMF tones for digit signaling. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

LPCSTR const lpszDigits

Specifies a far pointer to a NULL terminated character buffer that contains the digits to be generated.

Valid characters for pulse mode are '0' through '9' and ',' (comma). Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#', and ',' (comma). A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined. The line's device capabilities indicates what this duration is. Multiple commas may be used to inject longer pauses. Invalid digits are ignored during the generation.

DWORD dwDuration

Specifies both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of zero will use a default value.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALDIGITMODE

The specified digit mode is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall Any state

Comments The TSPI_lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated; not when all digits have been generated. Contrary to TSPI_lineDial, which dials digits in a network dependent fashion, TSPI_lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. TSPI_lineGenerateDigits is generally not suitable for making calls or dialing, it is intendent for end-to-end signaling over an established call.

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the TAPI DLL.

Note that only one inband generation request at a time (tone generation or digit generation) is allowed to be in progress per call.

Be aware that, depending on the service provider and hardware, the TAPI DLL may monitor the digits it generates itself. It is the reponsibility of the TAPI DLL or its clients to filter digit monitoring appropriately while generating digits.

See Also Functions: TSPI_lineGenerateTone, TSPI_lineDial

Messages: LINE_GENERATE

Data Types: LINEDIGITMODE

3.1.7.0 TSPI_lineGenerateTone

Syntax LONG TSPI_lineGenerateTone(dwRequestID, hdCall, dwEndToEndID, dwToneMode, dwDuration, dwNumTones, lpTones)

This function generates the specified tone inband over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation generation currently in progress on the specified call. Invoking TSPI_lineGenerateTone or TSPI_lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation in progress and initiates the generation of the newly specified tone or digits.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call on which tone generation is to be performed.

DWORD dwEndToEndID

DWORD dwToneMode

Defines the tone to be generated, of type LINETONEMODE. Tones can be either standard or custom. A custom tone is composed of set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified via dwDuration for both standard and custom tones. Values are:

LINETONEMODE_CUSTOM

The tone is a custom tone, defined by the specified frequencies.

LINETONEMODE_RINGBACK

The tone to be generated is ring tone. The exact ringback tone is service provider defined.

LINETONEMODE_BUSY

The tone is a standard (station) busy tone. The exact busy tone is service provider defined.

LINETONEMODE_BEEP

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

LINETONEMODE_BILLING

The tone is billing information tone such as a credit card prompt tone. The exact billing tone is service provider defined.

A value of zero for dwToneMode cancels tone generation.

DWORD dwDuration

Specifies duration in milliseconds during which the tone should be sustained.

DWORD dwNumTones

Specifies the number of entries in the lpTones array. This field is ignored if dwToneMode is not equal to LINETONEMODE_CUSTOM.

LPLINEGENERATETONE const lpTones

Specifies a far pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter may be left NULL for non custom tones.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_INVALTONEMODE

The specified tone mode parameter is invalid.

LINEERR_INVALTONE

The specified custom tone does not represent a valid tone, or is made up of too many frequencies.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States hdCall Any state

Comments TSPI_lineGenerateTone is considered to have completed successfully when the tone generation has been successfully initiated; not when the generation of the tone is done. The function allows the inband generation of several predefined tones, such as ring back, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence and volume. Since these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to the TAPI DLL.

Note that only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if tone generation is currently in progress on a call, invoking either TSPI_lineGenerateDigits or TSPI_lineGenerateTone will cancel the tone generation.

See Also Functions: TSPI_lineGenerateDigits

Messages: LINE_GENERATE

Data Types: LINEGENERATETONE

3.1.7.0 TSPI_lineGetAddressCaps

Syntax LONG TSPI_lineGetAddressCaps(dwRequestID, dwDeviceID, dwAddressID, dwTSPIVersion, dwExtVersion, lpAddressCaps)

This function queries the specified address on the specified line device to determine its telephony capabilities.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

DWORD dwDeviceID

Specifies the line device containing the address to be queried.

DWORD dwAddressID

Specifies the address on the given line device whose capabilities are to be queried.

DWORD dwTSPIVersion

Specifies the version number of the Telephony SPI to be used. The high order word contains the major version number; the low order word contains the minor version number.

DWORD dwExtVersion

Specifies the version number of the service provider-specific 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; the low order word contain the minor version number.

LPLINEADDRESSCAPS lpAddressCaps

Specifies a far pointer to a variable sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information.

LINEERR_BADDEVICEID

The specified line device ID is out of the range of line devices IDs supported by this driver.

LINEERR_INVALADDRESSID

The specified address ID is out of range.

LINEERR_INCOMPATIBLEVERSION

The specified TSPI and/or extension version number is not supported by the Service Provider for the specified line device.

LINEERR_INVALEXTVERSION

The app requested an invalid extension version number.

LINEERR_NODRIVER

The driver was not properly installed.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable

Comments The line device IDs supported by a particular driver are numbered sequentially starting at a value set by the TAPI DLL using the TSPI_lineSetDeviceIDBase function.

The version number supplied has been negotiated by the TAPI DLL using TSPI_lineNegotiateTSPIVersion.

Comparison This function differs from the lineGetAddressCaps function at the TAPI DLL in that no Application handle is passed. Furthermore, the interface version number is for the TSPI rather than TAPI.

See Also Data Types: LINEADDRESSCAPS

Functions: TSPI_lineSetDeviceIDBase, TSPI_lineNegotiateTSPIVersion

Fields: The following table indicates which fields of the LINEADDRESSCAPS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetAddressID

Syntax LONG TSPI_lineGetAddressID(dwRequestID, hdLine, lpdwAddressID, dwAddressMode, lpsAddress, dwSize)

This operation returns the address ID associated with address in a different format on the specified line.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line whose address is to be retrieved.

LPDWORD lpdwAddressID

Specifies a far pointer to a DWORD-sized memory location where the address ID is returned.

DWORD dwAddressMode

Specifies the address mode of the address contained in lpAddress, of type LINEADDRESSMODE. Values are:

LINEADDRESSMODE_ADDRESSID

The address is specified via a small integer in the range 0 to dwNumAddresses - 1, where dwNumAddresses is the value in the line's device capabilities.

LINEADDRESSMODE_DIALABLEADDR

The address is specified via its dialable address. lpAddress is the dialable address or canonical address format.

LPCSTR const lpsAddress

Specifies a far pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode parameter. If a DIALABLEADDR, the lpsAddress uses the common dialable number format and is NULL-terminated.

DWORD dwSize

Specifies the size of the address contained in lpAddress.

LINEERR_INVALLINEHANDLE

The specified device handle is invalid.

LINEERR_INVALADDRESSMODE

The specified address mode is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALADDRESS

The specified address is not assigned to the specified line or is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable

Comments This function is used to map a phone number (address) assigned to a line device back to its dwAddressID in the range 0 to the number of addresses - 1 returned in the line's device capabilities. TSPI_lineMakeCall allows the TAPI DLL to make a call by specifying a line handle and an address on the line. The address can be specified either as a dwAddressID, as a phone number, or as a device specific name or identifier. Using a phone number may be practical in environments where a single line is assigned lots of addresses.

See Also Functions: TSPI_lineMakeCall

Data Types: LINEADDRESSMODE

3.1.7.0 TSPI_lineGetAddressStatus

Syntax LONG TSPI_lineGetAddressStatus(dwRequestID, hdLine, dwAddressID, lpAddressStatus)

This operation allows the TAPI DLL to query the specified address for its current status.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line containing the address to be queried.

DWORD dwAddressID

Specifies an address on the given open line device. This is the address to be queried.

LPLINEADDRESSSTATUS lpAddressStatus

Specifies a far pointer to a variable sized data structure of type LINEADDRESSSTATUS.

LINEERR_INVALLINEHANDLE

The specified device handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is out of range.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable.

Comments None.

See Also Data Types: LINEADDRESSSTATUS

Fields: The following table indicates which fields of the LINEADDRESSSTATUS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetCallAddressID

Syntax void TSPI_lineGetCallAddressID(hdCall, lpdwAddressID)

This operation allows the TAPI DLL to retrieve the address ID for the indicated call.

Parameters HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call whose address ID is to be retrieved.

LPDWORD lpdwAddressID

Specifies a far pointer to a DWORD into which the Service Provider writes the call's address ID.

Return Value none

Call States Any

Comments This operation must be executed synchronously by the Service Provider, with presumed success. This operation may be called from within the context of the ASYNC_LINE_COMPLETION or LINEEVENT callbacks (i.e., from within an interrupt context). This function would typically be called at the start of the call life cycle.

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

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

See Also Functions: ASYNC_LINE_COMPLETION, LINEEVENT, TSPI_lineGetCallInfo

Data Structures: LINE_CALLINFO

3.1.7.0 TSPI_lineGetCallInfo

Syntax LONG TSPI_lineGetCallInfo(dwRequestID, hdCall, lpCallInfo)

This operation enables the TAPI DLL to obtain fixed information about the specified call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call whose call information is to be retrieved.

LPLINECALLINFO lpCallInfo

Specifies a far pointer to a variable sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call related information.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States hdCall any state

Comments A separate LINECALLINFO structure exists for every (inbound or outbound) call. The structure contains primarily fixed information about the call. An application would typically be interested in checking this information when it receives its handle for a call via the LINE_CALLSTATE message, or each time it receives notification via a LINE_CALLINFO message that parts of the call information structure have changed. These messages supply the handle for the call as a parameter.

See Also Messages: LINE_CALLINFO

Data Types: LINECALLINFO

Fields: The following table indicates which fields of the LINECALLINFO data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetCallStatus

Syntax LONG TSPI_lineGetCallStatus(dwRequestID, hdCall, lpCallStatus)

This operation returns the current status of the specified call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be queried for its status.

LPLINECALLSTATUS lpCallStatus

Specifies a far pointer to a variable sized data structure of type LINECALLSTATUS. Upon successful completion of the request, this structure is filled with call status information.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States hdCall any state

Comments TSPI_lineCallStatus 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 the TAPI DLL can invoke on the call while the call is in this state. An application would typically be interested in requesting this information when it receives notification about a call state change via the LINE_CALLSTATE message.

See Also Data Types: LINECALLSTATUS

Functions: TSPI_lineGetCallInfo

Fields: The following table indicates which fields of the LINECALLSTATUS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetDevCaps

Syntax LONG TSPI_lineGetDevCaps(dwRequestID, dwDeviceID, dwTSPIVersion, lpLineDevCaps)

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

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

DWORD dwDeviceID

Specifies the line device to be queried.

DWORD dwTSPIVersion

Specifies the negotiated TSPI version number. This value has already been negotiated for this device through the TSPI_lineNegotiateTSPIVersion function.

LPLINEDEVCAPS lpLineDevCaps

Specifies a far pointer to a variable sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information.

LINEERR_BADDEVICEID

The specified line device ID is out of range.

LINEERR_NODRIVER

The driver was not successfully installed.

LINEERR_INCOMPATIBLEVERSIONS

A TSPI or Extension version number was requested that was outside the range of supported versions for this device.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable.

Comments Line device ID numbering for a Service Provider is sequential from the value set by the function TSPI_lineSetDeviceIDBase.

The dwExtVersion field of lpLineDevCaps has already been filled in to indicate the version number of the Extension information requested. If it is zero, no Extension information is requested. If it is non-zero it holds a value that has already been negotiated for this device with the function TSPI_lineNegotiateExtVersion. The Service Provider should fill in Extension information according to the Extension version specified.

One of the fields in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address IDs used to reference individual addresses vary from zero to one less than the returned number. The capabilities of each address may be different. Use TSPI_lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address.

Comparison This function differs from the corresponding TAPI function in the following ways:

No application identifier is passed to the Service Provider

The SPI version has already been negotiated between the TAPI DLL and the Service Provider. The final result of the negotiation is passed as a parameter to this function. The Service Provider must preserve the value that is present in the dwTAPIVersion field of the LINEDEVCAPS structure.

The Extension version number has already been negotiated, with the dwExtVersion field containing the negotiated value. The Service Provider must preserve the value in this field and fill in the DevSpecific portion of the data structure according to that Extension version requested (regardless of any currently selected Extension version). The special version number 0 indicates that no DevSpecific data is requested and the Service Provider may avoid filling it in.

See Also Data Types: LINEDEVCAPS

Functions: TSPI_lineSetDeviceIDBase, TSPI_lineNegotiateExtVersion, TSPI_lineGetAddressCaps

Fields: The following table indicates which fields of the LINEDEVCAPS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

The following table indicates which fields of the LINETERMCAPS data structure(s) embedded in the varying part of the LINEDEVCAPS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetID

Syntax LONG TSPI_lineGetID(dwRequestID, hdLine, dwAddressID, hdCall, dwSelect, lpDeviceID, lpszDeviceClass)

This function returns a device ID for the specified device class associated with the selected line, address or call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to be queried.

DWORD dwAddressID

Specifies an address on the given open line device.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be queried.

DWORD dwSelect

Specifies the whether the device ID requested is associated with the line, address or a single call, of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE

Selects the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID are unused.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall is unused.

LINECALLSELECT_CALL

Selects the specified call. hdCall must be valid; hdLine and dwAddressID are both unused.

LPVARSTRING lpDeviceID

Specifies a far pointer to the memory location of type VARSTRING where the device ID is returned. Upon successful completion of the request, this location is filled with the device ID. The format of the returned information depends on the method used by the device class (API) for naming devices.

LPCSTR const lpszDeviceClass

Specifies a far pointer to a NULL-terminated ASCII string that specifies the device class of the device whose ID is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

LINEERR_INVALLINEHANDLE

The hdLine parameter is an invalid handle.

LINEERR_INVALADDRESSID

The specified dwAddressID parameter is invalid.

LINEERR_INVALCALLHANDLE

The hdCall parameter is an invalid handle.

LINEERR_INVALCALLSELECT

The specified dwCallSelect parameter is invalid.

LINEERR_NODEVICE

The line device has no associated device for the given device class.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable.

Comments This function can be used to retrieve a line device ID given a line handle. Although the TAPI DLL has sufficient information to determine the line device ID from a line handle, it may still call this operation in such a fashion on behalf of an application that has opened a line device using LINE_MAPPER. The Service Provider should support the "line" device class to allow applications to determin the real line device ID of an opened line.

This function can also be used to obtain the device ID of a phone device or media device (e.g., mci waveform, mci midi, wave, fax, etc.) associated with a call, address or line. This ID can then be used with the appropriate API (e.g., phone, mci, midi, wave, etc.) to select the corresponding media device associated with the specified call.

Note that the notion of Windows device class is different from that of media mode. For example, the interactive voice or stored voice media modes may be accessed using either the mci waveaudio or the low level wave device classes. A media modes describes a format of information on a call, a device class defines a Windows API used to manage that stream. Often, a single media stream may be accessed using multiple device classes, or a single device class (e.g., the Windows COMM API) may provide access to multiple media modes.

See Also Data Types: VARSTRING

Fields: The following table indicates which fields of the VARSTRING data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetLineDevStatus

Syntax LONG TSPI_lineGetLineDevStatus(dwRequestID, hdLine, lpLineDevStatus)

This operation enables the TAPI DLL to query the specified open line device for its current status.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to be queried.

LPLINEDEVSTATUS lpLineDevStatus

Specifies a far pointer to a variable sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, this structure is filled with the line's device status.

LINEERR_INVALLINEHANDLE

The specified line device handle is invalid.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unknown reasons.

Call States Not applicable.

Comments The TAPI DLL uses TSPI_lineGetLineDevStatus to query the line device for its current line status. This status information applies globally to all addresses on the line device. Use TSPI_lineGetAddressStatus to determine status information about a specific address on a line.

See Also Messages: LINE_LINEDEVSTATE

Data Types: LINEDEVSTATUS

Functions: TSPI_lineGetAddressStatus

Fields: The following table indicates which fields of the LINEDEVSTATUS data structure are filled in by the Service Provider and which fields are filled in by the TAPI DLL. The Service Provider must preserve (i.e., must not overwrite) the values filled in by the TAPI DLL.

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_lineGetProcTable

Syntax BOOL TSPI_lineGetProcTable(dwTSPIVersion, lpLineProcTable)

This function allows the TAPI DLL to retrieve a procedure table of pointers to all the line-related functions in the TSPI.

Parameters DWORD dwTSPIVersion

Specifies the TSPI version that defines the list of entry points, parameter profiles, and syntax of functions in the procedure table.

LPTSPI_LINE_PROCS lpLineProcTable

Specifies a far pointer to the procedure table that is to be filled in by the Service Provider with pointers to all the line-related functions.

Return Value Returns TRUE if successful, otherwise FALSE

Call States Not applicable.

Comments This function is typically invoked early in the initialization sequence to retrieve the line-related entry points through which the Service Provider is accessed. Entry points may be retrieved in this way for performance reasons; in some system environments this is much quicker than loading entry points by name. The Service Provider must still export all of its entry points by name to support the early functions (such at TSPI_lineGetProcTable itself) that must be invoked before the procedure table has been retrieved and the system environments in which entry points are always loaded by name.

A Service Provider is allowed to limit its support to a subset of the functions defined in the TSPI specification. However, it must fill in a valid procedure pointer for each of the functions in the procedure table. This can be the address of a "stub" function that simply returns a "not supported" result code for unsupported functions.

The TAPI DLL negotiates a TSPI version using TSPI_lineNegotiateTSPIVersion before calling this function. Since the device ID base has not been set this early in initialization, no device can be specified for the negotiation. The TAPI DLL uses the special dwDeviceID value INITIALIZE_NEGOTIATION to signify that it is negotiating an "overall" interface version for the purpose of calling functions such as TSPI_lineGetProcTable.

Comparison There is no corresponding function at the TAPI level. All entry points at the TAPI level are strictly accessed through standard library entry point export and linkage mechanisms.

See Also Functions: TSPI_lineNegotiateTSPIVersion

Constants: INITIALIZE_NEGOTIATION

3.1.7.0 TSPI_lineHold

Syntax LONG TSPI_lineHold(dwRequestID, hdCall)

This function places the specified call on hold.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be placed on hold.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The specified call is not in a valid state for the requested operation.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall connected

Comments The call on hold is temporarily disconnected allowing the TAPI DLL to use the line device for making or answering other calls. TSPI_lineHold performs a so-called "hard hold" of the specified call, as opposed to a "consultation call". A call on hard hold typically cannot be transferred or included in a conference call, whereas a consultation call can. Consultation calls are initiated using TSPI_lineSetupTransfer, TSPI_lineSetupConference, or TSPI_linePrepareAddToConference.

After a call has been successfully placed on hold, the call state will typically transition to onHold. A held call is retrieved via TSPI_lineUnhold. While a call is on hold, the TAPI DLL may receive LINE_CALLSTATE messages about state changes of the held call. For example, if held party hangs up, the call state may transition to disconnected.

See Also Functions: TSPI_lineUnhold

Messages: LINE_CALLSTATE

3.1.7.0 TSPI_lineMakeCall

Syntax LONG TSPI_lineMakeCall(dwRequestID, hdLine, htCall, lphdCall, lpszDestAddress, dwCountryCode, lpCallParams)

This function places a call on the specified line to the specified destination address, exchanging opaque handles for the new call between the TAPI DLL and Service Provider. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line on which the new call is to be originated.

HTAPICALL htCall

Specifies the TAPI DLL's opaque handle to the new call. The Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.

LPHDRVCALL lphdCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the call. The Service Provider must fill this location with its opaque handle for the call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

LPCSTR const lpszDestAddress

Specifies a far pointer to the destination address. This follows the standard dialable number format. This pointer may be specified as NULL for non-dialed addresses (i.e., a hot phone) or when all dialing will be performed using TSPI_lineDial. In the latter case, TSPI_lineMakeCall will allocate an available call appearance which would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities may allow an application to specify multiple addresses at once.

DWORD dwCountryCode

Specifies the country code of the called party. If a value of zero is specified, then a default will be used by the implementation.

LPLINECALLPARAMS const lpCallParams

Specifies a far pointer to a LINECALLPARAMS structure. This structure allows the TAPI DLL to specify how it wants the call to be set up. If NULL is specified, then a default 3.1kHz voice call is established, and an arbitrary origination address on the line is selected.

This structure allows the TAPI DLL to select such elements as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, dialing parameters, etc.

LINEERR_INVALLINEHANDLE

The specified line device handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is out of range.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_CALLUNAVAIL

All call appearances on the specified address are currently in use.

LINEERR_INVALCALLPARAMS

The specified call parameter structure is invalid.

LINEERR_ADDRESSBLOCKED

The specified address is blocked from being dialed on the specified call.

LINEERR_BILLINGREJECTED

The billing information specified as part of the destination address has been rejected.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Not applicable

Comments After dialing has completed, several LINE_CALLSTATE messages will typically be sent to the TAPI DLL to notify it about the progress of the call. No generally valid sequence of call state transitions is specified as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence may cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call may typically transition directly to connected state.

The TAPI DLL has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device allows the TAPI DLL to originate calls from any of these stations using TSPI_lineMakeCall.

The call parameters allow the TAPI DLL to make non voice calls or request special call setup options that are not available by default.

The TAPI DLL can partially dial using TSPI_lineMakeCall and continue dialing using TSPI_lineDial. To abandon a call attempt, use TSPI_lineDrop.

The Service Provider initially does media monitoring on the new call for at least the set of media modes that were monitored for on the line.

See Also Functions: TSPI_lineDial, TSPI_lineDrop

Messages: LINE_CALLSTATE

Data types: LINECALLPARAMS

3.1.7.0 TSPI_lineMonitorDigits

Syntax LONG TSPI_lineMonitorDigits(dwRequestID, hdCall, dwDigitModes)

This function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode(s) is detected a message is sent to the application indicating which digit has been detected.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call on which digits are to be detected.

DWORD dwDigitModes

Specifies the digit mode(s) that are to be monitored, of type LINEDIGITMODE. Values are:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

LINEDIGITMODE_DTMFEND

Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

A dwDigitModes with a value of zero cancels digit monitoring.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALDIGITS

The specified digits are not valid.

LINEERR_INVALDIGITMODE

The specified digit mode is invalid.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The operation is not available.

LINEERR_OPERATIONFAILED

The operation failed for unspecified reasons.

Call States hdCall Any state

Comments This function is considered successful if digit monitoring has been correctly initiated; not when digit monitoring has terminated. Digit monitoring will remain in effect until it is explicitly disabled by calling TSPI_lineMonitorDigits with dwDigitModes set to zero, or until the call transitions to idle.

Although this function can be invoked in any call state, digits will typically only be detected while the call is in the connected state.

Each time a digit is detected, a LINE_MONITORDIGITS message is sent to the TAPI DLL passing the detected digit as a parameter.

The TAPI DLL can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. It can use TSPI_lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

See Also Functions: TSPI_lineGetDevCaps, TSPI_lineGatherDigits, TSPI_lineSetMediaControl

Messages: LINE_MONITORDIGITS

Data Types: LINEDEVCAPS, LINEDIGITMODE

3.1.7.0 TSPI_lineMonitorMedia

Syntax LONG TSPI_lineMonitorMedia(dwRequestID, hdCall, dwMediaModes)

This function enables and disables the detection of media modes on the specified call. When a media mode is detected, a message is sent to the TAPI DLL.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call for which media monitoring is to be set.

DWORD dwMediaModes

Specifies the media modes to be monitored, of type LINEMEDIAMODE. Values are:

LINEMEDIAMODE_NONE

This is used as a NULL value for the data type.

LINEMEDIAMODE_INTERACTIVEVOICE

The TAPI DLL wants to handle calls of the interactive voice media type; i.e., it manages live voice calls.

LINEMEDIAMODE_AUTOMATEDVOICE

The TAPI DLL wants to handle calls in which there is voice data, but the voice is handled by an automated application. Most Service Providers will not be able to distinguish between automated and interactive voice. In such a case any request for voice or detection of voice should be treated as interactive voice.

LINEMEDIAMODE_DIGITALDATA

The TAPI DLL wants to handle calls of the digital data media type

LINEMEDIAMODE_G3FAX

The TAPI DLL wants to handle calls of the group 3 fax media type.

LINEMEDIAMODE_G4FAX

The TAPI DLL wants to handle calls of the group 4 fax media type.

LINEMEDIAMODE_DATAMODEM

The TAPI DLL wants to handle calls with the data modem media mode.

LINEMEDIAMODE_TELETEX

The TAPI DLL wants to handle calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The TAPI DLL wants to handle calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The TAPI DLL wants to handle calls with the telex media mode.

LINEMEDIAMODE_MIXED

The TAPI DLL wants to handle calls with the ISDN mixed media mode.

LINEMEDIAMODE_TDD

The TAPI DLL wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_ADSI

The TAPI DLL wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

A value of zero for the dwMediaModes parameter cancels all media mode detection.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALMEDIAMODE

The list of media types to be monitored contains invalid information.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation is failed for unspecified reasons.

Call States hdCall any state

Comments This function is considered successful if media mode monitoring has been correctly initiated; not when media mode monitoring has terminated. Media monitoring for a given media mode will remain in effect until it is explicitly disabled by calling TSPI_lineMonitorMedia with a dwMediaModes parameter with the media mode set to zero, or until the call transitions to idle. TSPI_lineMonitorMedia is primarily an event reporting mechanism. The media mode of a call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only the TAPI DLL or a client application can change a call's media mode.

Default media monitoring performed by the service provider for a new call appearance corresponds to the union of all media modes specified by TSPI_lineSetDefaultMediaDetection or TSPI_lineConditionalMediaDetection for the line. Shortly after a new call is established, the TAPI DLL typically calls this function to reduce the set of media modes detected and reported for this call to the union of all media modes desired by the call's client applications.

Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is certain call states. These states may be device specific. For example, in ISDN a message may indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering of the media stream. Since filtering of a call's media stream implies a computational overhead, the TAPI DLL typically uses this procedure to disable media monitoring when not required.

See Also Functions: TSPI_lineGetDevCaps, TSPI_lineSetMediaControl, TSPI_lineSetDefaultMediaDetection, TSPI_lineConditionalMediaDetection

Messages: LINE_MONITORMEDIA

Data Types: LINEDEVCAPS, LINEMEDIAMODE

3.1.7.0 TSPI_lineMonitorTones

Syntax LONG TSPI_lineMonitorTones(dwRequestID, hdCall, dwToneListID, lpToneList, dwNumEntries)

This function enables and disables the detection of inband tones on the call. When a specified tone is detected, a message is sent to the TAPI DLL.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call for which tone detection is to be done.

DWORD dwToneListID

Specifies the unique ID for this tone list. Several tone lists can be outstanding at once. The Service Provider replaces any old list having the same dwToneListID with the new tone list. If lpToneList is NULL, the tone list with dwToneListID is simply dropped. In any case, other tone lists with different dwToneListIDs are kept unchanged.

LPLINEMONITORTONE const lpToneList

Specifies a list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an app defined tag field that is used to identify individual tones in the list for the purpose of reporting a tone detection.

DWORD dwNumEntries

Specifies the number of entries in lpToneList.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALTONE

The specified tone structure does not describe a valid tone.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall any state

Comments This function is considered successful if tone monitoring has been correctly initiated; not when tone monitoring has terminated. Tone monitoring will remain in effect for a given tone list until that tone list is explicitly disabled by calling TSPI_lineMonitorTones with the same dwToneListID and another tone list (or a NULL tone list), or until the call transitions to idle.

Although this function can be invoked in any call state, tones can typically only be detected while the call is in the connected state. Tone detection typically requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected may vary over time. Also, an equivalent amount of resources may be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

The Service provider monitors for all tones in all tone lists concurrently. When a tone is detected, each matching tone from each tone list is reported separately. Each tone report includes both the tone list ID and the app-specific tag. Depending on the Service Provider, it may not be possible to discriminate very close tones, so that multiple matches may be reported even for tones whose descriptions are not strictly identical.

Note that TSPI_lineMonitorTones is also used to detect silence. Silence is specified as a tone with all zero frequencies.

Comparison The corresponding function at the TAPI interface does not include a dwToneListID parameter. The inclusion of this parameter at the TSPI interface allows the TAPI DLL to forward the union of all tone monitoring lists from all applications to the Service Provider, while still retaining the ability to filter and forward the tone detection events according to application. This gives Service Provider designers the maximum flexibility to determine the degree to which they can discriminate very close tones, since the TAPI DLL makes no assumptions about what tone descriptions are considered identical.

See Also Functions: TSPI_lineGetDevCaps, TSPI_lineSetMediaControl

Messages: LINE_MONITORTONE

Data Types: LINEDEVCAPS, LINEMONITORTONE

3.1.7.0 TSPI_lineNegotiateExtVersion

Syntax LONG TSPI_lineNegotiateTSPIVersion(dwDeviceID, dwTSPIVersion, dwLowVersion, dwHighVersion)

This function returns the highest Extension version number the Service Provider is willing to operate under for this device given the range of possible Extension versions.

Parameters DWORD dwDeviceID

Identifies the line device for which interface version negotiation is to be performed. The value INITIALIZE_NEGOTIATION may not be used for this function.

DWORD dwTSPIVersion

Specifies an interface version number that has already been negotiated for this device using TSPI_lineNegotiateTSPIVersion. This function operates according to the interface specification at this version level.

DWORD dwLowVersion

Specifies the lowest Extension version number under which the TAPI DLL or its client application is willing to operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.

DWORD dwHighVersion

Specifies the highest Extension version number under which the TAPI DLL or its client application is willing to operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.

Return Value The Service Provider returns the highest Extension version number, within the range requested by the caller, under which the Service Provider is willing to operate. If the requested range does not overlap the range supported by the Service Provider, the function returns zero.

Call States Not applicable.

Comments This function may be called before or after the device has been opened by the TAPI DLL. If the device is currently open and has an Extension version selected, the function should return that version number if it is within the requested range. If the selected version number is outside the requested range, the function returns 0.

Comparison There is no directly corresponding function at the TAPI level, at which both interface version negotiation and Extension version negotiation are done as overloaded uses of lineGetDevCaps.

See Also Functions: TSPI_lineGetProcTable, TSPI_lineNegotiateExtVersion

Constants: INITIALIZE_NEGOTIATION

3.1.7.0 TSPI_lineNegotiateTSPIVersion

Syntax LONG TSPI_lineNegotiateTSPIVersion(dwDeviceID, dwLowVersion, dwHighVersion)

This function returns the highest SPI version the Service Provider is willing to operate under for this device given the range of possible SPI versions.

Parameters DWORD dwDeviceID

Identifies the line device for which interface version negotiation is to be performed. In addition to device IDs within the range the Service Provider supports, this may be the value:

INITIALIZE_NEGOTIATION

This value is used to signify that an overall interface version is to be negotiated. Such an interface version is required for functions that can be called early in the initialization sequence, i.e., before the device ID range has been set.

DWORD dwLowVersion

Specifies the lowest TSPI version number under which the TAPI DLL is willing to operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.

DWORD dwHighVersion

Specifies the highest TSPI version number under which the TAPI DLL is willing to operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.

Return Value The Service Provider returns the highest interface version number, within the range requested by the caller, under which the Service Provider is willing to operate. If the requested range does not overlap the range supported by the Service Provider, it returns zero.

Call States Not applicable.

Comments The TAPI DLL typically calls this function early in the initialization sequence for each line device. In addition, it calls this with the value INITIALIZE_NEGOTIATION for dwDeviceID to negotiate an interface version for calling early initialization functions such as TSPI_lineGetProcTable.

Negotiation of an Extension version is done through the separate procedure TSPI_lineNegotiateExtVersion.

See Also Functions: TSPI_lineGetProcTable, TSPI_lineNegotiateExtVersion

Constants: INITIALIZE_NEGOTIATION

3.1.7.0 TSPI_lineOpen

Syntax BOOL TSPI_lineOpen(dwDeviceID, htLine, lphdLine, dwTSPIVersion, lineEventProc)

This function opens the line device whose device ID is given, returning the Service Provider's opaque handle for the device and retaining the TAPI DLL's opaque handle for the device for use in subsequent calls to the LINEEVENT procedure.

Parameters DWORD dwDeviceID

Identifies the line device to be opened. The value LINE_MAPPER for a device ID is not permitted.

HTAPILINE htLine

Specifies the TAPI DLL's opaque handle for the line device to be used in subsequent calls to the LINEEVENT callback procedure to identify the device.

LPHDRVLINE lphdLine

A far pointer to a HDRVLINE where the Service Provider fills in its opaque handle for the line device to be used by the TAPI DLL in subsequent calls to identify the device.

DWORD dwTSPIVersion

The TSPI version negotiated through TSPI_lineNegotiateTSPIVersion under which the Service Provider is willing to operate.

LINEEVENT lineEventProc

A far pointer to the LINEEVENT callback procedure supplied by the TAPI DLL that the Service Provider will call to report subsequent events on the line.

Return Value Returns TRUE if the procedure is successful, otherwise FALSE

Call States Not applicable.

Comments Opening a line entitles the TAPI DLL to make further requests on the line. The line becomes "active" in the sense that the TAPI DLL can initiate outbound calls and the Service Provider can report inbound calls. The Service Provider reserves whatever non-sharable resources are required to manage the line. For example, opening a line accessed through a comm port and modem should result in opening the comm port, making it no longer available for use by other applications.

If the function is successful, both the TAPI DLL and the Service Provider become committed to operating under the specified interface version number for this open device. Subsquent operations and events identified using the exchanged opaque line handles conform to that interface version. This commitment and the validity of the handles remain in effect until the TAPI DLL closes the line using the TSPI_lineClose operation or the Service Provider reports the LINE_CLOSE event. If the function is not successful, no such commitment is made and the handles are not valid.

Comparison This procedure does not correspond directly to any procedure at the TAPI level, at which the functions of enabling device-specific extensions, selecting line characteristics, and setting media mode detection are included in the functionality defined by lineOpen. At the TSPI level, these additional capabilities are separated out into TSPI_lineNegotiateExtVersion, TSPI_lineSetDefaultMediaDetection and TSPI_lineConditionalMediaDetection. This procedure simply starts the "life cycle" of subsequent operations.

In addition, the TAPI procedure allows for asynchronous execution while this one does not.

See Also Functions: TSPI_lineClose, TSPI_lineNegotiateTSPIVersion, LINEEVENT

Messages: LINE_CLOSE

3.1.7.0 TSPI_linePark

Syntax LONG TSPI_linePark(dwRequestID, hdCall, dwParkMode, lpszDirAddress, lpNonDirAddress)

This function parks the specified call according to the specified park mode.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be parked.

DWORD dwParkMode

Specifies the park mode with which the call is to be parked, of type LINEPARKMODE. Values are:

LINEPARKMODE_DIRECTED

The TAPI DLL specifies the address at which address the call is to be parked in lpszDirAddress.

LINEPARKMODE_NONDIRECTED

This operation reports to the TAPI DLL where the call has been parked in lpNonDirAddress.

LPCSTR const lpszDirAddress

Specifies a far pointer to NULL-terminated string that indicates the address where the call is to be parked when using directed park. The address in dialable number format. This parameter is ignored for non directed park.

LPVARSTRING lpNonDirAddress

Specifies a far pointer to structure of type VARSTRING. For non directed park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park.

LINEERR_INVALCALLHANDLE

The specified device handle is invalid.

LINEERR_INVALPARKMODE

The specified park mode is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_INVALADDRESS

The specified address is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall connected

Comments Under directed park, the TAPI DLL determines the address at which it wants to park the call. Under non directed park, the switch determines the address and provides this to the TAPI DLL. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle call state after it has been successfully parked.

Some switches may remind the user after a call has been parked for some long amount of time. The TAPI DLL will see an offering call with a call reason set to reminder.

See Also Functions: TSPI_lineUnpark

Data Types: LINEPARKMODE, VARSTRING

Field Name

TAPI DLL

Service Provider

3.1.7.0 TSPI_linePickup

Syntax LONG TSPI_linePickup(dwRequestID, hdLine, dwAddressID, htCall, lphdCall, lpszDestAddress, lpszGroupID)

This 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, then a group pickup is performed. If required by the device capabilities, lpszGroupID specifies the group ID to which the alerting station belongs.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line on which a call is to be picked up.

DWORD dwAddressID

Specifies the address on hdLine at which the pickup is to be originated.

HTAPICALL htCall

Specifies the TAPI DLL's opaque handle to the new call. The Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.

LPHDRVCALL lphdCall

LPCSTR const lpszDestAddress

Specifies a far pointer to a NULL terminated character buffer that contains the address whose call is to be picked up. The address is standard dialable address format.

LPCSTR const lpszGroupID

Specifies a far pointer to a NULL terminated character buffer containing the group ID to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALADDRESS

The specified address is not a valid number.

LINEERR_INVALGROUPID

The specified group ID is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States not applicable

Comments When a call has been picked up successfully the TAPI DLL is notified via the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It will list the reason for the call as pickup. This structure is available via TSPI_lineGetCallInfo.

See Also Functions: TSPI_lineGetCallInfo, TSPI_lineGetCallStatus

Messages: LINE_CALLSTATE

Structures: LINECALLINFO, LINECALLSTATUS

3.1.7.0 TSPI_linePrepareAddToConference

Syntax LONG TSPI_linePrepareAddToConference(dwRequestID, hConfCall, htAddCall, lphdAddCall, lpCallParams)

This function prepares an existing conference call for the addition of another party. It creates a new, temporary consultation call. The new consulatation call can be subsequently added to the conference call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdConfCall

Specifies the Service Provider's opaque handle to a conference call.

HTAPICALL htAddCall

Specifies the TAPI DLL's opaque handle to the new, temporary consultation call. The Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call.

LPHDRVCALL lphdAddCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the new, temporary consultation call. The Service Provider must fill this location with its opaque handle for the new call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

LPLINECALLPARAMS const lpCallParams

Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

LINEERR_INVALCONFCALLHANDLE

The specified call handle for the conference call is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLSTATE

The conference call is not in a valid state for the requested operation.

LINEERR_CALLUNAVAIL

All call appearances on the specified address are currently allocated.

LINEERR_CONFERENCEFULL

The maximum number of parties for a conference has been reached.

LINEERR_INVALCALLPARAMS

The specified call parameters are invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdConfCall connected

hdAddCall Not applicable

Comments A conference call handle can be obtained via TSPI_lineSetupConference or via TSPI_lineCompleteTransfer that is resolved as a three-way conference call. The function TSPI_linePrepareAddToConference typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call via TSPI_lineAddToConference.

The consultation call can be canceled using TSPI_lineDrop. It may also be possible for the TAPI DLL to swap between the consultation call and the held conference call via TSPI_lineSwapHold.

The Service Provider initially does media monitoring on the new call for at least the set of media modes that were monitored for on the line.

See Also Functions: TSPI_lineDial, TSPI_lineSwapHold, TSPI_lineSetupConference, TSPI_lineAddToConference, TSPI_lineRemoveFromConference

Messages: LINE_CALLSTATE

3.1.7.0 TSPI_lineRedirect

Syntax LONG TSPI_lineRedirect(dwRequestID, hdCall, lpszDestAddress, dwCountryCode)

This function redirects the specified offering call to the specified destination address.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be redirected.

LPCSTR const lpszDestAddress

Specifies a far pointer to the destination address. This follows the standard dialable number format.

DWORD dwCountryCode

Specifies the country code of the party the call is redirected to. If a value of zero is specified, then a default will be used by the implementation.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_INVALADDRESS

The specified character buffer for the destination address contains invalid characters or digits (i.e., syntax error); the call has not been redirected.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall offering

Comments Call redirection allows the TAPI DLL to deflect an offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the TAPI DLL; redirection can be done on a call by call basis by the TAPI DLL, for example driven by caller ID information. It differs from call transfer in that transferring a call requires the call first be answered.

After a call has been successfully redirected, the call will typically transition to idle.

Besides redirecting an incoming call, the TAPI DLL may have the option to accept the call using TSPI_lineAccept, reject the call via TSPI_lineDrop, or answer the call using TSPI_lineAnswer. The availability of these operations is dependent on device capabilities.

See Also Functions: TSPI_lineAccept, TSPI_lineDrop, TSPI_lineGetDevCaps

Messages: LINE_CALLSTATE

3.1.7.0 TSPI_lineRemoveFromConference

Syntax LONG TSPI_lineRemoveFromConference(dwRequestID, hdCall)

This function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be removed from the conference.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall conferenced

Comments This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party may be removed from a conference, and the removed call may be automatically dropped (becomes idle). Consult the line's device capabilities to determine the available effects of removing a call from a conference.

See Also Functions: TSPI_lineSetupConference, TSPI_lineAddToConference, TSPI_lineGetDevCaps

Messages: LINE_CALLSTATE

Data Types: LINEDEVCAPS

3.1.7.0 TSPI_lineSecureCall

Syntax LONG TSPI_lineSecureCall(dwRequestID, hdCall)

This function secures the call from any interruptions or interference that may affect the call's media stream.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be secured.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall any state

Comments A call can be secured to avoid interference. For example, in an analog environment, call waiting tones may destroy a fax or modem session on the original call. TSPI_lineSecureCall allows an existing call to be secured, TSPI_lineMakeCall provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

See Also Functions: TSPI_lineMakeCall

3.1.7.0 TSPI_lineSelectExtVersion

Syntax BOOL TSPI_lineSelectExtVersion(hdLine, dwExtVersion)

This function selects the indicated Extension version for the indicated line device. Subsequent requests operate according to that Extension version.

Parameters HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line for which an Extension version is to be selected.

DWORD dwExtVersion

Specifies the Extension version to be selected. This version number has been negotiated using TSPI_lineNegotiateExtVersion. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. Calling this function with a dwExtVersion of zero cancels the current selection.

Return Value If the function is successful, it returns TRUE, otherwise it returns FALSE.

Call States not applicable

Comments The Service selects the indicated Extension version. Although the indicated version number may have been successfully negotiated, a different Extension version may have been selected in the interim, in which case this function fails (returning FALSE).

Subsequent operations on the line after an Extension version has been selected behave according to that Extension version. Subsequent attempts to negotiate the Extension version report strictly the selected version or 0 (if the requested range does not include the selected version). Calling this procedure with the special Extension version 0 cancels the current selection. The device becomes once again capable of supporting its full range of Extension version numbers.

Comparison This function has no direct correspondence at the TAPI level, where selecting an Extension version is bundled with the other functions of lineOpen. TSPI_lineSelectExtVersion is typically called in two situations: (1) An application requested to open a line, the resulting change of Media Mode monitoring was successful, the application requested that a particular Extension version be used, and no Extension version was currently selected. (2) The last application using a particular Extension version closed the line, and the Extension version selection can be cancelled.

See Also Functions: TSPI_lineNegotiateExtVersion

3.1.7.0 TSPI_lineSendUserUserInfo

Syntax LONG TSPI_lineSendUserUserInfo(dwRequestID, hdCall, lpsUserUserInfo, dwSize)

This function send user-to-user information to the remote party on the specified call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call on which to send user-to-user information.

LPCSTR const lpsUserUserInfo

Specifies a far pointer to a string containing user-to-user information to be sent to the remote party. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize

Specifies the size in bytes of the user-to-user information in lpsUserUserInfo.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_INVALPOINTER

The specified pointer parameter is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall connected

Comments This function can be used to send user-to-user information at any time during a connected call. If the size of the specified information to be sent is larger than what may fit into a single network message (e.g., ISDN), then the service provider is responsible for breaking the information up into a sequence of chained network messages (using "more data").

User-to-user information can also be sent as part of call accept, call reject, call redirect, and when making calls. User-to-user information can also be received. The received information is available via the call's call information record. Whenever user-to-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter will notify the TAPI DLL that user-to-user information in the call information record has changed. If multiple network messages are chained, then the information is assembled by the service provider and a single message is sent to the TAPI DLL.

See Also Functions: TSPI_lineMakeCall, TSPI_lineAccept, TSPI_lineRedirect, TSPI_lineDrop, TSPI_lineGetCallInfo

Messages: LINE_CALLINFO

Data Types: LINECALLINFO

3.1.7.0 TSPI_lineSetAppSpecific

Syntax LONG TSPI_lineSetAppSpecific(dwRequestID, hdCall, dwAppSpecific)

This operation enables the TAPI DLL to set the application specific field of the specified call's call information record.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call whose application specific field is to be set.

DWORD dwAppSpecific

Specifies the new content of the dwAppSpecific field for the call's LINECALLINFO structure. This value is uninterpreted by the Service Provider.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall any state

Comments The app specific field in the LINECALLINFO data structure that exists for each call is uninterpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by TSPI_lineGetCallInfo. However, TSPI_lineSetAppSpecific must be used to set the field so that changes become visible to other apps. When this field is changed, the Service Provider sends a LINE_CALLINFO message with an indication that the AppSpecific field has changed.

See Also Functions: TSPI_lineGetCallInfo

Messages: LINE_CALLINFO

Data Types: LINECALLINFO

3.1.7.0 TSPI_lineSetCallParams

Syntax LONG TSPI_lineSetCallParams(dwRequestID, hdCall, dwBearerMode, dwMinRate, dwMaxRate, lpDialParams)

This function allows the TAPI DLL to change certain parameters for an existing call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call whose parameters are to be changed.

DWORD dwBearerMode

Specifies the new bearer mode for the call, of type LINEBEARERMODE. Values are:

LINEBEARERMODE_VOICE

This is a regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.

LINEBEARERMODE_SPEECH

This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.

LINEBEARERMODE_MULTIUSE

The multi-use mode defined by ISDN.

LINEBEARERMODE_DATA

The unrestricted data transfer on the call. The data rate is specified separately.

LINEBEARERMODE_ALTSPEECHDATA

The alternate transfer of speech or unrestricted data on the same call (ISDN).

LINEBEARERMODE_NONCALLSIGNALING

This corresponds to a non call-associated signaling connection from the app to the service provider or switch (treated as a "media stream" by the TAPI DLL).

DWORD dwMinRate

Specifies a lower bound for the call's new data rate. The TAPI DLL is willing to accept a new rate as low as this one.

DWORD dwMaxRate

Specifies an upper bound for the call's new data rate. This is the maximum data rate the TAPI DLL would like. Equal values for dwMinRate and dwMaxRate indicate that an exact data rate is required.

LPLINEDIALPARAMS lpDialParams

Specifies a far pointer to the new dial parameters for the call, of type LINEDIALPARAMS. If this parameter is NULL, it indicates that the call's current dialing parameters are to be used.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLPARAMS

The specified call parameter structure is invalid.

LINEERR_INVALBEARERMODE

The specified bearer mode is invalid.

LINEERR_INVALRATE

The specified bearer mode is invalid.

LINEERR_BEARERMODEUNAVAIL

The call's bearer mode cannot be changed to the specified bearer mode.

LINEERR_RATEUNAVAIL

The service provider does currently not have enough bandwidth available for the specified rate.

LINEERR_RESOURCEUNAVAIL

The service provider does not have enough resources available to complete the request.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Any state

Comments This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

See Also Functions: TSPI_lineMakeCall

Messages: LINECALLPARAMS

3.1.7.0 TSPI_lineSetCompletionCallback

Syntax void TSPI_lineSetCompletionCallback(dwTSPIVersion, cbCompletion)

This procedure sets the procedure pointer to be used for all asynchronous request completion callbacks for "line" requests to the service provider.

Parameters DWORD dwTSPIVersion

Specifies the overall interface version that has been negotiated using TSPI_lineNegotiateTSPIVersion.

ASYNC_LINE_COMPLETION cbCompletion

Specifies the far pointer to the procedure to be called to report completion of all line-related functions for all line devices supported by the Service Provider.

Return Value none

Call States Not applicable

Comments Since this procedure is called without an active device to identify the interface version, it includes an already-negotiated TSPI version number defining the interface version at which the Service Provider is expected to operate for this function. An "early" version negotiation such as this uses the dwDeviceID value INITIALIZE_NEGOTIATE to signify that an overall interface version number is being negotiated.

The operation is always synchronous, with presumed success.

Comparison This procedure has no direct corresondence at the TAPI level, where completion of asynchronous operations is reported by sending a message to a central callback function where all other messgas are reported.

See Also Functions: TSPI_lineNegotiateTSPIVersion

Constants: INITIALIZE_NEGOTIATE

3.1.7.0 TSPI_lineSetDefaultMediaDetection

Syntax LONG TSPI_lineSetDefaultMediaDetection(dwRequestID, hdLine, dwMediaModes)

This procedure tells the Service Provider the new set of Media Modes to detect for the indicated line (replacing any previous set). It also sets the initial set of Media Modes that should be monitored for on subsequent calls (inbound or outbound) on this line.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line to have media monitoring set.

DWORD dwMediaModes

Specifies the media mode(s) of interest to the TAPI DLL, of type LINEMEDIAMODE. Values are:

LINEMEDIAMODE_NONE

This is used as a NULL value for the data type. The TAPI DLL is not interested to be the target of any handoff or inbound calls.

LINEMEDIAMODE_UNKNOWN

The TAPI DLL wants to handle calls of unknown media type; i.e., unclassified calls.

LINEMEDIAMODE_INTERACTIVEVOICE

The TAPI DLL wants to handle calls of the interactive voice media type; i.e., it manages live voice calls.

LINEMEDIAMODE_AUTOMATEDVOICE

The TAPI DLL wants to handle calls in which there is voice data managed by an automated application. In cases where the Service Provider does not distinguish between automated or interactive voice, this should be treated the same as interactive voice.

LINEMEDIAMODE_DIGITALDATA

The TAPI DLL wants to handle calls of the digital data media type.

LINEMEDIAMODE_G3FAX

The TAPI DLL wants to handle calls of the group 3 fax media type.

LINEMEDIAMODE_G4FAX

The TAPI DLL wants to handle calls of the group 4 fax media type.

LINEMEDIAMODE_DATAMODEM

The TAPI DLL wants to handle calls with the data modem media mode.

LINEMEDIAMODE_TELETEX

The TAPI DLL wants to handle calls with the teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The TAPI DLL wants to handle calls with the videotex media mode.

LINEMEDIAMODE_TELEX

The TAPI DLL wants to handle calls with the telex media mode.

LINEMEDIAMODE_MIXED

The TAPI DLL wants to handle calls with the ISDN mixed media mode.

LINEMEDIAMODE_TDD

The TAPI DLL wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_ADSI

The TAPI DLL wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_NOMEM

Unable to allocate or lock memory.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_NODRIVER

The driver was not properly installed.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States Not applicable.

Comments The TAPI DLL typically calls this function to update the set of detected media modes for the line to the union of all modes selected by all outstanding lineOpens whenever a line is Opened or Closed at the TAPI level. A lineOpen attempt is rejected if media detection is rejected. A single call to this procedure is typically the result of a lineOpen that does not specify the device ID LINE_MAPPER. The Device ID LINE_MAPPER is never used at the TSPI level.

Comparison There is no directly corresponding function at the TAPI level. This procedure corresponds to the "request media modes" implied for the specific line by the lineOpen procedure when it is called with the a specific device ID (i.e., other than LINE_MAPPER).

See Also Functions: lineClose

Data Types: LINEMEDIAMODE, LINECALLPARAMS

3.1.7.0 TSPI_lineSetDeviceIDBase

Syntax void TSPI_lineSetDeviceIDBase(dwTSPIVersion, dwDeviceID)

This function tells the Service Provider what its lowest numbered line device ID should be.

Parameters DWORD dwTSPIVersion

Specifies the interface version under which the Service Provider and TAPI DLL operation for this function. This version number has already been negotiated using TSPI_lineNegotiateTSPIVersion.

DWORD dwDeviceID

Specifies the new base line device ID from which the Service Provider should number its line devices.

Return Value none

Call States Not applicable

Comments Under directed park, the application determines the address at which it wants to park the call. Under non directed park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The Service Provider numbers its available line devices contiguously starting at the number set by this function. For example, if the Service Provider supports 4 lines and this procedure is called with a base dwDeviceID of 5, the lines have device IDs 5 through 8 both when device IDs are used as "input" parameters (as in TSPI_lineGetDevCaps) and when device IDs are used as "output" parameters (as in a returned LINEADDRESSCAPS data structure). This procedure may be called again, in which case device ID numbering changes for all subsequent requests. The operation returns synchronously. The device IDs before this procedure is called start at 0. Since this procedure is called without an active device to identify the interface version, it includes an already-negotiated TSPI version number defining the interface version at which the Service Provider is expected to operate for this function.

Comparison This function has no correspondence at the TAPI level, where device IDs are a zero-based range spanning all Service Providers. This function is used to "divide up" the range of device IDs between different Service Providers.

The responsibility for "offsetting" device IDs resides with the Service Providers rather than with the TAPI DLL to allow Service Provider designers maximum flexibility in defining extensions. Since the Service Provider uses the same device IDs as the application level, device-specific extensions can pass device IDs back and forth to applications using consistent device ID numbering.

See Also none

3.1.7.0 TSPI_lineSetMediaControl

Syntax LONG TSPI_lineSetMediaControl(dwRequestID, hdLine, dwAddressID, hdCall, dwSelect, lpDigitList, dwDigitNumEntries, lpMediaList, dwMediaNumEntries, lpToneList, dwToneNumEntries, lpCallStateList, dwCallStateNumEntries)

This function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states. The new specified media controls replace all the ones that were in effect for this line, address, or call prior to this request.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to a line.

DWORD dwAddressID

Specifies an address on the given open line device.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to a call.

DWORD dwSelect

Specifies the whether media control is requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This field is of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE

Selects the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall is ignored.

LINECALLSELECT_CALL

Selects the specified call. hdCall must be valid; hdLine and dwAddressID are both ignored.

LPLINEMEDIACONTROLDIGIT const lpDigitList

Specifies a far pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit listed in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

DWORD dwDigitNumEntries

Specifies the number of entries in the lpDigitList.

LPLINEMEDIACONTROLMEDIA const lpMediaList

Specifies a far pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media type specific information (e.g., duration), and a media control field. If a media mode in the list is detected, then the corresponding media control action is performed on the call's media stream.

DWORD dwMediaNumEntries

Specifies the number of entries in lpMediaList.

LPLINEMEDIACONTROLTONE const lpToneList

Specifies a far pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media control field. If a tone in the list is detected, then the corresponding media control action is performed on the call's media stream.

DWORD dwToneNumEntries

Specifies the number of entries in lpToneList.

LPLINEMEDIACONTROLCALLSTATE const lpCallStateList

Specifies a far pointer to an array with entries are of type LINEMEDIACONTROLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action. Whenever the given call transitions into one of the call states in the list, the corresponding media control action is invoked. A media control value of LINEMEDIACONTROL_NONE should be specified to cancel the media control of a call state.

DWORD dwCallStateNumEntries

Specifies the number of entries in lpCallStateList.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSELECT

The specified select parameter is invalid.

LINEERR_INVALDIGITLIST

The specified digit list is invalid.

LINEERR_INVALMEDIALIST

The specified media list is invalid.

LINEERR_INVALTONELIST

The specified tone list is invalid.

LINEERR_INVALCALLSTATELIST

The specified call state list is invalid.

LINEERR_RESOURCEUNAVAIL

The service provider does not have enough resources available to complete the request.

LINEERR_OPERATIONUNAVAIL

The operation is not available.

LINEERR_OPERATIONFAILED

The operation failed for unspecified reasons.

Call States hdCall any state

Comments This function is considered successful if media control has been correctly initiated; not when any media control has taken effect. Media control in progress is changed or is canceled by calling this function again with either different parameters or NULLs.

Only a single media control request can be outstanding on a call across all applications that own the call. A request replaces any that may be outstanding.

Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made may vary over time. If service provider resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Whether or not media control is supported by the service provider is a device capability.

See Also Functions: TSPI_lineGetDevCaps

Data Types: LINECAPS, LINEDIGITMODE, LINEMEDIAMODE,
LINEMEDIACONTROLMODE, LINEMEDIACONTROLCALLSTATE,
LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA,
LINEMEDIACONTROLTONE

3.1.7.0 TSPI_lineSetMediaMode

Syntax LONG TSPI_lineSetMediaMode(dwRequestID, hdCall, dwMediaMode)

This function changes the call's media as stored in the call's LINECALLINFO structure.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call undergoing a change in media mode.

DWORD dwMediaMode

Specifies the new media mode(s) for the call, of type LINEMEDIAMODE. As long as the UNKNOWN media mode flag is set, multiple other media mode flags may be set as well. This is used to indentify a call's media mode as not fully determined, but narrowed down to one of just a small set of specified media modes. If the UNKNOWN flag is not set, then only a single media mode can be specified. Values are:

LINEMEDIAMODE_NONE

This is used as a NULL value for the data type. This value is used when the media stream is inaccessible but call control features are being used.

LINEMEDIAMODE_UNKNOWN

The anticipated media type is not fully classified.

leftoff

LINEMEDIAMODE_INTERACTIVEVOICE

The anticipated media type is interactive voice media mode; i.e., live conversations.

LINEMEDIAMODE_AUTOMATEDVOICE

LINEMEDIAMODE_DIGITALDATA

The anticipated media type is digital data calls.

LINEMEDIAMODE_G3FAX

The anticipated media type is group 3 fax media mode.

LINEMEDIAMODE_G4FAX

The anticipated media type is group 4 fax media mode.

LINEMEDIAMODE_DATAMODEM

The anticipated media type is data modem media mode.

LINEMEDIAMODE_TELETEX

The anticipated media type is teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The anticipated media type is videotex media mode.

LINEMEDIAMODE_TELEX

The anticipated media type is telex media mode.

LINEMEDIAMODE_MIXED

The anticipated media type is ISDN mixed media mode.

LINEMEDIAMODE_TDD

The anticipated media type is TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_ADSI

The anticipated media type is ADSI (Analog Display Services Interface) media mode.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALMEDIAMODE

The specified media mode parameter is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reasons.

Call States hdCall Any state

Comments Other than changing the call's media as stored in the call's LINECALLINFO structure, this procedure is simply "advisory" in the sense that it indicates an expected media change that is about to occur, rather than forcing a specific change to the call. Typical usage is to set a calls media mode to a specific known media mode, or to exclude possible media modes as long as the call's media mode is not fully known; i.e., the UNKNOWN media mode flag is set.

See Also Data Types: LINECALLINFO

Functions: TSPI_lineGetCallInfo

3.1.7.0 TSPI_lineSetStatusMessages

Syntax LONG TSPI_lineSetStatusMessages(dwRequestID, hdLine, dwLineStates, dwAddressStates)

This operation enables the TAPI DLL 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.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line device for which the new filter is to be set.

DWORD dwLineStates

Specifies a bit array that identifies for which line device status changes a message is to be sent to the TAPI DLL, of type LINEDEVSTATE. Values are:

LINEDEVSTATE_OTHER

An other device status item has changed.

LINEDEVSTATE_RINGING

The switch tells the line to alert the user.

LINEDEVSTATE_CONNECTED

The line was previously disconnected and is now connected to the Service Provider.

LINEDEVSTATE_DISCONNECTED

This line was previously connected and is now disconnected from the Service Provider.

LINEDEVSTATE_MSGWAITON

The message waiting indicator is turned on.

LINEDEVSTATE_MSGWAITOFF

The message waiting indicator is turned off.

LINEDEVSTATE_INSERVICE

The line is connected to the Service Provider. This happens when the Service Provider is first activated, or when the line wire is physically plugged in and in service at the switch while the Service Provider is active.

LINEDEVSTATE_OUTOFSERVICE

The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE

Maintenance is being performed on the line at the switch. The Service Provider cannot be used to operate on the line device.

LINEDEVSTATE_NUMCALLS

The number of calls on the line device has changed.

LINEDEVSTATE_TERMINALS

The terminal settings have changed.

LINEDEVSTATE_ROAMMODE

The roaming mode of the line device has changed.

LINEDEVSTATE_BATTERY

The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL

The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC

The line's device specific information has changed.

LINEDEVSTATE_REINIT

Items have changed in the configuration of line devices. To become aware of these changes (e.g., new line devices) the TAPI DLL should notify all its client applications to reinitialize their use of the API. A Service Provider should initiate such a sequence only in extreme cases that cannot be handled through the normal configuration-change notification mechanism described in the "Overview" chapter.

LINEDEVSTATE_LOCK

The locked status of the line device has changed.

DWORD dwAddressStates

Specifies a bit array that identifies for which address status changes a message is to be sent to the TAPI DLL, of type LINEADDRESSSTATE. Values are:

LINEADDRESSSTATE_OTHER

An other address status item than those listed below has changed.

LINEADDRESSSTATE_DEVSPECIFIC

The device specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO

The address has changed to idle; i.e., it is now in use by zero stations.

LINEADDRESSSTATE_INUSEONE

The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY

The monitored or bridged address has changed to being in use by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS

The number of calls on the address has changed. This is the result of either a new inbound call, or an outbound call on the address, a call changing its hold status, etc.

LINEADDRESSSTATE_FORWARD

The forwarding status of the address has changed including the number of rings for determining a no answer condition. The TAPI DLL should check the address status to determine details about the address' current forwarding status.

LINEADDRESSSTATE_TERMINALS

The terminal settings for the address have changed.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALPARAM

One or both of the states parameters is invalid.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Not applicable.

Comments The TAPI defines a number of messages that notify applications about events occurring on lines and addresses. The sets of all change messages that all applications are interested may be much smaller than the set of possible messages. This procedure allows the TAPI DLL to tell the Service Provider the reduced set of messages that should be delivered. The Service Provider must deliver at least this set. It is permitted to deliver more, but it is discouraged from doing so for performance reasons. By default, address and line status reporting is initially disabled for a line.

Comparison This function differs from the corresponding TAPI function as follows: (1) The set of messages requested is the union of all sets requested by applications at the TAPI level. (2) The message set is neither reduced nor augmented by ownership (since there is no concept of ownership at the TSPI level) (3) The set is "advisory" in the sense that the Service Provider is required to forward at least the indicated set of messages but is permitted to forward a larger set.

Device state changes regarding Open and Close are not reported, since at the TSPI level there is only one outstanding Open at a time.

See Also Messages: LINE_LINEDEVSTATE, LINE_ADDRESSSTATE

Data Types: LINEDEVSTATE, LINEADDRESSSTATE

3.1.7.0 TSPI_lineSetTerminal

Syntax LONG TSPI_lineSetTerminal(dwRequestID, hdLine, dwAddressID, hdCall, dwSelect, dwTerminalModes, dwTerminalID, bEnable)

This operation enables the TAPI DLL to specify to which terminal information related to the specified line, address or call is to be routed. This operation can be used while calls are in progress on the line, to allow an application to route these events to different devices as required.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to a line.

DWORD dwAddressID

Specifies an address on the given open line device.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to a call.

DWORD dwSelect

Specifies whether the terminal setting is requested for the line, the address or just the specified call. If line or address is specified, then events either apply to the line or address itself or serves as a default initial setting for all new calls on the line or address. This parameter is of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE

Selects the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall is ignored.

LINECALLSELECT_CALL

Selects the specified call. hdCall must be valid; hdLine and dwAddressID are both ignored.

DWORD dwTerminalModes

Specifies the class(es) of low level events to be routed to the given terminal.

LINETERMMODE_BUTTONS

The button presses from the terminal to the line.

LINETERMMODE_DISPLAY

The display events from the line to the terminal.

LINETERMMODE_LAMPS

The lamp lighting events from the line to the terminal.

LINETERMMODE_RINGER

The ring requests from the line to the terminal.

LINETERMMODE_HOOKSWITCH

The hookswitch events between the terminal and the line.

LINETERMMODE_MEDIAFROMTERM

This is the unidirectional media stream from the terminal to the line associated with a call on the line. This value is only allowed when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIATOTERM

This is the unidirectional media stream from the line to the terminal associated with a call on the line. This value is only allowed when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIR

This is the bidirectional media stream associated with a call on the line and the terminal. This is the only value allowed when routing of both unidirectional channels of a call's media stream cannot be controlled independently.

DWORD dwTerminalID

Specifies the device ID of the terminal device where the given events are to be routed. Terminal IDs are small integers in the range of 0 to dwNumTerminals -1, where dwNumTerminals, and the terminal modes each terminal is capable of handling, are returned by lineGetDevCaps. Note that these terminal IDs have no relation to other device IDs and are defined by the service provider via device capabilities.

BOOL bEnable

If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the dwTerminalID.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSELECT

The specified select parameter is invalid.

LINEERR_INVALTERMINALMODE

The specified terminal modes parameter is invalid.

LINEERR_INVALTERMINALID

The specified terminal mode parameter is invalid.

LINEERR_RESOURCEUNAVAIL

The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available for the given device.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Not applicable.

Comments The TAPI DLL can use this operation to route certain classes of low level line events to the specified terminal device, or to suppress the routing of these events altogether. For example, voice may be routed to a separate audio I/O device (headset), lamps and display events may be routed to the local phone device, and button events and ringer events may be suppressed altogether.

This operation can be called any time, even when a call is active on the given line device. This, for example, allows a user to switch from using the local phone set to another audio I/O device.

This function may be called multiple times to possibly route the same events to multiple terminals simultaneously. To reroute event to a different terminal, it is recommended that the app first disable routing to the existing terminal and next route the events to the new terminal.

Terminal ID assignments are made by the line's service provider. Device capabilities only indicate which terminal IDs the service provider has available. Service providers that don't support this type of event routing would indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS is zero).

See Also Data Types: LINETERMMODE, LINECALLSELECT

3.1.7.0 TSPI_lineSetupConference

Syntax LONG TSPI_lineSetupConference(dwRequestID, hdCall, hdLine, htConfCall, lphdConfCall, htAddCall, lphdAddCall, dwNumParties, lpCallParams)

This function sets up a conference call for the addition of the third party.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the initial call that identifies the first party of a conference call. In some environments, a call must exist in order to start a conference call. In other telephony environments, no call initially exists and hdCall is left NULL.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line device on which to originate the conference call if hdCall is NULL. The hdLine parameter is ignored if hdCall is non-NULL. The Service Provider reports which model it supports through the setupConfNull flag of the LINEADDRESSCAPS data structure.

HTAPICALL htConfCall

Specifies the TAPI DLL's opaque handle to the new conference call. The Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call.

LPHDRVCALL lphdConfCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the newly created conference call. The Service Provider must fill this location with its opaque handle for the new call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

HTAPICALL htAddCall

Specifies the TAPI DLL's opaque handle to a new call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The Service Provider must save the htAddCall and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new consultation call.

LPHDRVCALL lphdAddCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for a call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The Service Provider must fill this location with its opaque handle for the new consultation call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

DWORD dwNumParties

Specifies the expected number of parties in the conference call. The service provider is free to do with this number as it pleases; ignore it, use it a hint to allocate the right size conference bridge inside the switch, etc.

LPLINECALLPARAMS const lpCallParams

Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

LINEERR_INVALCALLHANDLE

The specified call handle for the conference call is invalid. This error may also indicate that the telephony environment requires an initial call to set up a conference but a NULL call handle was supplied.

LINEERR_INVALLINEHANDLE

The specified line handle for the line containing the conference call is invalid. This error may also indicate that the telephony environment requires an initial line to set up a conference but a non-NULL call handle was supplied instead.

LINEERR_INVALCALLSTATE

The call is not in a valid state for the requested operation.

LINEERR_CALLUNAVAIL

All call appearances on the specified address are currently allocated.

LINEERR_CONFERENCEFULL

The requested number of parties cannot be satisfied.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLPARAMS

The specified call parameters are invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall connected

hdConfCall Not applicable

hdAddCall Not applicable

Comments TSPI_lineSetupConference provides two ways for establishing a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hdCall parameter is a valid call handle that is initially added to the conference call by the TSPI_lineSetupConference request and hdLine is ignored. On switches where conference call setup does not start with an existing call, hdCall must be NULL and hdLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. The TAPI DLL can use TSPI_lineDial to dial the address of the other party.

The conference call will typically transition into the onHoldPendingConference state, the consultation call dialtone state and the initial call (if one) into the conferenced state.

A conference call can also be set up via a TSPI_lineCompleteTransfer that is resolved into a three-way conference.

The TAPI DLL may be able to toggle between the consultation call and the conference call by using TSPI_lineSwapHold.

See Also Functions: TSPI_lineDial, TSPI_lineSwapHold, TSPI_linePrepareAddToConference, TSPI_lineAddToConference, TSPI_lineRemoveFromConference

Messages: LINE_CALLSTATE

Data Structures: LINEADDRESSCAPS, LINEADDRESSCAPFLAGS

3.1.7.0 TSPI_lineSetupTransfer

Syntax LONG TSPI_lineSetupTransfer(dwRequestID, hdCall, htConsultCall, lphdConsultCall, lpCallParams)

This function initiates a transfer of the call specified by hdCall. It establishes a consultation call, lphdConsultCall, on which the party can be dialed that can become the destination of the transfer.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be transferred.

HTAPICALL htConsultCall

LPHDRVCALL lphdConsultCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the new consultation call. The Service Provider must fill this location with its opaque handle for the new consultation call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

When setting a call up for transfer, another call (a consultation call) is automatically allocated to enable the TAPI DLL to dial the address (using TSPI_lineDial) of the party to where the call is to be transferred. The originating party can carry on a conversation over this consultation call prior to completing the transfer.

This transfer procedure may not be valid for some line devices. Instead of calling this procedure, the TAPI DLL may need to unhold an existing held call (using TSPI_lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call may 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, via TSPI_lineMakeCall, to the destination of the transfer.

The transferHeld and transferMake flags in the LINEADDRESSCAPS data structure report what model the Service Provider uses.

LPLINECALLPARAMS const lpCallParams

Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call to be transferred is not in a valid state.

LINEERR_CALLUNAVAIL

All call appearances on the specified address are currently allocated.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLPARAMS

The specified call parameters are invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall connected, onHoldPendingTransfer, onHold

hdConsultCall Not applicable

Comments This operation sets up the transfer of the call specified by hdCall. The setup phase of a transfer establishes a consultation call that enables the application to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hdConsultCall) and can be manipulated independently of the original call (e.g., dropped, etc.).

When the consultation call has reached the dialtone call state, the application may proceed transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using TSPI_lineCompleteTransfer.

While the consultation call exists, the original call will typically transition to the onholdPendingTransfer state. The app may be able to toggle between the consultation call and the original call by using TSPI_lineSwapHold.

The app may also transfer calls in a single step, without having to deal with the intervening consultation call by using TSPI_lineBlindTransfer.

In telephony environments that follow the transferHeld or transferMake transfer models, this procedure returns LINEERR_OPERATIONUNAVAIL and does not allocate a consultation call handle.

See Also Functions: TSPI_lineDial, TSPI_lineCompleteTransfer, TSPI_lineBlindTransfer, TSPI_lineSwapHold

Messages: LINE_CALLSTATE

Data Structures: LINEADDRESSCAPS

3.1.7.0 TSPI_lineSwapHold

Syntax LONG TSPI_lineSwapHold(dwRequestID, hdActiveCall, hdConsultCall)

This function swaps the specified active call with the specified call on consultation hold.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdActiveCall

Specifies the Service Provider's opaque handle to the call to be swapped with the call on consultation hold.

HDRVCALL hdConsultCall

Specifies the handle to the consultation call.

LINEERR_INVALCALLHANDLE

One or both of the specified call handles are invalid.

LINEERR_INVALCALLSTATE

The call states of the calls are invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdConsultCall onHoldPendingTransfer, onHoldPendingConference, onHold
hdActiveCall connected

Comments Swapping the active call with the call on consultation hold allows the TAPI DLL to alternate or toggle between these two calls. One example where this is typical behavior is in call waiting.

See Also Functions: TSPI_lineSetupTransfer, TSPI_lineSetupConference

3.1.7.0 TSPI_lineUncompleteCall

Syntax LONG TSPI_lineUncompleteCall(dwRequestID, hdline, dwCompletionID)

This function is used to cancel the specified call competion request on the specified line.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line on which a call completion is to be cancelled.

DWORD dwCompletionID

Specifies the completion ID for the request that is to be canceled.

LINEERR_INVALLINEHANDLE

The specified line handle is invalid.

LINEERR_INVALCOMPLETIONID

The completion ID is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Not applicable.

Comments None.

See Also Functions: TSPI_lineCompleteCall

3.1.7.0 TSPI_lineUnhold

Syntax LONG TSPI_lineUnhold(dwRequestID, hdCall)

This function retrieves the specified held call.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVCALL hdCall

Specifies the Service Provider's opaque handle to the call to be retrieved.

LINEERR_INVALCALLHANDLE

The specified call handle is invalid.

LINEERR_INVALCALLSTATE

The call is not currently on hold.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States hdCall onHold

Comments This operation works only for calls on hard hold, i.e., call placed on hold using TSPI_lineHold.

See Also Functions: TSPI_lineHold

3.1.7.0 TSPI_lineUnpark

Syntax LONG TSPI_lineUnpark(dwRequestID, hdLine, dwAddressID, htCall, lphdCall, lpszDestAddress)

This function retrieves the call parked at the specified address and returns a call handle for it.

Parameters DRV_REQUESTID dwRequestID

Specifies the identifier of the asynchronous request. The Service Provider returns this value if the function completes asynchronously.

HDRVLINE hdLine

Specifies the Service Provider's opaque handle to the line on which a call is to be unparked.

DWORD dwAddressID

Specifies the address on hdLine at which the unpark is to be originated.

HTAPICALL htCall

Specifies the TAPI DLL's opaque handle to the new unparked call. The Service Provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.

LPHDRVCALL lphdCall

Specifies a far pointer to an opaque HDRVCALL representing the Service Provider's identifier for the new unparked call. The Service Provider must fill this location with its opaque handle for the call before this procedure returns, whether it decides to execute the request sychronously or asynchronously. This handle is invalid if the function results in an error (either synchronously or asynchronously).

LPCSTR const lpszDestAddress

Specifies a far pointer to a NULL terminated character buffer that contains the address where the call is parked. The address is in standard dialable address format.

LINEERR_INVALLINEHANDLE

The specified call handle is invalid.

LINEERR_INVALPOINTER

One or more of the specified pointer parameters are invalid.

LINEERR_INVALADDRESSID

The specified address ID is invalid.

LINEERR_INVALADDRESS

The specified address is invalid.

LINEERR_OPERATIONUNAVAIL

The specified operation is not available.

LINEERR_OPERATIONFAILED

The specified operation failed for unspecified reason.

Call States Not applicable

Comments None.

See Also Functions: TSPI_lineHold