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 as false.
• After using any of the Interaction methods return result.controlled as false.

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:

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"

-- Announcement ID.
GO_AWAY = 2003

local scc = ...

-- Play our announcement (using default Internal SRP 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