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 sends180 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 .
|
seconds
|
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
|
Proceeded / Abandoned
|
Indicates which scenario has occurred. The call proceeded, or the A-Leg was lost. |
.decline_ok
|
Boolean |
Can the service logic still use the .proceeding and .decline methods?This field can be true only when .controlled is also 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_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 always180
.
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.proceeding (181)
if (not result.controlled) then return end
incall_api.play_announcement (nil, 2005)
return