☰
Navigation :

Hangup

Introduction

An SIP call-control LUA script using LhoSipIncallLuaService, or using LhoSipOutcallLuaAgent may end the controlled call using the hangup method. Hangup will also be applied to a controlled call when the script completes.

If the call is already disconnected then the hangup method has no effect, and it will return with true and will not generate any warning.

The A-Leg will be torn-down using either:

If a B-Leg exists, then it will be torn-down using one of:

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