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 INAP Agent may be used by any Lua script, regardless of which Service initiated that script.

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`	Attribute	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:

Invalid input parameters supplied by Lua script.
Internal processing error.

.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).

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 = {
      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 Extension):

  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_octet_string = '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)

.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).

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 ('srf.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).

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 ('srf.scp.1')

    tcap_api.check_opcode ('srf.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 ('srf.scp.1')

    tcap_api.check_opcode ('srf.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:

inap_api.MM_Interrupted = 0
inap_api.MM_NotifyAndContinue = 1
inap_api.MM_Transparent = 2
nil (No EDP arming for oAnswer or tAnswer)

[Fragment] Example (Detect Answer Arming):

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

    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:

inap_api.MM_Interrupted = 0
inap_api.MM_NotifyAndContinue = 1
inap_api.MM_Transparent = 2
nil (No EDP arming for oDisconnect Leg 1 or tDisconnect Leg 1)

[Fragment] Example (Echo Disconnect Leg Arming):

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

    -- 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 SMS Opcodes
inap.OPCODE_InitialDPSMS = 60
inap.OPCODE_ContinueSMS = 65
inap.OPCODE_ReleaseSMS = 66

-- 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