Diameter Lua Agent

Introduction

The DiameterLuaAgent is an asynchronous helper for Lua scripts running within the LogicApp. It is used for sending out Diameter client requests.

The DiameterLuaAgent communicates with one or more instances of the DiameterApp which can be used to communicate with one or more external Diameter servers.

The DiameterLuaAgent communicates with the DiameterApp using the DIAMETER-C-… messages.

Diameter Agent API methods are accessed via the “n2.n2svcd.diameter_agent” module:

local diameter_api = require "n2.n2svcd.diameter_agent"

Configuring DiameterLuaAgent

The DiameterLuaAgent 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>
            ...
            <parameter name="default_diameter_app_name" value="DIAMETER-CLIENT"/>
            <parameter name="diameter_app_name_sms" value="DIAMETER-CLIENT-SMS"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="DiameterApp::DiameterLuaAgent" libs="../apps/diameter/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

Parameter Name Type XML Type Description
module DiameterApp:: DiameterLuaAgent Attribute [Required] The module name containing the Lua Agent code.
libs ../apps/diameter/lib Attribute Location of the module for DiameterLuaAgent.

In addition, the DiameterLuaAgent must be configured with the name of the DiameterApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

Parameter Name Type XML Type Description
parameters Array Element Array of name = value Parameters for this Application instance.
.default_diameter_app_name String Attribute Default name for the DiameterApp with which DiameterLuaAgent will communicate.
.diameter_app_name_<route> String Attribute Use this format when DiameterLuaAgent will communicate with more than one DiameterApp.

The DiameterLuaAgent API

All methods may raise a Lua Error in the case of exception, including:

.request_response [Asynchronous]

The request_response method sends a Diameter request, and returns the response. The following parameters are accepted.

Parameter Type Description
route String Optional Diameter route to use to submit the message. If undefined the default route will be used.
(Default = undef)
command String or Integer The String command name or Integer command code of the command request to send.
avps Array of Object Array of AVP descriptors each with the following fields.
[].bytes String Optional raw bytes representing the entire AVP including headers and padding.
If you supply this, then it is used without further checking, and all other attributes are ignored.
[].name String The name of the Diameter AVP, e.g. Rating-Group.
This must be the name of a supported AVP within N2::DIAMETER::Codec or DiameterApp custom AVPs.
If your AVP is not supported, you may instead specify [].code.
[].code Integer The code of the Diameter AVP, if not specifying by [].name.
[].vendor_id Integer The vendor ID. This field is optional and can be specified both when selecting the AVP by [].name (to distinguish between AVPs which have the same name but which are specified by different vendors) or when selecting the AVP by [].code in order to specify the intended vendor ID.
[].type String One of None, OctetString, UTF8String, DiamIdent, Integer32, Integer64, Unsigned32, Enumerated, Time, Unsigned64, Address, Grouped.
This is used only when specifying an AVP by [].code.
For named AVPs the type is pre-defined.
[].mandatory 0/1 Override the default mandatory AVP flag.
This is used only when specifying an AVP by [].code.
For named AVPs the mandatory flag is pre-defined.
[].encryption 0/1 Override the default encryption AVP flag.
This is used only when specifying an AVP by [].code.
For named AVPs the encryption flag is pre-defined.
[].value Various The value for this AVP.
For AVPs of type Grouped this will be an ARRAY of AVPs.
For all other AVPs this is a SCALAR of the appropriate type.
auto_session_id 0/1 Flag to indicate if the Session-Id AVP should be automatically assigned.
(Default = 0)

The request_response method returns a Diameter response object with the following fields.

Field Type Description
command String The String command name if known.
code Integer The Integer command code of the received response.
session_id String The String session ID associated with the current Diameter context if it was assigned by `auto_session_id` in the inbound request.
avps Array of Object Array of AVP descriptors each with the fields described as for a request.

Example (Diameter Client Request):

local n2svcd = require "n2.n2svcd"
local diameter_api = require "n2.n2svcd.diameter_agent"

local soap_args = ...

local result = diameter_api.request_response ('sms', 'Credit-Control-Request', {
    { name = "Service-Context-Id", value = "sms@huawei.com" },
    { name = "CC-Request-Type", value = 1 },
    { name = "CC-Request-Number", value = 1 },
    { name = "Rating-Group", value = 900 },
    { name = "Requested-Action", value = 0 },
    { name = "Requested-Service-Unit",
        value = { { name = "CC-Service-Specific-Units", value = 1 } },
        vendor_specific = 0
    },
    { name = "Service-Identifier", value = 200 },
    { name = "Subscription-Id",
        value = {
            { name = "Subscription-Id-Data", value = "64220635462" },
            { name = "Subscription-Id-Type", value = 0 }
        }
    },
    { name = "Custom-1", value = 789 }
}, true)

soap_response = {}
soap_response['status'] = 'ok'

return soap_response

The above example shows a LogicApp script invoked by a SoapLuaService.

Note that the decoded .avps array will contain all fields, i.e. the [].name and [].code and [].type and [].mandatory, etc. will all be present.

The only exception will be when decoding AVPs which are not part of the core fields defined within N2::DIAMETER::Codec and are not defined as custom AVPs in the configuration for DiameterApp. In these cases, the [].name and [].type AVP attributes will not be present, and the [].value will be the raw undecoded bytes of the AVP value without any interpretation.

.get_first_instance_of_avp [Synchronous]

The get_first_instance_of_avp method searches an array of AVPs, returning the first AVP with name matching a specified name. The following parameters are accepted.

Parameter Type Description
avps Array of Object Array of AVP descriptors each with the fields described for the result.
name String The name of the AVP to search for.

If a matching AVP is found, the get_first_instance_of_avp method returns an avp object with the following fields.

Field Type Description
.name String The name of the Diameter AVP, e.g. Rating-Group.
This field will only be present if the AVP is included within N2::DIAMETER::Codec or DiameterApp custom AVPs.
.code Integer The code that identifies the Diameter AVP.
.vendor_id Integer The identifier of the vendor that defines the AVP if the AVP is a vendor-specific AVP.
.type String One of None, OctetString, UTF8String, DiamIdent, Integer32, Integer64, Unsigned32, Enumerated, Time, Unsigned64, Address, Grouped.
This field will only be present if the AVP is included within N2::DIAMETER::Codec or DiameterApp custom AVPs.
.mandatory 0/1 The value of the AVP's mandatory flag.
.encryption 0/1 The value of the AVP's encryption flag.
.value Various The AVP's value.
For AVPs of type Grouped this will be an ARRAY of AVPs.
For all other AVPs this is a SCALAR of the appropriate type.

.get_first_value_of_avp [Synchronous]

The get_first_value_of_avp method searches an array of AVPs, returning the value of the first AVP with name matching a specified name. The following parameters are accepted.

Parameter Type Description
avps Array of Object Array of AVP descriptors each with the fields described for the get_first_instance_of_avp result.
name String The name of the AVP to search for.

If a matching AVP is found, the get_first_value_of_avp method returns that AVP’s value. For AVPs of type Grouped this will be an ARRAY of AVPs. For all other AVPs this is a SCALAR of the appropriate type.

.get_all_instances_of_avp [Synchronous]

The get_all_instances_of_avp method searches an array of AVPs, returning all AVPs with name matching a specified name. The following parameters are accepted.

Parameter Type Description
avps Array of Object Array of AVP descriptors each with the fields described for the get_first_instance_of_avp result.
name String The name of the AVP(s) to search for.

If at least one matching AVP is found, the get_all_instances_of_avp method returns an array of AVPs as per get_first_instance_of_avp. Otherwise an empty array is returned.

Built-In N2::Diameter::Codec Commands

The following list of Command names is built-in to the N2::Diameter::Codec encoding and decoding library. Commands not in this list may be referenced by numeric code, although they will not have support for setting special flags, or for changing the Diameter Application ID.

Name Code
AA265
Abort-Session274
Accounting271
Authentication-Information318
Bootstrapping-Info310
Capabilities-Exchange257
Credit-Control272
Device-Watchdog280
Diameter-EAP268
Disconnect-Peer282
Location-Info302
Message-Process311
Multimedia-Auth303
Notify323
Profile-Update307
Push-Notification309
Push-Profile305
Re-Auth258
Registration-Termination304
Server-Assignment301
Session-Termination275
Spending-Limit8388635
Spending-Status-Notification8388636
Subscribe-Notifications308
Update-Location316
User-Authorization300
User-Data306

Built-In N2::Diameter::Codec AVPs

The following list of AVPs is built-in to the N2::Diameter::Codec encoding and decoding library. Additional custom AVPs may be added as necessary on a per-site basis by using configuration in the DiameterApp.

Name Code Type & Flags
User-Name1UTF8String, Mandatory
Class25OctetString, Mandatory
Session-Timeout27Unsigned32, Mandatory
Proxy-State33OctetString, Mandatory
Accounting-Session-Id44OctetString, Mandatory
Acct-Multi-Session-Id50UTF8String, Mandatory
Event-Timestamp55Time, Mandatory
Acct-Interim-Interval85Unsigned32, Mandatory
Host-IP-Address257Address, Mandatory
Auth-Application-Id258Unsigned32, Mandatory
Acct-Application-Id259Unsigned32, Mandatory
Vendor-Specific-Application-Id260Grouped, Mandatory
Redirect-Host-Usage261Enumerated, Mandatory
Redirect-Max-Cache-Time262Unsigned32, Mandatory
Session-Id263UTF8String, Mandatory
Origin-Host264DiamIdent, Mandatory
Supported-Vendor-Id265Unsigned32, Mandatory
Vendor-Id266Unsigned32, Mandatory
Firmware-Revision267Unsigned32
Result-Code268Unsigned32, Mandatory
Product-Name269UTF8String
Session-Binding270Unsigned32, Mandatory
Session-Server-Failover271Enumerated, Mandatory
Multi-Round-Time-Out272Unsigned32, Mandatory
Disconnect-Cause273Enumerated, Mandatory
Auth-Request-Type274Enumerated, Mandatory
Auth-Grace-Period276Unsigned32, Mandatory
Auth-Session-State277Enumerated, Mandatory
Origin-State-Id278Unsigned32, Mandatory
Failed-AVP279Grouped, Mandatory
Proxy-Host280DiamIdent, Mandatory
Error-Message281UTF8String
Route-Record282DiamIdent, Mandatory
Destination-Realm283DiamIdent, Mandatory
Proxy-Info284Grouped, Mandatory
Re-Auth-Request-Type285Enumerated, Mandatory
Accounting-Sub-Session-Id287Unsigned64, Mandatory
Authorization-Lifetime291Unsigned32, Mandatory
Redirect-Host292DiamURI, Mandatory
Destination-Host293DiamIdent, Mandatory
Error-Reporting-Host294DiamIdent
Termination-Cause295Enumerated, Mandatory
Origin-Realm296DiamIdent, Mandatory
Experimental-Result297Grouped, Mandatory
Experimental-Result-Code298Unsigned32, Mandatory
Inband-Security-Id299Unsigned32, Mandatory
E2E-Sequence300Grouped, Mandatory
Accounting-Record-Type480Enumerated, Mandatory
Accounting-Realtime-Required483Enumerated, Mandatory
Accounting-Record-Number485Unsigned32, Mandatory
Called-Station-Id30UTF8String, Mandatory
Calling-Station-Id31UTF8String, Mandatory
CC-Correlation-Id411OctetString
CC-Input-Octets412Unsigned64, Mandatory
CC-Money413Grouped, Mandatory
CC-Output-Octets414Unsigned64, Mandatory
CC-Request-Number415Unsigned32, Mandatory
CC-Request-Type416Enumerated, Mandatory
CC-Service-Specific-Units417Unsigned64, Mandatory
CC-Session-Failover418Enumerated, Mandatory
CC-Sub-Session-Id419Unsigned64, Mandatory
CC-Time420Unsigned32, Mandatory
CC-Total-Octets421Unsigned64, Mandatory
CC-Unit-Type454Enumerated, Mandatory
Check-Balance-Result422Enumerated, Mandatory
Cost-Information423Grouped, Mandatory
Cost-Unit424UTF8String, Mandatory
Credit-Control426Enumerated, Mandatory
Credit-Control-Failure-Handling427Enumerated, Mandatory
Currency-Code425Unsigned32, Mandatory
Direct-Debiting-Failure-Handling428Enumerated, Mandatory
Exponent429Integer32, Mandatory
Final-Unit-Action449Enumerated, Mandatory
Final-Unit-Indication430Grouped, Mandatory
Granted-Service-Unit431Grouped, Mandatory
G-S-U-Pool-Identifier453Unsigned32, Mandatory
G-S-U-Pool-Reference457Grouped, Mandatory
Multiple-Services-Credit-Control456Grouped, Mandatory
Multiple-Services-Indicator455Enumerated, Mandatory
Rating-Group432Unsigned32, Mandatory
Redirect-Address-Type433Enumerated, Mandatory
Redirect-Server434Grouped, Mandatory
Redirect-Server-Address435UTF8String, Mandatory
Requested-Action436Enumerated, Mandatory
Requested-Service-Unit437Grouped, Mandatory
Restriction-Filter-Rule438IPFiltrRule, Mandatory
Service-Context-Id461UTF8String, Mandatory
Service-Identifier439Unsigned32, Mandatory
Service-Parameter-Info440Grouped
Service-Parameter-Type441Unsigned32
Service-Parameter-Value442OctetString
Subscription-Id443Grouped, Mandatory
Subscription-Id-Data444UTF8String, Mandatory
Subscription-Id-Type450Enumerated, Mandatory
Tariff-Change-Usage452Enumerated, Mandatory
Tariff-Time-Change451Time, Mandatory
Unit-Value445Grouped, Mandatory
Used-Service-Unit446Grouped, Mandatory
User-Equipment-Info458Grouped
User-Equipment-Info-Type459Enumerated
User-Equipment-Info-Value460OctetString
Value-Digits447Integer64, Mandatory
Validity-Time448Unsigned32, Mandatory
Subscription-Id-Extension659Grouped, Mandatory
Subscription-Id-E164660UTF8String, Mandatory
Subscription-Id-IMSI661UTF8String, Mandatory
Subscription-Id-SIP-URI662UTF8String, Mandatory
Subscription-Id-NAI663UTF8String, Mandatory
Subscription-Id-Private664UTF8String, Mandatory
Vendor ID = 10415
3GPP-IMSI1UTF8String
3GPP-GGSN-Address7OctetString
3GPP-GGSN-MCC-MNC9UTF8String
3GPP-SGSN-MCC-MNC18UTF8String
3GPP-RAT-Type21OctetString
3GPP-User-Location-Info22OctetString
3GPP-MS-TimeZone23OctetString
Policy-Counter-Identifier2901UTF8String, Mandatory
Policy-Counter-Status2902UTF8String, Mandatory
Policy-Counter-Status-Report2903Grouped, Mandatory
SL-Request-Type2904Enumerated, Mandatory
Event-Type823Grouped, Mandatory
Event825UTF8String, Mandatory
Calling-Party-Address831UTF8String, Mandatory
Called-Party-Address832UTF8String, Mandatory
Application-Provided-Called-Party-Address837UTF8String, Mandatory
GGSN-Address847Address, Mandatory
Application-Server-Information850Grouped, Mandatory
Time-Quota-Threshold868Unsigned32, Mandatory
Volume-Quota-Threshold869Unsigned32, Mandatory
Service-Information873Grouped, Mandatory
PS-Information874Grouped, Mandatory
IMS-Information876Grouped, Mandatory
LCS-Information878Grouped, Mandatory
Address-Data897UTF8String, Mandatory
Address-Type899Enumerated, Mandatory
QoS-Information1016Grouped
Recipient-Address1201Grouped, Mandatory
SGSN-Address1228Address, Mandatory
Requested-Party-Address1251UTF8String, Mandatory
SMS-Information2000Grouped, Mandatory
SM-Message-Type2007Enumerated, Mandatory
Refund-Information2022OctetString, Mandatory
Recipient-Info2026Grouped, Mandatory
VCS-Information3410Grouped, Mandatory
Bearer-Capability3412OctetString, Mandatory
ISUP-Location-Number3414OctetString, Mandatory
MSC-Address3417OctetString, Mandatory
VLR-Number3420OctetString, Mandatory
Vendor ID = 3512
ORA-Account-Topup206Grouped, Mandatory
ORA-Recharge-Reference207UTF8String, Mandatory
ORA-Balance208Grouped, Mandatory
ORA-Validity-Start-Time213Time, Mandatory
ORA-Validity-End-Time214Time, Mandatory
ORA-Validity-Start-Relative215Grouped, Mandatory
ORA-Validity-End-Relative216Grouped, Mandatory
ORA-First-Usage-Validity217Grouped, Mandatory
ORA-Validity-Offset218Unsigned32, Mandatory
ORA-Validity-Unit219Enumerated, Mandatory
ORA-Extend-Bucket-Validity228Enumerated, Mandatory
ORA-Customer-Cost-Information231Grouped, Mandatory
ORA-Cost-Information232Grouped, Mandatory
ORA-Balance-Element-Id233Integer32, Mandatory
ORA-Subscriber-Id235OctetString, Mandatory
ORA-Remaining-Balance241Grouped, Mandatory
ORA-Balance-Element243Grouped, Mandatory
ORA-Earliest-Expiry-Time245Time, Mandatory
ORA-Balance-Query-Mode248Integer32, Mandatory
ORA-Balance-Details249Grouped, Mandatory
ORA-Credit-Floor252Grouped, Mandatory