TSPI_lineSetupTransfer (Windows CE 5.0)
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.
LONG TSPIAPI TSPI_lineSetupTransfer(DRV_REQUESTIDdwRequestID,HDRVCALLhdCall,HTAPICALLhtConsultCall,LPHDRVCALLlphdConsultCall,LPLINECALLPARAMSconstlpCallParams);
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 hdConsultCall is 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 Values
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 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
OS Versions: Windows CE 3.0 and later.
Header: Tapicomn.h.
Link Library: Coredll.lib.
See Also
LINEEVENT | TSPI_lineBlindTransfer | TSPI_lineCompleteTransfer | TSPI_lineDial | TSPI_lineDrop | TSPI_lineSwapHold | TSPI_lineUnhold
Send Feedback on this topic to the authors