☰
Navigation :

Decline

Introduction

An Incall LUA script may decline the incall attempt, i.e. request that a final SIP INVITE Response be sent with code in the range 300-699.

This is done using the decline method. A convenience redirect method is also provided for the common redirection case.

Here is the overall flow for this declined case:

SCC Message Flow (Incall, Declined)

The “Post-Call Notification” shown in this flow is given purely as an example of supplementary functionality, but is not at all intrinsic to the flow.

Note that the decline method can only be used before the final result is sent for the INVITE.

Any of the following service logic actions can potentially cause a final response to be sent on the A-Leg, meaning that the decline method is not longer applicable.

If the service logic has played an announcement, but not attempted to terminate a B-Leg, then it should examine the decline_ok attribute of the announcement method result value to determine if decline can still be used.

If not, the service logic should use hangup to expressly end the call.

The LhoSipIncallLuaService Decline API

.decline [Synchronous]

The decline method allows control of final SIP status code in the range 3xx-6xx for the A-Leg final SIP INVITE Response sent by us.

Note that Authentication codes 401 and 403 are handled internally by the LhoSipApp, and the service logic does not need to (and should not) use this method to perform authentication checks

The decline method takes the following arguments:

Attribute Type Description
code 300-699 SIP response code to return in the A-Leg final SIP Response.
(Default = 603)
reason Object This is a container for specifying extended information in the SIP response Reason header of the SIP final response or of the SIP BYE request, depending on which is used.
(Default = SIP response does not contain Reason header)
.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)
extra_headers Table Requests that custom extra headers be set on the SIP INVITE Final 300-699 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 Final 300-699 Response.)

The decline method returns true.

Note that the hangup method will pass the processing request off to the controlling LhoSipApp (using the SCC-DO-ALEG-DECLINE-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 (decline with 604 Does Not Exist Anywhere, with a prior 180 Ringing):

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

local scc = ...

incall_api.ringing ()
incall_api.decline (604, nil)

return

Example (returning a Q.850 Cause 16):

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

local scc = ...

incall_api.decline (487, { protocol = "Q.850", value = 16, text = 'Normal Call Teardown' })

return

.redirect [Synchronous]

The redirect method is a special-case convenience method which is identical to the decline case, in terms of message flow, but which has two specific differences:

Otherwise, all other comments and limitations relevant to decline also apply for redirect.

The redirect method takes the following arguments:

Attribute Type Description
contact_user (+)Hex String [Required] An alternate contact digits to specify in the Contact header.
This is only the digits part with optional leading +.

The redirect method returns true.

Note that the hangup method will pass the processing request off to the controlling LhoSipApp (using the SCC-DO-ALEG-DECLINE-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 (redirect to 00645559999):

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

local scc = ...

incall_api.redirect ("00645559999")

return