Navigation :

Proceeding

Introduction

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

This is done using the proceeding method, or the simpler ringing method.

The ringing method always sends a 180 Ringing Response. The proceeding method allows control of the Response code, but not the associated message text (which is determined automatically by the framework).

Provisional Response is only applicable for an inbound A-Leg INVITE Request, and can only be sent when:

a Final Response has not already been sent
the inbound INVITE Request did not contain a Require header, or did not require 100rel (i.e. reliable Provisional Response with PRACK Request)
a Require header in the inbound INVITE Request specified 100rel (i.e. reliable Provisional Response with PRACK Request), and the INVITE Request contained an SDP Offer

The service logic should examine the proceed_ok attribute supplied by the scc entry parameter and returned by the methods associated with proceeding, interaction, and termination to determine if proceeding or ringing can still be used.

These methods cannot be used to send SDP (Session Description Protocol) Offer or Answer content. Nor can they 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.)

Their primary use is to enable forcing a “flash” 180 Ringing (or other Provisional Response) prior to interaction, termination attempt, or decline.

The LhoSipIncallLuaService Proceeding API

.proceeding [Asynchronous]

The proceeding method allows explicit sending of a SIP INVITE Provisional Response.

The proceeding method takes the following arguments:

Attribute	Type	Description
`code`	Integer	[Required] The code to send in the SIP INVITE Provisional Response. The code must be in the range `101-199`.
`seconds`	Positive Integer	Requests a specific service logic wait timer extension. This allows the service logic more time to complete processing while in the proceeding state. (Default = do not refresh the service logic timer).
`extra_headers`	Table	Additional user headers to include in the SIP INVITE Provisional Response. The table keys are header names. The table values are tables of header values. (Default = do not add extra user headers).

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

Attribute	Type	Description
`.controlled`	Boolean	[Required] Is this call still controlled right now? This value being `true` indicates that (at least some) telephony API actions can be performed by service logic. Note that in some cases the available control actions may be limited.
`.proceed_ok`	Boolean	[Required] Can the service logic still use the `.proceeding` method? This value will be `true` when `.controlled` is `true`, we have not yet sent a Final Response, and an SDP Offer would not be required to proceed.
`.decline_ok`	Boolean	[Required] Can the service logic still use the `.decline` method? This value will be `true` when `.controlled` is `true` and we have not yet sent a Final Response.
`.reason`	`Proceeded` / `Abandoned`	[Required] The reason why the proceed attempt ended.

Note that the proceeding method is 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 Provisional Response (i.e. PRACK Request) is enabled, the SIP call will wait for the receipt of the PRACK Request 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_service"

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 [Asynchronous]

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_service"

local scc = ...

local result = incall_api.ringing (180)
if (not result.controlled) then return end

incall_api.rtp_interaction ({ message_id = 2005 })

return