☰
Navigation :

INAP Lua Agent

Introduction

The InapLuaAgent is an synchronous helper for Lua scripts running within the LogicApp. It is used for encoding and decoding Intelligent Network Application Part (INAP) or CAMEL Application Part (CAP) operations.

The InapLuaAgent performs the encoding/decoding functions internally and does not rely on any other external applications to perform this task. Hence it does not send or receive any messages.

INAP Agent methods are accessed via the “n2.n2svcd.inap_agent” module:

    local inap_api = require "n2.n2svcd.inap_agent"

Configuring InapLuaAgent

The InapLuaAgent 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>
              ...
            </services>
            <agents>
              <agent module="SigtranApp::InapLuaAgent" libs="../apps/sigtran/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

Parameter Name Type XML Type Description
module SigtranApp:: InapLuaAgent Attribute [Required] The module name containing the Lua Agent code.
libs ../apps/sigtran/lib Element Location of the module for InapLuaAgent.

Note that despite the fact that the Agent module resides within the SigtranApp, invoking the INAP Agent functions to encode/decode an INAP/CAP operation does not perform any interaction with the SigtranApp at that time.

The SigtranApp interaction occurs only at the time when the INAP/CAP message is actually sent over TCAP, using the TCAP Agent.

The INAP Agent does not reference any entries in the LogicApp’s <parameters> element, nor does it use any expanded <config> block within the <agent> entry.

The InapLuaAgent API

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

.encode_op [Synchronous]

The encode_op method encodes a table structure into an INAP/CAP Invoke binary ASN.1 byte sequence.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the INAP/CAP operation to encode into ASN.1.
Specify one of the provided constants, e.g. inap_api.OPCODE_ApplyCharging.
argument Table A (typically nested) table structure defining the attributes of the operation to be encoded.
For the structure of this parameter, see Tester Internals (INAP Operations).
variant String An optional identifier for the INAP/CAP variant to use when encoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (INAP Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The encode_op method returns the binary ASN.1 “parameter”, which is then passed as the parameter for an Invoke component for the send_components method of the TCAP Agent API.

[Fragment] Example (Encode CAMEL2 ApplyChargingReport):

    local arg_ApplyChargingReport = {
      ["CAMEL-CallResult"] = {
        timeDurationChargingResult = {
          callActive = 1,
          partyToCharge = { receivingSideID = '\001' },
          timeInformation = { timeIfNoTariffSwitch = v_talktime }
        }
      }
    }
    param_ApplyChargingReport = inap_api.encode_op (inap_api.OPCODE_ApplyChargingReport, arg_ApplyChargingReport, 'camel2', nil)

    local components = { 
      { type = tcap_api.CT_INVOKE, opcode = inap_api.OPCODE_ApplyChargingReport, parameter = param_ApplyChargingReport } 
    }
    tcap_api.send_components ('ssp.scp.1', , tcap_api.TYPE_CONTINUE)

[Fragment] Example (Encode ETSI InitialDP with Extensions):

  local inap_hints = {
    extensions = { ["400"] = 'OCTET STRING', ["401"] = 'OCTET STRING' }
  }

  arg_InitialDP = {
    bearerCapability = { bearerCap_hex = '8090a3' },
    callReferenceNumber_auto = 1,
    calledPartyNumber_digits = '1800' .. v_suffix,
    calledPartyNumber_noa = 3,
    callingPartyNumber_digits = v_cli,
    callingPartyNumber_noa = 3,
    callingPartysCategory_hex = 'f7',
    eventTypeBCSM = 3,
    extensions = {
      { type = '400', value_inner = 'BOSS' }
    },
    forwardCallIndicators_hex = '2001',
    highLayerCompatibility_hex = '9181',
    locationNumber_digits = '61415015122',
    locationNumber_noa = 4,
    serviceInteractionIndicators_hex = '300ba009810102820101880100',
    serviceKey = 3000
  }
  param_InitialDP = inap_api.encode_op (inap_api.OPCODE_InitialDP, arg_InitialDP, nil, inap_hints)

.encode_result [Synchronous]

The encode_result method encodes a table structure into a INAP/CAP ReturnResult binary ASN.1 byte sequence.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the INAP/CAP operation whose Result we will encode into ASN.1.
Specify one of the provided constants, e.g. inap_api.OPCODE_ApplyCharging.
argument Table A (typically nested) table structure defining the attributes of the operation Result to be encoded.
For the structure of this parameter, see Tester Internals (INAP Operations).
variant String An optional identifier for the INAP/CAP variant to use when encoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (INAP Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The encode_result method returns the binary ASN.1 “parameter”, which is then passed as the parameter for a ReturnResult component for the send_components method of the TCAP Agent API.

[Fragment] Example (Encode PromptAndCollectUserInformationResult):

  -- SEND PromptAndCollectUserInformationResult
  local arg_PromptAndCollectUserInformationResult = { digitsResponse_digits = '1234' }
  local param_PromptAndCollectUserInformationResult = inap_api.encode_result (inap_api.OPCODE_PromptAndCollectUserInformation, arg_PromptAndCollectUserInformationResult, nil, nil)

  tcap_api.send_components ('srp.scp.1', { { type = tcap_api.CT_RETURN_RESULT, opcode = inap_api.OPCODE_PromptAndCollectUserInformation, parameter = param_PromptAndCollectUserInformationResult } }, tcap_api.TYPE_CONTINUE)

.decode_op [Synchronous]

The decode_op decodes a INAP/CAP Invoke binary ASN.1 byte sequence into a table containing individual field values.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the INAP/CAP operation to decode from ASN.1.
Specify one of the provided constants, e.g. inap_api.OPCODE_ApplyCharging.
parameter Table
variant String An optional identifier for the INAP/CAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (INAP Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The decode_op method returns a (typically nested) table structure containing the attributes of the Invoke as decoded.
For the structure of this parameter, see Tester Internals (INAP Operations).

[Fragment] Example (Decode/Match ETSI PlayAnnouncement):

    result = tcap_api.expect_invoke ('srp.scp.1')

    tcap_api.check_opcode ('srp.scp.1', result, inap_api.OPCODE_PlayAnnouncement, 'INAP PlayAnnouncement')
    arg_PlayAnnouncement = inap_api.decode_op (result.opcode, result.parameter, nil, nil)

.match_op [Synchronous]

The match_op method compares the actual Invoke argument structure decoded from an INAP/CAP operation ASN.1 parameter against an expected argument structure.

The actual fields to be compared are specific to the particular INAP/CAP operation code, and will typically also vary according to the specific INAP/CAP protocol variant.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the INAP/CAP operation to decode from ASN.1.
Specify one of the provided constants, e.g. inap_api.OPCODE_ApplyCharging.
argument Table A (typically nested) table structure defining the actual attributes of the operation to be match.
This is typical the returned result from a call to the decode_op method.
For the structure of this parameter, see Tester Internals (INAP Operations).
expected Table A (typically nested) table structure defining the expected attributes of the operation we have just received.
This expected structure is identical to the decoded structure, and identical to the structure passed into encode_op.
For the structure of this parameter, see Tester Internals (INAP Operations).
variant String An optional identifier for the INAP/CAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (INAP Operations).

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_op method returns nil.

[Fragment] Example (Decode/Match ETSI PlayAnnouncement):

    result = tcap_api.expect_invoke ('srp.scp.1')

    tcap_api.check_opcode ('srp.scp.1', result, inap_api.OPCODE_PlayAnnouncement, 'INAP PlayAnnouncement')
    arg_PlayAnnouncement = inap_api.decode_op (result.opcode, result.parameter, nil, nil, exp_PlayAnnouncement)

    exp_PlayAnnouncement = {
      informationToSend = {
        inbandInfo = {
          messageID = { elementaryMessageID = v_ID1 }
        }
      }
    }
    inap_api.match_op (inap_api.OPCODE_PlayAnnouncement, arg_PlayAnnouncement, exp_PlayAnnouncement, nil)

.rrbcsm_answer_mm [Pure Lua]

The rrbcsm_answer_mm is a pure Lua convenience function, to detect if a decoded RequestReportBCSMEvent includes an Answer EDP arming request.

This method accepts the following parameters.

Field Type Description
arg_RequestReportBCSMEvent Table The decoded structure from a call to inap_api.decode_op for an INAP RequestReportBCSMEvent parameter.

The rrbcsm_answer_mm method returns the armed monitor mode for the first contained oAnswer or tAnswer EDP. The returned monitor mode will be one of the following:

[Fragment] Example (Detect Answer Arming):

    arg_RequestReportBCSMEvent = inap_api.decode_op (result.opcode, result.parameter, nil, inap_hints, exp_RequestReportBCSMEvent)

    if (not (inap_api.rrbcsm_answer_mm (arg_RequestReportBCSMEvent)))
    then goto answer_not_armed end

.rrbcsm_disconnect1_mm [Pure Lua]

The rrbcsm_disconnect1_mm method is a pure Lua convenience function, to detect if a decoded RequestReportBCSMEvent includes an oDisconnect or tDisconnect EDP arming request where the sendingSideID is defined and == 1 (binary).

This method accepts the following parameters.

Field Type Description
arg_RequestReportBCSMEvent Table The decoded structure from a call to inap_api.decode_op for an INAP RequestReportBCSMEvent parameter.

The rrbcsm_disconnect1_mm method returns the armed monitor mode for the first contained oDisconnect or tDisconnect EDP for sendingSideID == 1. The returned monitor mode will be one of the following:

[Fragment] Example (Echo Disconnect Leg Arming):

    -- Decode received RRBCSM.
    arg_RequestReportBCSMEvent = inap_api.decode_op (result.opcode, result.parameter, nil, inap_hints, exp_RequestReportBCSMEvent)

    -- Copy the Disconnect Leg 1 Monitor Mode back into returned ERBCSM.
    arg_EventReportBCSM = {
      eventTypeBCSM_name = 'oDisconnectLeg1',
      miscCallInfo = {
        messageType = (inap_api.rrbcsm_disconnect1_mm (arg_RequestReportBCSMEvent) or 1)
      }
    }
    param_EventReportBCSM = inap_api.encode_op (inap_api.OPCODE_EventReportBCSM, arg_EventReportBCSM)

.ac_is_ride [Pure Lua]

The ac_is_ride method is a pure Lua convenience function, to detect if a decoded ApplyCharging for CAMEL2 or CAMEL3 includes the “Release if Duration Exceeded” flag.

Detection of CAMEL2/CAMEL3 is automatic.

This method accepts the following parameters.

Field Type Description
arg_ApplyCharging Table The decoded structure from a call to inap_api.decode_op for an INAP ApplyCharging parameter.

The ac_is_ride method a Boolean value.

[Fragment] Example (RIDE DETECTION):

    -- Decode received ApplyCharging.
    tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_ApplyCharging, 'INAP ApplyCharging')
    arg_ApplyCharging = inap_api.decode_op (result.opcode, result.parameter, 'camel2', nil, nil)

    if (inap_api.ac_is_ride (arg_ApplyCharging))
    then tester.match_pass ('Test for Release if Duration Exceeded.', 'Release if Duration Exceeded is TRUE, as expected.')
    else error ('Expected Release if Duration Exceeded.')
    end

Constants

The following INAP constants are defined on the returned inap_api object.

-- INAP OPCODE Constants.
inap_api.OPCODE_ActivityTest = 55
inap_api.OPCODE_ApplyCharging = 35
inap_api.OPCODE_ApplyChargingReport = 36
inap_api.OPCODE_AssistRequestInstructions = 16
inap_api.OPCODE_CallInformationReport = 44
inap_api.OPCODE_CallInformationRequest = 45
inap_api.OPCODE_Connect = 20
inap_api.OPCODE_ConnectToResource = 19
inap_api.OPCODE_Continue = 31
inap_api.OPCODE_ContinueWithArgument = 88
inap_api.OPCODE_DisconnectForwardConnection = 18
inap_api.OPCODE_DisconnectForwardConnectionWithArgument = 86
inap_api.OPCODE_DisconnectLeg = 90
inap_api.OPCODE_EstablishTemporaryConnection = 17
inap_api.OPCODE_EventReportBCSM = 24
inap_api.OPCODE_FurnishChargingInformation = 34
inap_api.OPCODE_InitialDP = 0
inap_api.OPCODE_MergeCallSegments = 91
inap_api.OPCODE_PlayAnnouncement = 47
inap_api.OPCODE_PromptAndCollectUserInformation = 48
inap_api.OPCODE_ReleaseCall = 22
inap_api.OPCODE_RequestReportBCSMEvent = 23
inap_api.OPCODE_ResetTimer = 33
inap_api.OPCODE_SendChargingInformation = 46
inap_api.OPCODE_SpecializedResourceReport = 49
inap_api.OPCODE_SplitLeg = 95

-- INAP Monitor Mode Constants.
inap_api.MM_Interrupted = 0
inap_api.MM_NotifyAndContinue = 1
inap_api.MM_Transparent = 2

-- INAP Event Detection Point Constants.
inap_api.EDP_origAttemptAuthorized = 1
inap_api.EDP_collectedInfo = 2
inap_api.EDP_analyzedInformation = 3
inap_api.EDP_routeSelectFailure = 4
inap_api.EDP_oCalledPartyBusy = 5
inap_api.EDP_oNoAnswer = 6
inap_api.EDP_oAnswer = 7
inap_api.EDP_oMidCall = 8
inap_api.EDP_oDisconnect = 9
inap_api.EDP_oAbandon = 10
inap_api.EDP_termAttemptAuthorized = 12
inap_api.EDP_tCalledPartyBusy = 13
inap_api.EDP_tNoAnswer = 14
inap_api.EDP_tAnswer = 15
inap_api.EDP_tMidCall = 16
inap_api.EDP_tDisconnect = 17
inap_api.EDP_tAbandon = 18