Hangup
Introduction
An Incall LUA script may hangup the SIP incall using the hangup
method, assuming
that the call is currently under out control.
The call is under our control when the inbound SIP processing script begins, but control is lost in the following situations.
- After using the Decline (or Redirect) methods.
- After using this Hangup method.
- After using Termination (Attempt) returns
result.controlled
asfalse
. - After using any of the Interaction methods return
result.controlled
asfalse
.
An Incall LUA script can hangup a call simply by calling return, i.e. by ending the script.
However there are circumstances where the script may wish to perform actions after hanging-up the call,
and in this case the hangup
method will ensure that the call is torn-down promptly.
If the call is already disconnected then the hangup
method has no effect.
The actual mechanism for teardown of the call will be whichever is applicable of:
- Final SIP Response to inbound SIP INVITE.
- Sending of SIP BYE.
The LhoSipIncallLuaService Hangup API
.hangup [Synchronous]
The hangup
method takes the following arguments:
Attribute | Type | Description |
---|---|---|
code
|
300-699
|
Provides user control of the SIP code for the A-Leg teardown message. This use of this code depends on the particular hangup scenario which is applicable at the time. This parameter does not apply to any B-Leg teardown. |
reason
|
Object |
Container for SIP response Reason header set for the A-Leg teardown message.This parameter does not apply to any B-Leg teardown. |
.protocol
|
SIP /Q.850
|
The protocol to which this reason belongs. (Default = SIP )
|
.value
|
Integer |
[Required] A numeric Reason value code.
|
.text
|
String |
A text Reason .(Default = Terminated )
|
The hangup
method returns true
.
This hangup method will terminate the in-progress A-Leg and any B-Legs. The mechanism used is:
BYE
In the case where the INVITE has been accepted with a 200 OK successful, non-provisional response, then a BYE will be sent for A-Leg or B-Leg teardown.
For the A-Leg only, if BYE is used, and the reason
parameter is set in this hangup method, then an
RFC 3326 Reason
header will be constructed and set in the A-Leg outgoing BYE Request.
For the A-Leg only, if BYE is used, and the reason
parameter is not set in the hangup method, but
the code
parameter is set in this hangup method, then a RFC 3326 Reason
header will be constructed
using the SIP
protocol. This will also include a SIP status message automatically determined by us.
CANCEL
In the case where the SIP INVITE Request was outbound, and we have not yet received a final Response, then a SIP CANCEL Request will be sent for A-Leg or B-Leg teardown.
For the A-Leg only, if either of the code
and reason
attributes are specified, then an RFC 3326
SIP protocol Reason
header will be added to the SIP CANCEL Request, using the same construction
rules as for the “BYE” mechanism.
SIP Final Response
In the case where the SIP INVITE Request was inbound, and we have not yet sent a final Response, then a final SIP INVITE Response will be sent for A-Leg or B-Leg teardown.
For the A-Leg only, if final SIP INVITE Response is used, and the reason
parameter is set in this hangup
method, then an RFC 3326 Reason
header will be constructed and set in the A-Leg outgoing final
SIP INVITE Response.
For the A-Leg only, if final SIP INVITE Response is used, then the final SIP INVITE Response code will
be the specified value. Otherwise, a default value of 603
will be used.
Note that the hangup
method will pass the processing request off to the controlling
LhoSipApp
(using the SCC-DO-ALEG-HANGUP-FINAL
message) and then will immediately (synchronously)
return back to Lua script control, without waiting to confirm the result of the SIP transaction state change.
Example:
local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"
-- Announcement ID.
GO_AWAY = 2003
local scc = ...
-- Play our announcement (using Internal RTP media server and default Language).
local result = incall_api.play_announcement (GO_AWAY)
-- The 487 will either be sent as a SIP INVITE Final Response or an RFC 3326 "Reason" header in BYE.
incall_api.hangup (487)
n2svcd.notice ("Calm Down Period")
n2svcd.wait (5.0)
return