See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function initiates a transfer of the call specified by the hCallparameter. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer. The application acquires owner privilege to the lphConsultCallparameter.
Syntax
LONG WINAPI lineSetupTransfer( HCALL hCall, LPHCALL lphConsultCall, LPLINECALLPARAMS const lpCallParams ); |
Parameters
- hCall
-
Handle of the call to be transferred. The application must be an owner of the call. The call state of hCallmust be connected.
- lphConsultCall
-
Pointer to an HCALL handle. This location is then loaded with a handle identifying the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated that enables the lineDialfunction to dial the address associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCallis not applicable.
This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and unhold an existing held call (using the lineUnholdfunction) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. Which forms of transfer are available are specified in the call's address capabilities.
- lpCallParams
-
Pointer to call parameters to be used when establishing the consultation call. This parameter is one or more of the LINECALLPARAMFLAGSconstants. This parameter can be set to NULL if no special call setup parameters are desired.
Return Value
Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2parameter of the corresponding LINE_REPLYmessage is zero if the function succeeds or it is a negative error number if an error occurs. The following table shows the return values for this function.
| Value | Description |
|---|---|
|
LINEERR_BEARERMODEUNAVAIL |
The bearer mode is unavailable. |
|
LINEERR_INVALRATE |
The rate is invalid. |
|
LINEERR_CALLUNAVAIL |
The call is unavailable. |
|
LINEERR_NOMEM |
Not enough memory is available. |
|
LINEERR_INUSE |
The line is in use. |
|
LINEERR_NOTOWNER |
The application is not an owner of this call. |
|
LINEERR_INVALADDRESSMODE |
The address mode is invalid. |
|
LINEERR_OPERATIONFAILED |
The operation failed. |
|
LINEERR_INVALBEARERMODE |
The bearer mode is invalid. |
|
LINEERR_OPERATIONUNAVAIL |
The operation is unavailable. |
|
LINEERR_INVALCALLHANDLE |
The handle to the call is invalid. |
|
LINEERR_RATEUNAVAIL |
The rate is unavailable. |
|
LINEERR_INVALCALLPARAMS |
The call parameters are invalid. |
|
LINEERR_RESOURCEUNAVAIL |
The resources are unavailable. |
|
LINEERR_INVALCALLSTATE |
The call state of hCallis something other than connected. |
|
LINEERR_STRUCTURETOOSMALL |
The structure is too small. |
|
LINEERR_INVALLINESTATE |
The line state is invalid. |
|
LINEERR_UNINITIALIZED |
A parameter is uninitialized. |
|
LINEERR_INVALMEDIAMODE |
The media mode is invalid. |
|
LINEERR_USERUSERINFOTOOBIG |
The user-user information is too big. |
|
LINEERR_INVALPOINTER |
The pointer is invalid. |
Remarks
The lineSetupTransferfunction sets up the transfer of the call specified by hCall. 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 ( hConsultCall) and can be dropped or otherwise manipulated independently of the original call.
When the consultation call has reached the dial tone call state, the application can 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 the lineCompleteTransferfunction.
While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state. The application may be able to toggle between the consultation call and the original call by using the lineSwapHoldfunction. A consultation call can be canceled by invoking lineDropon it. After dropping a consultation call, the original call typically transitions back to the connected state. If the call state of the original call is onHoldPendingTransfer, the lineUnholdfunction can be used to recover the call. In this case, the call state of the consultation call is set to idle.
The application can also transfer calls in a single step, without having to deal with the intervening consultation call, by using the lineBlindTransferfunction.
 Note: |
|---|
| This function is for TAPI version 2.0 and later. |
Requirements
| Header | tapi.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |