Navigation :

Proceeding

Introduction

An Incall LUA script may proceed the incall attempt, i.e. request that a provisional SIP INVITE Response be sent with code in the range 101-199.

This is done using the proceeding or the simpler-named ringing method.

This method can not be used to send a 100 Trying response. The underlying framework will send an automatic 100 Trying response at the start of the service logic processing.

This method should not be used to send a 183 Session Progress response, since that response requires SDP (Session Description Protocol) content which cannot be constructed via this method.

This method allows control of the Response code, but not the associated message text (which is determined automatically) by the framework.

This method is generally not needed, since:

Announcement setup is “fast” in general, and Ringing is not necessary.
Call redirection or decline is “fast” in general, and Ringing is not necessary.
The termination_attempt method sends 180 Ringing automatically if no proceeding code was requested prior.

Hence the only reasons for using the proceeding or ringing method are:

a. To force a “flash” 180 Ringing (or other proceeding response) prior to an invocation of decline. b. To force a 180 Ringing (or other proceeding response) prior to interaction. c. To replace the default 180 Ringing prior to termination_attempt with a different 1XX proceeding code.

The LhoSipIncallLuaService Proceeding API

.proceeding [Asynchronous]

The proceeding method allows explicit sending of a proceeding SIP status code in the range 101-199.

The proceeding method takes the following arguments:

Attribute	Type	Description
`code`	Integer	[Required] SIP response code to send in the range `101`-`199`.
`secs`	Integer	Requests a specific service logic wait timer. This allows the service logic more time to complete processing while in the proceeding state. (Default = Use the default configured service logic timer.)
`extra_headers`	Table	Requests that custom extra headers be set on the SIP INVITE Proceeding Response. Each value in this table must be a SCALAR value, or an ARRAY of SCALAR values. (Default = Do not add any service-logic header values to the SIP Proceeding Response.)

The proceeding method returns a LUA table with the following attributes.

Attribute	Type	Description
`.controlled`	Boolean	[Required] Is this call still controlled, i.e. can subsequent SIP actions be performed?
`.reason`	String	Reason for loss of A-Leg control. This field is present is present if and only if `.controlled` is false.
`.decline_ok`	Boolean	Can the service logic still use the `.proceeding` and `.decline` methods? This field is present is present if and only if `.controlled` is `true`. This field will be `true` if we have not yet sent a 2XX or 300-699 Response code.

Note that the proceeding method as asynchronous. It will pass the proceeding request off to the controlling LhoSipApp (using the SCC-DO-ALEG-PROCEEDING message) and then will wait for confirmation before returning back to Lua script control.

This is because in the case where the use of 100rel reliable 1XX (i.e. PRACK) is enabled, then the SIP call will wait for the receipt of the PRACK configuration before allowing processing to resume for this call.

Example (flash 181 “Call is Being Forwarded” Response Code prior to decline):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

local scc = ...

local result = incall_api.proceeding (181, nil, { "MyHeader" = "Custom Value" })

-- PRACK may fail, or caller may CANCEL.
if (result.decline_ok) then
    incall_api.decline (606)
end

return

.ringing [Synchronous]

The ringing method is a convenience method which is identical to proceeding however:

The code is always 180.

Otherwise, all other comments and limitations relevant to proceeding also apply for ringing.

The ringing method takes no arguments.

The ringing method returns the same table structure as proceeding.

Example (flash 180 Ringing prior to internal announcement):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall"

local scc = ...

local result = incall_api.proceeding (181)
if (not result.controlled) then return end

incall_api.play_announcement (nil, 2005)

return