lineSetupTransfer
The lineSetupTransfer
function initiates a transfer of the call specified by hCall. 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 lphConsultCall.
LONG lineSetupTransfer(
|
HCALL hCall, |
|
|
LPHCALL lphConsultCall, |
|
|
LPLINECALLPARAMS const lpCallParams |
|
|
); |
|
Parameters
hCall
The handle of
the call to be transferred. The application must be an owner of the call. The
call state of hCall must be connected.
lphConsultCall
A 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, another call
(a consultation call) is automatically allocated to enable the application to
dial the address (using 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. Call state of hConsultCall is 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 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, by lineMakeCall, to the destination of the transfer. Which forms
of transfer are available are specified in the call's address capabilities.
lpCallParams
A 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.
Return Values
Returns a
positive request ID if the function will be completed asynchronously, or a negative
error number if an error has occurred. The dwParam2 parameter of the
corresponding LINE_REPLY
message is zero if the function is successful or it is a negative error number
if an error has occurred. Possible return values are:
LINEERR_BEARERMODEUNAVAIL,
LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_NOMEM, LINEERR_INUSE,
LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE,
LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLPARAMS,
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_STRUCTURETOOSMALL,
LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIAMODE,
LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALPOINTER.
Remarks
The lineSetupTransfer
function 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 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 lineCompleteTransfer.
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 lineSwapHold. A consultation call can be
canceled by invoking lineDrop on it. After dropping a consultation call,
the original call will typically transition back to the connected state.
If the call state of the original call is onHoldPendingTransfer, the lineUnhold
function can be used to recover the call. In this case, the call state of the
consultation call is set to idle.
The
application may also transfer calls in a single step, without having to deal
with the intervening consultation call by using lineBlindTransfer.
See Also