Navigation :

SIP Incall Lua Service

Introduction

The LhoSipIncallLuaService is a service for initiating Lua scripts to control inbound SIP calls. The Lua logic runs within the LogicApp (see core n2svcd documentation).

The LhoSipIncallLuaService begins with a SCC-HANDLE-ALEG-INBOUND-INVITE from one or more instances of the LhoSipApp which is configured to receive inbound SIP INVITE Requests from an external client.

The LhoSipIncallLuaService communicates with the LhoSipApp using the SCC-… messages.

For initiating outbound SIP calls, an already running Lua script can use the LhoSipOutcallLuaAgent.

Configuring LhoSipIncallLuaService

The LhoSipIncallLuaService is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <parameters>
            ...
          </parameters>
          <config>
            <services>
              <service module="LhoSipApp::LhoSipIncallLuaService" libs="../../n2sip/apps/lho_sip/lib" script_dir="/var/n2sip/scripts">
                <triggers>
                  <trigger called_prefix="800" script_key="800_digit_menu"/>
                  <trigger called_prefix="811" script_key="811_rest"/>
                  <trigger called_prefix="900" script_key="900_mca"/>
                </triggers>
              </service>
            </services>
            <agents>
              ...
            </agents>
          </config>
        </application>
        ...
      </applications>
      ...
    </n2svcd>

Under normal installation, the following service parameters apply:

Parameter	Type	XML Type	Description
`module`	`LhoSipApp::LhoSipIncallLuaService`	Attribute	[Required] The module name containing the Lua Service code.
`libs`	`../../n2sip/apps/lho_sip/lib`	Attribute	Location of the `module` for LhoSipIncallLuaService.
`script_dir`	String	Attribute	[Required] The directory containing scripts used by this service.
`default_no_answer_secs`	Integer	Attribute	The default number of seconds to wait for No Answer on a B-Leg termination attempt, when the service logic does not explicitly specify a no-answer timeout value. (Default = `60` seconds).
`default_pa_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a non-`prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `120` seconds).
`default_pacui_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a `prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `300` seconds).
`wait_margin_secs`	`1` - `15`	Attribute	The number of seconds to add to the wait time for all SIP call control actions to account for round-trip latency. (Default = `5` seconds).
`triggers`	Array	Element	Array of `trigger` elements specifying Lua scripts to run for SIP Incalls.
`.trigger`	Object	Element	Provisions a trigger which guides Lua script selection.

See also the script-loading and refresh timing parameters for all file-scripted Lua Service Loaders described as part of the LogicApp documentation.

Script Selection (SIP Incall Request)

The Lua Script selected to execute for a SIP Incall is a function of the called party and/or calling party extracted from the INVITE Request.

The LhoSipApp will extract the userinfo part (the part preceding the @) from the Request URI address. Any insignificant visual separator characters will be removed. The remainder must consist exclusively of telephony digits (0-9a-f) with an optional leading +. This identifier will be supplied to the SIP Incall Lua Service as the called party.

The LhoSipApp will apply the same processing to obtain the calling party, except that the calling party will be extracted from either the P-Asserted-Identity or From header. The calling party will be extracted from the P-Asserted-Identity header if that header is available, parseable, and has a userinfo part; otherwise it will be extracted from the From header. Note that the From header may be anonymised to protect the privacy of the caller. In that case, a usable P-Asserted-Identity header must be present in the INVITE Request.

The SIP Incall Lua Service will iterate the configured trigger entries in the sequence in which they are configured and find the first trigger which matches the received called and/or calling parties (or a script which matches all called and/or calling parties).

Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.

Script Consume/Decline

A configured instance of this Service will consume the SCC-HANDLE-ALEG-INBOUND-INVITE message only when it finds a matching Trigger, or in the case where the message appears malformed.

If no matching Trigger entry is found, the Service will decline the message, allowing other configured Services to be used.

Script Trigger Rules

Each SIP Incall trigger rule defines the name of a script which is ready to handle an incall for some/all called and/or calling party addresses.

Addresses may include non-digit characters, in which case the matching is case-insensitive.

Each trigger Object in the config.triggers Array is configured as follows.

Attribute	Type	Description
`from_otg` / `otg`	String	This trigger applies for only Incalls with this exact `otg` (Outgoing Trunk Group) tag on the SIP `From` header URI. For example, a SIP INVITE Request `From` header `<sip:12456@Test-SS;otg=NP>;tag=Sqepd3Ad9` would match `otg` = `NP`. (Default = trigger applies to all SIP Incalls).
`to_dtg` / `dtg`	String	This trigger applies for only Incalls with this exact `dtg` (Destination Trunk Group) tag on the SIP `To` header URI. (Default = trigger applies to all SIP Incalls).
`called`	String	This trigger applies for only Incalls to this exact called party. (Default = trigger applies to all SIP Incalls).
`called_prefix`	String	This trigger applies for only Incalls to called parties starting with this prefix. (Default = trigger applies to all SIP Incalls).
`calling`	String	This trigger applies for only Incalls from this exact calling party. (Default = trigger applies to all SIP Incalls).
`calling_prefix`	String	This trigger applies for only Incalls from calling parties starting with this prefix. (Default = trigger applies to all SIP Incalls).
`script_key`	String	[Required] The key of the Lua script to load and run. This is the file name excluding the ".lua"/".lc" suffix. The script should reside in the configured `script_dir` directory. Note that derived subclasses such as `AcdSipApp::AcdSipLuaService` may allow `script_key` to be undefined here, and will instead perform a dynamic database lookup to determine the script key.

Script Entry Parameters (SIP Incall Request)

The Lua script defines the service processing steps, such as the following:

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

local scc = ...

-- No Thanks.
incall_api.decline (607)

return

The service script will be executed with a single scc entry parameter:

Field	Type	Description
`scc`	Table	[Required] The SCC control parameters for the message. This is a pass-through of the `scc` attribute of the `SCC-HANDLE-ALEG-INBOUND-INVITE` message details.
`.request_uri`	Table	[Required] The decoded Lua table representation of the received SIP INVITE Request URI.
`.string`	String	[Required] The complete original Request URI.
`.display_name`	String	The `display-name` part of the Request URI, if present.
`.parameters`	Table	A map of top-level parameter values (not the Address parameters). Parameters without a value (e.g. `;urgent`) will be present with a value of `UNDEF`.
`.address`	Table	[Required] Container for the Address attributes.
`.uri`	String	[Required] The complete Address URI including parameters, but not including any `< >`.
`.protocol`	String	[Required] The Address protocol - `sip` or `tel`.
`.user`	String	[Required] The `userinfo` part (the part preceding the `@`) of the Address.
`.host`	String	[Required] The `host` part of the Address.
`.port`	Integer	The `port` part of the address, if explicitly present.
`.parameters`	Table	The Address parameters (not the top-level parameters). This will include the `transport` parameter (if explicit), and could include `otg` or other site-specific parameters. Parameters without a value (e.g. `;exdirectory`) will be present with a value of `UNDEF`.
`.from`	Table	[Required] The decoded Lua table representation of the `From` header from the received SIP INVITE Request. The table structure is identical to the structure described for the `.request_uri` value.
`.to`	Table	[Required] The decoded Lua table representation of the `To` header from the received SIP INVITE Request. The table structure is identical to the structure described for the `.request_uri` value.
`.call_id`	String	[Required] The `Call-ID` header value from the received SIP INVITE Request.
`.privacy`	Table	This value is present only when one or more `Privacy` headers are present in the received SIP INVITE Request. This table will have entries with keys matching each of the Privacy flags which are present in the headers, each with the value `1`. For example if a `Privacy` header has value `user;id` then this table will be `{ user = 1, id = 1 }`. (Default = not present, the header was not present in the Request).
`.p_preferred_identities`	Table	Table of `P-Preferred-Identity` header values from the received SIP INVITE Request. This value is present only when one or more `P-Preferred-Identity` headers are present in the Request. (Default = not present, the header was not present in the Request).
`.p_asserted_identities`	Table	Table of `P-Asserted-Identity` header values from the received SIP INVITE Request. This value is present only when one or more `P-Asserted-Identity` headers are present in the Request. (Default = not present, the header was not present in the Request).
`.p_charging_vector`	String	The `P-Charging-Vector` header value from the received SIP INVITE Request. This value is present only when a `P-Charging-Vector` header is present in the Request. (Default = not present, the header was not present in the Request).
`.extra_headers`	Table	A table of extra headers "of interest" from the received SIP INVITE Request. These are only headers specifically configured in the `<invite_headers>` configuration block. The table keys are header names. Header names are upper/lower case as defined in the `name` attribute of the `<invite_header>` configuration, even though the matching for header names in the Request is performed using case-insensitive matching. The table values are non-empty tables of raw header values parsed for the corresponding header name. (Default = not present, no headers of interest were matched in the Request).
`.calling_party`	(+)Hex String	[Required] Calling Party. This is the `userinfo` part of the `P-Asserted-Identity` or `From` header Address. It is guaranteed to contain only `0-9A-F` digits.
`.normalised_calling_party`	(+)Hex String	[Required] Normalised Calling Party. This is the `.calling_party` after any configured 'calling_party' normalisation rules have been applied. It is guaranteed to contain only `0-9A-F` digits.
`.is_calling_restricted`	`0` / `1`	[Required] Is presentation of the Calling Party restricted? This value will be `1` if: there are no Privacy headers in the received SIP INVITE Request, or the `none` flag is not present, and the `userinfo` part of the `From` header Address is anonymous
`.presented_calling_party`	(+)Hex String	This is the `userinfo` part of the `From` header Address. It is guaranteed to contain only `0-9A-F` digits. This value is present only when: a parseable `P-Asserted-Identity` header is received, and the `userinfo` part of the `From` header Address is not anonymous, and after normalisation, the `userinfo` part of the `From` header Address differs from `.normalised_calling_party` (Default = not present, the described value pre-conditions are not met).
`.normalised_presented_calling_party`	(+)Hex String	This is the `.presented_calling_party` after any configured 'calling_party' normalisation rules have been applied. It is guaranteed to contain only `0-9A-F` digits. (Default = not present, there is no `.presented_calling_party`).
`.called_party`	(+)Hex String	[Required] Called Party. This is the `userinfo` part of the Request URI Address. It is guaranteed to contain only `0-9A-F` digits.
`.normalised_called_party`	(+)Hex String	[Required] Normalised Called Party. This is the `.called_party` after any configured 'called_party' normalisation rules have been applied. It is guaranteed to contain only `0-9A-F` digits.
`.original_called_party`	(+)Hex String	This is the `userinfo` part of the `To` header address. It is guaranteed to contain only `0-9A-F` digits. This value is present only when, after normalisation, the `userinfo` part of the `To` header Address differs from `.normalised_called_party`. (Default = not present, the described value pre-conditions are not met).
`.normalised_original_called_party`	(+)Hex String	This is the `.original_called_party` after any configured 'called_party' normalisation rules have been applied. It is guaranteed to contain only `0-9A-F` digits. (Default = not present, there is no `.original_called_party`).
`.pending_tn`	(+)Hex String	[Required] Pending termination number digits. The normalised pending termination number inferred from the SIP INVITE Request. It is guaranteed to contain only `0-9A-F` digits.
`.proceed_ok`	`0` / `1`	[Required] Can the service logic still use the `.proceeding` method? This value will be `1` if an SDP Offer would not be required to proceed.

Script Return Parameters (SIP Incall Response)

The return value from the Lua script should always be nil. Returning any other value will generate a warning to the syslog.

The LhoSipIncallLuaService API

A script processing SCC incalls must use the SIP SIP Incall API.

    local incall_api = require "n2.n2svcd.sip_incall_service"

The following functionality is available for a controlled call.