Reject up a call.
This function causes a currently connected call to be released, or an incoming call to be rejected.
Default behaviour is for the REJECTED clearing cause to be used. The other valid options are:
- BUSY
- NOANSWER
- UNOBTAINABLE
- CHANGED
- OUTOFORDER
- BARRED
- REJECTED
- NOCHANNELS
- CONGESTION
A raw_cause clearing cause, in the form of a string, may be supplied. This gives the opportunity to send a message that is specific to the underlying call control protocol, e.g., SIP. This will override cause.
See the relevant SIP documentation for a list of clearing causes and their meanings.
This function will block until the call is actually cleared and the call state has returned to IDLE. This function will wait 60 seconds for the call state to return to IDLE.
Note that an inbound call might take quite a while to clear, as it is only actually fully released when the caller hangs up (or the network times out waiting for him to do so). Accordingly, if this function times out, the call channel will still not be available for another call until after the call state has returned to IDLE. The application can wait for this by calling the wait_for_idle function.
Please note that SIP redirection is not supported, so raw causes in the 300 range cannot be used. The call reject will fail with channel.State.ERROR if a raw cause is supplied which is not supported. And the user should send a different reject message.
This function will return the current call state.
Usage examples:
# reject the call with BUSY
state = channel.reject(cause=channel.Cause.BUSY)
if state != channel.State.IDLE:
# wait for channel to go to idle
channel.wait_for_idle()
# reject the call fails
state = channel.reject(raw_cause=301)
if state != channel.State.IDLE:
if state == channel.State.ERROR:
channel.reject()
# wait for channel to go to idle
channel.wait_for_idle()