Perform a retrievable transfer to a new outbound call.
This function is used to transfer a connected call channel to another destination. This function will allow the application to retain control over the call channel and retrieve it when the transfer is no longer required - for example, when the far end hangs up.
The argument other_call is the call channel instance used for the transfer’s outbound leg. This call channel must be in the IDLE state.
An originating address call_from may be supplied. Setting this parameter to an empty string will result in a default value being used.
The primary channel must be in ANSWERED state. If it is IDLE, this function will raise a Hangup exception; otherwise, if it is not ANSWERED it will raise an Error exception.
The argument ringback_tone is the ringback tone to play when the outbound call channel is in the RING_OUTGOING state. Valid options for ringback_tone are listed in the server’s ToneManager resource. If ringback_tone is None a default tone will be used. For the channel to play a tone it must have a tone player object. It is essential that a tone player is created on the channel before a transfer is attempted.
The argument seconds_timeout is the amount of time allowed for the transfer to be completed. If the timeout is None, no time limit will be imposed.
When successfully transferred in this manner, this call channel will be in the TRANSFERRED state.
If unsuccessful, the cause of the failure can be retrieved from transfer_cause() function.
After the transfer has completed successfully, this channel cannot be used to play or record audio (the audio path is no longer available, it has been transferred), it can be used only to hang up the call or to call either the retrieve_transferred_call function or the wait_for_transferred_call_retrieval function.
This function will block until confirmation has been received that the channel has been transferred, or that the transfer request has failed, or a timeout has expired.
This function will return the channel state.
Usage example:
state = channel.retrievable_transfer(other_call, 'sip:3301@127.0.0.1:5060;user=phone')
if state != channel.State.TRANSFERRED:
cause = channel.transfer_cause()
print("could not transfer the call, reason is {0}".format(cause))