Navigation :

Hangup

Introduction

A SIP call-control Lua script using LhoSipIncallLuaService or 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. It will return true and will not generate any warning.

The A-Leg will be torn down by sending either:

SIP INVITE Final Response
SIP BYE Request

If a B-Leg exists, it will be torn down by sending either:

SIP CANCEL Request
SIP BYE Request

The LhoSipIncallLuaService Hangup API

.hangup [Synchronous]

The hangup method takes the following arguments:

Attribute	Type	Description
`code`	Integer	The code to send in the A-Leg SIP INVITE Final Response or BYE Request `Reason` header. The code must be in the range `300-699`. (Default = `603` or other platform-configured default value).
`reason`	Table	This is a container for specifying the details for a `Reason` header. The header will be included in the A-Leg SIP INVITE Final Response or BYE Request, depending on which is used. (Default = do not include a `Reason` header).
`.protocol`	`SIP`/`Q.850`	The protocol value to include in the `Reason` header. (Default = `SIP`).
`.cause`	Integer	The cause parameter value to include in the `Reason` header. (Default = do not include a `cause` parameter in the header).
`.text`	String	The text parameter value to include in the `Reason` header. (Default = do not include a `text` parameter in the header).

The hangup method returns true.

This hangup method will terminate the in-progress A-Leg and any B-Legs. The mechanism used is:

BYE

When the SIP INVITE Request has been accepted with a 200 OK Final Response, a SIP BYE Request will be sent for A-Leg or B-Leg teardown.

For the A-Leg only, an RFC 3326 Reason header will be constructed and included in the BYE Request if:

the hangup method reason parameter is set
the hangup method reason parameter is not set, but the code parameter is set

In the first case, the Reason header protocol and parameter values will be as specified by the reason parameter.

In the second case, the Reason header protocol value will be SIP, the cause parameter value will be the hangup method code parameter value, and the text parameter value will be the SIP status message associated with the code value.

CANCEL

When the SIP INVITE Request was outbound and we have not yet received a Final Response, a SIP CANCEL Request will be sent for A-Leg or B-Leg teardown.

For the A-Leg only, an RFC 3326 Reason header will be constructed and included in the CANCEL Request in the same conditions as for a BYE Request, using the same header construction rules.

SIP Final Response

When the SIP INVITE Request was inbound and we have not yet sent a Final Response, a SIP INVITE Final Response will be sent for A-Leg teardown.

The Final Response code will be as specified by the hangup method code parameter value, or 603 by default.

An RFC 3326 Reason header will be constructed and included in the Final Response when the hangup method reason parameter is set. The protocol and parameter values will be as specified by the reason parameter.

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.
local GO_AWAY = 2003

local scc = ...

-- Play our announcement (using Internal RTP media server and default Language).
local result = incall_api.rtp_interaction ({ message_id = 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