lineCompleteTransfer
The lineCompleteTransfer
function completes the transfer of the specified call to the party connected in
the consultation call.
LONG lineCompleteTransfer(
|
HCALL hCall, |
|
|
HCALL hConsultCall, |
|
|
LPHCALL lphConfCall, |
|
|
DWORD dwTransferMode |
|
|
); |
|
Parameters
hCall
A handle to
the call to be transferred. The application must be an owner of this call. The
call state of hCall must be onHold, onHoldPendingTransfer.
hConsultCall
A handle to
the call that represents a connection with the destination of the transfer. The
application must be an owner of this call. The call state of hConsultCall
must be connected, ringback, busy, or proceeding.
lphConfCall
A pointer to
a memory location where an HCALL handle can be returned. If dwTransferMode
is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned
in lphConfCall and the application becomes the sole owner of the conference
call. Otherwise, this parameter is ignored by TAPI.
dwTransferMode
Specifies how
the initiated transfer request is to be resolved. This parameter uses the
following LINETRANSFERMODE_ constants:
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 application.
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_INVALCALLHANDLE,
LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL,
LINEERR_INVALCONSULTCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALTRANSFERMODE,
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED,
LINEERR_NOMEM.
Remarks
The
LINE_REPLY message sent in response to a call to the lineCompleteTransfer
function is based on the status of the call specified by the hCall
parameter.
This
operation completes the transfer of the original call, hCall, to the
party currently connected by hConsultCall. The consultation call will
typically have been dialed on the consultation call allocated as part of lineSetupTransfer, but it may be any call to
which the switch is capable of transferring hCall.
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 by hCall and hConsultCall
are connected to each other, and both hCall and hConsultCall are
typically cleared from the application's line and transition to the idle
state. Note that the application's call handle remains valid after the transfer
has completed. The application must deallocate its handle with lineDeallocateCall when it is no longer
interested in the transferred call.
When resolved
as a conference, all three parties enter into a conference call. Both existing
call handles remain valid but will transition to the conferenced state.
A conference call handle will be created and returned, and it will transition
to the connected state.
If lineGetConfRelatedCalls is called immediately after
lineCompleteTransfer with the result that the calls are conferenced, lineGetConfRelatedCalls
may not return a complete list of related calls. This is because TAPI waits to
receive a LINE_CALLSTATE message indicating that the call has entered
LINECALLSTATE_CONFERENCED before it considers the call to actually be part of
the conference. That is, it waits for the service provider to confirm the
conferenced state. Once the application has received the LINE_CALLSTATE
message, lineGetConfRelatedCalls returns complete information.
It may also
be possible to perform a blind transfer of a call using lineBlindTransfer.
See Also