Share via

TSPI_lineSetupTransfer (Compact 2013)

  • Article

3/26/2014

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

Syntax

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID dwRequestID, 
  HDRVCALL hdCall, 
  HTAPICALL htConsultCall, 
  LPHDRVCALL lphdConsultCall, 
  LPLINECALLPARAMS const lpCallParams 
);

Parameters

  • dwRequestID
    Identifier of the asynchronous request.
  • hdCall
    Handle to the call to be transferred. The call state of hdCall can be connected.
  • htConsultCall
    TAPI 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 consultation call.

  • lphdConsultCall
    Pointer to a HDRVCALL representing the service provider's identifier for the new consultation call. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCallis not applicable.

    When setting a call up for transfer, another call (a consultation call) is automatically allocated to enable the application (through TAPI) 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, TAPI 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 can exist on a different address than the call to be transferred. It may also be necessary to set up the consultation call as an entirely new call, using the TSPI_lineMakeCall function, to the destination of the transfer.

    The transferHeld and transferMake flags in the LINEADDRESSCAPS data structure report what model the service provider uses.

  • lpCallParams
    Pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired (the service provider uses defaults).

Return Value

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this method.

Value

Description

LINEERR_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_INVALBEARERMODE

The bearer mode is invalid.

LINEERR_INVALCALLSTATE

The call state is invalid.

LINEERR_INVALRATE

The rate is invalid.

LINEERR_CALLUNAVAIL

The call is unavailable.

LINEERR_INVALCALLPARAMS

The call parameters are invalid.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALLINESTATE

The line state is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALMEDIAMODE

The media mode is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INUSE

The line is in use.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_BEARERMODEUNAVAIL

The bearer mode is unavailable.

LINEERR_RATEUNAVAIL

The rate is unavailable.

LINEERR_INVALADDRESSMODE

The address mode is invalid.

LINEERR_USERUSERINFOTOOBIG

The user information is too big.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the call to be transferred is not in a valid state.

This operation sets up the transfer of the call specified by hdCall. The setup phase of a transfer establishes a consultation call 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 (for example, dropped) independently of the original call.

When the consultation call has reached the dial tone call state, TAPI can continue 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 the TSPI_lineCompleteTransfer function.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state.

The TSPI_lineUnhold function can recover calls that have the call state onHoldPendingTransfer. If this is done, any consultation call typically goes to the idle state.

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

A consultation call can be canceled by invoking the TSPI_lineDrop function on it. After dropping a consultation call, the original call typically transitions back to the connected state.

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

Requirements

Header

tspi.h

Library

CellTSP.dll

See Also

Reference

TSPI Line Device Functions
LINEEVENT
TSPI_lineBlindTransfer
TSPI_lineCompleteTransfer
TSPI_lineDial
TSPI_lineDrop
TSPI_lineSwapHold
TSPI_lineUnhold