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
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:
- 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).
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:
inap_api.MM_Interrupted
=0
inap_api.MM_NotifyAndContinue
=1
inap_api.MM_Transparent
=2
nil
(No EDP arming foroAnswer
ortAnswer
)
[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:
inap_api.MM_Interrupted
=0
inap_api.MM_NotifyAndContinue
=1
inap_api.MM_Transparent
=2
nil
(No EDP arming foroDisconnect
Leg 1 ortDisconnect
Leg 1)
[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