TCAP Lua Agent
Introduction
The TcapLuaAgent is a helper agent for Lua scripts running within the LogicApp.
- The TCAP Agent may be used by any Lua script, regardless of which Service initiated that script.
The TcapLuaAgent communicates with one or more instances of the SigtranApp which can be used to communicate via one or more external M3UA or SUA connections.
The TcapLuaAgent communicates with the SigtranApp using the TCAP-… messages.
TCAP Agent methods are accessed via the “n2.n2svcd.tcap_agent” module:
local tcap_api = require "n2.n2svcd.tcap_agent"
Configuring TcapLuaAgent
The TcapLuaAgent 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_tcap_app_name" value="SIGTRAN-C"/>
</parameters>
<config>
<services>
...
</services>
<agents>
<agent module="SigtranApp::TcapLuaAgent" libs="../apps/sigtran/lib">
<config tcap_timeout_secs="20" ignore_reset_timer="1"/>
</agent>
</agents>
</config>
</application>
...
</application>
...
</n2svcd>
Under normal installation, following agent
attributes apply:
Parameter Name
Type
XML Type
Description
module
SigtranApp::
TcapLuaAgent
Attribute
[Required] The module name containing the Lua Agent code.
libs
../apps/sigtran/lib
Element
Location of the
module
for TcapLuaAgent.
config
Object
Element
Container for extended configuration for this Application instance.
.tcap_timeout_secs
Integer
Attribute
How long to wait for an expected TCAP message to arrive.
(Default = 10
seconds)
.ignore_reset_timer
0
/ 1
Attribute
Should received
ResetTimer
operations be ignored when received?
The service logic may override this for individual tests.
(Default = 0
, do not ignore, pass to user layer)
.auto_activity_result
0
/ 1
Attribute
Should we automatically send
ActivityTestResult
for ActivityTest
.
The service logic may override this for individual tests.
(Default = 0
, do not automatically respond)
In addition, the TcapLuaAgent must be configured with the name of the SigtranApp 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_tcap_app_name
String
Attribute
Default name for the SigtranApp with which TcapLuaAgent will communicate.
.tcap_appname<route>
String
Attribute
Use this format when
TcapLuaAgent
will communicate with more than one SigtranApp
.
(Default = TcapLuaAgent uses only the default route/SIGTRAN connectivity application).
The TcapLuaAgent API
All methods may raise a Lua Error in the case of exception, including:
- Invalid input parameters supplied by Lua script.
- Unexpected results structure returned from SigtranApp.
- Processing error occurred at SigtranApp.
- Timeout occurred at SigtranApp.
.ignore_reset_timer [Synchronous]
The ignore_reset_timer
method overrides the default behavior for handling of ResetTimer
INAP operations.
This method accepts the following parameters:
Field
Type
Description
value
Boolean /
UNDEF
Should the TcapLuaAgent ignore received
ResetTimer
operations?
true
= yes, ignore. These operations are silently discarded.
false
= no, do not ignore. The script must explicitly expect these operations.
nil
= revert to the default behavior configured for the agent.
The ignore_reset_timer
method returns nil
.
[Fragment] Example (Enable ignore of ResetTimer):
tcap_api.ignore_reset_timer (true)
.auto_activity_result [Synchronous]
The auto_activity_result
method overrides the default behavior for handling of ActivityTest
INAP operations.
This method accepts the following parameters:
Field
Type
Description
value
Boolean /
UNDEF
Should the TcapLuaAgent automatically respond to
ActivityTest
operations?
true
= yes, send automatic response then silently discard the operation.
false
= no, do not automatically respond. The script must explicitly expect these operations and generate responses.
nil
= revert to the default behavior configured for the agent.
The auto_activity_result
method returns nil
.
[Fragment] Example (Enable automatic handling of ActivityTest):
tcap_api.auto_activity_result (true)
.initialise [Synchronous]
The initialise
method creates and prepares a new outbound TCAP transaction for the subsequent
sending of a TCAP BEGIN message.
This method accepts the following parameters:
Field
Type
Description
route
String
The identifier of the SIGTRAN application to use, or
nil
for the default.
transaction
String
[Required] A key for the new TCAP transaction. This must be unique within this Lua instance (script).
Closing a TCAP transaction via TCAP END or TCAP ABORT or TCAP Pre-Arranged END does not free up the transaction name for re-use.
The standard naming convention for these transactions has the form “ssp.scp.1”, where
“ssp” is the role of the local end of the transaction, “scp” is the role for the far and
of the transaction, and “1”, “2”, etc. is the incrementing “subcall” number within this
instance.
sccp_dest_address
Table
The SCCP address to which the TCAP BEGIN should be sent.
Subsequent messages will be sent to the SCCP address which responds back to us for that transaction.
.dri
0
/ 1
SCCP Destination Routing Indicator
(Default = Automatically Determined).
.dpc
Integer
SCCP Destination Point Code
(Default = Does not route on PC/SSN).
.dssn
Integer
SCCP Destination Subsystem Number
(Default = Does not route on PC/SSN).
.dgt_digits
String
SCCP Destination Global Title Digits
(Default = Does not route on GT).
.dgt_noa
Integer
SCCP Destination Global Title Nature of Address
(Default = Varies).
.dgt_np
Integer
SCCP Destination Global Title Numbering Plan
(Default = Varies).
.dgt_tt
Integer
SCCP Destination Global Title Translation Type
(Default = Automatically Determined).
tcap_ac_bin
String
[Required] A binary TCAP Application Context string.
This is typically one of the entries in the tcap_api.APPLICATION_CONTEXT_ALIASES
table.
The initialise
method returns nil
.
[Fragment] Example (Initialise CAMEL2 Transaction):
local scp_dra = {
dgt_digits = "049991000"
}
tcap_api.initialise (nil, 'ssp.scp.1', scp_dra, tcap_api.APPLICATION_CONTEXT_ALIASES['camel2'])
.map_register_ati3_msisdn [Synchronous]
There are three mechanisms by which Lua scripts running in the LogicApp can becomes associated with a new TCAP transaction. Those mechanisms are as follows:
- An incoming TCAP BEGIN can start a new script by invoking a Lua Service.
- An already-running Lua script can create a new outbound TCAP transaction using the
initialise
method. - An already-running Lua script can register to accept a new unbound TCAP transaction using one of the register methods.
The most common use of these “register” methods is a test script which is testing another application and which expects that “application under test” to generate a TCAP transaction. e.g. we are writing a test script to send InitialDP and simulate a call for a mobile subscriber. We expect the application to send out a MAP AnyTimeInterrogation message to determine the current subscriber state.
The map_register_ati3_msisdn
method informs the LogicApp that this currently running script instance
expects to receive a new inbound TCAP BEGIN in the near future. The LogicApp will register that expectation,
and if/when the matching AnyTimeInterrogation arrives, it will be delivered to the script instance.
Naturally, only one script instance may be registered for the exact ATI MSISDN digits at any one time.
The full set of matching conditions for the inbound TCAP BEGIN is:
- The Dialogue part must have the TCAP Application Context =
4.0.0.1.0.51.3
. - There must be exactly one component.
- The component must be Invoke.
- The Invoke must have operation ID = 71 (ATI).
- The AnyTimeInterrogation must be decodable.
- The AnyTimeInterrogation must contain the
subscriberIdentity
. - The
subscriberIdentity
MSISDN digits must exactly match the specified digits.
This is a synchronous method. It sets the registration information in preparation for a message
and then returns immediately. The expect_invoke
method must then be used to retrieve the actual
ATI operation if/when it arrives.
The registration method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] A key for the new TCAP transaction which will be created when the TCAP BEGIN arrives.
This must be unique within this Lua instance (script).
Closing a TCAP transaction via TCAP END or TCAP ABORT or TCAP Pre-Arranged END does not free up the transaction name for re-use.
The standard naming convention for these transactions has the form “ssp.scp.1”, where
“ssp” is the role of the local end of the transaction, “scp” is the role for the far and
of the transaction, and “1”, “2”, etc. is the incrementing “subcall” number within this
instance.
msisdn_digits
String
The
subscriberIdentity.MSISDN
digits which must exactly match, in order for the new AnyTimeInterrogation
transaction to be associated with the current-running Lua script.
The map_register_ati3_msisdn
method returns nil
.
[Fragment] Example (Register for ATI Transaction):
-- Register to expect an inbound AnyTimeInterrogationRequest for our MSISDN.
tcap.map_register_ati3_msisdn ('hlr.scp.1', '414511860')
-- EXPECT AnyTimeInterrogationRequest
local result = tcap.expect_invoke ('hlr.scp.1')
tcap.check_opcode ('hlr.scp.1', result, map_api.OPCODE_AnyTimeInterrogationRequest, 'map AnyTimeInterrogationRequest')
local arg_AnyTimeInterrogationRequest = map_api.decode_op (result.opcode, result.parameter)
.map_deregister [Synchronous]
This method will cancel any existing prior registration for all/any inbound MAP operation.
If no MAP registration is present, this method will silently suceed.
The map_deregister
method taks no parameters.
At most one MAP registration may be activated at any time, and so it is not necessary to resupply the registration parameters here, since there is no ambiguity.
[Fragment] Example (De-Register any current MAP registration):
tcap.map_deregister ()
.send_components [Synchronous]
The send_components
method sends one or more TCAP Components on a previously initialised outbound
TCAP transction. The components are sent in a single TCAP message. The first message sent on an
initialised TCAP transction must be TCAP BEGIN. Subsequent messages may be TCAP CONTINUE or TCAP END.
The transaction becomes closed automatically if a TCAP END is sent.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
components
List
[Required] Array of components to send. May contain zero components.
Each has the following structure.
.type
String
[Required] Type of component, being one of:
tcap_api.CT_INVOKE
- TCAP Invoke
tcap_api.CT_RETURN_RESULT
- TCAP Return Result
tcap_api.CT_RETURN_ERROR
- TCAP Return Error
.opcode
Integer
The INAP Operation Code. This is required for Invoke.
Optional for Return Result without parameter, and for Return Error.
.parameter
Integer
The ASN.1 encoded binary parameter, if required for this type/opcode.
msg_type
String
[Required] One of
tcap_api.TYPE_BEGIN
, tcap_api.TYPE_CONTINUE
, tcap_api.TYPE_END
.
map_open
String
Defines a MAP-OPEN to be sent in the AARQ dialogue element.
This field should only be present when using TYPE_BEGIN
, and should
always be present when performing a TCAP BEGIN for the MAP protocol.
To create a minimum empty MAP-OPEN address, specify {}
for this parameter.
(Default = MAP-OPEN is not present).
.destination_reference_digits
Hex String
The digits for the Destination Reference address in the MAP-OPEN.
(Default = destination reference is not present).
.destination_reference_noa
Integer
The Nature of Address for the Destination Reference address in the MAP-OPEN.
(Default = 0
).
.destination_reference_npi
Integer
The Numbering Plan Indicator for the Destination Reference address in the MAP-OPEN.
(Default = 1
).
.origination_reference_digits
Hex String
The digits for the Origination Reference address in the MAP-OPEN.
(Default = orgination reference is not present).
.origination_reference_noa
Integer
The Nature of Address for the Origination Reference address in the MAP-OPEN.
(Default = 0
).
.origination_reference_npi
Integer
The Numbering Plan Indicator for the Origination Reference address in the MAP-OPEN.
(Default = 1
).
The send_components
method returns nil
.
[Fragment] Example (Encode/Send RRBCSM):
-- SEND EventReportBCSM
arg_EventReportBCSM = {
eventSpecificInformationBCSM = {
oDisconnectSpecificInfo = { releaseCause_cause = 12 }
},
eventTypeBCSM = 9,
legID = { sendingSideID_hex = '01' }
}
param_EventReportBCSM = inap_api.encode_op (inap_api.OPCODE_EventReportBCSM, arg_EventReportBCSM, nil, nil)
tcap_api.send_components ('ssp.scp.1', { { type = tcap_api.CT_INVOKE, opcode = inap_api.OPCODE_EventReportBCSM, parameter = param_EventReportBCSM } }, tcap_api.TYPE_CONTINUE)
[Fragment] Example (Encode/Send ProcessUSSD Request):
local scp_dra = { dpc = 2068, dssn = 120 }
tcap_agent.initialise (nil, 'hlr.scp.1', scp_dra, tcap_agent.APPLICATION_CONTEXT_ALIASES['ussd2'])
-- Start USSD session.
local param_ProcessUnstructuredSSRequest = map_agent.encode_op (map_agent.OPCODE_ProcessUnstructuredSSRequest, { msisdn_digits = '9607499901', ussdString_text = '*123#' }, nil, nil)
-- MAP-OPEN is required (empty in this case).
tcap_agent.send_components ('hlr.scp.1', { { type = tcap_agent.CT_INVOKE, opcode = map_agent.OPCODE_ProcessUnstructuredSSRequest, parameter = param_ProcessUnstructuredSSRequest } }, tcap_agent.TYPE_BEGIN, {})
.send_empty_end [Synchronous]
The send_empty_end
method sends one an empty TCAP END previously initialised outbound
TCAP transction.
The transaction becomes closed automatically.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
The send_empty_end
method returns nil
.
[Fragment] Example (Send Empty END):
-- SEND EventReportBCSM
tcap_api.send_empty_end ('ssp.scp.1')
.send_abort [Synchronous]
The send_abort
method sends a TCAP ABORT message on a previously initialised outbound TCAP transction.
The transaction is subsequently closed.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
p_cause
Integer
Specify the Protocol Cause.
(Default = attribute is not present).
u_source
Integer
Specify the User Source.
(Default = attribute is not present).
u_source
List of String
Array of User Information strings.
(Default = attribute is not present).
The send_abort
method returns nil
.
[Fragment] Example (Send User Abort):
tcap_api.send_abort ('ssp.scp.1', nil, 1, { "Processing Error 3007-A" })
.expect_invoke [Asynchronous]
The expect_invoke
method waits until a TCAP Invoke component is received on the specified TCAP transaction.
- If the transaction is not registered for this instance, an error is raised.
- If an Invoke component has previously been received but not handled, it will be returned immediately.
- If the received component is/was a ReturnResult/ReturnError, an error is raised.
- If the received message is/was a TCAP ABORT, an error is raised.
- If the transaction is closed with no unhandled components, an error is raised.
- If the timeout expires with no message received, an error is raised.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
seconds
Number
Override the default TCAP timer.
(Default = configured timer for TCAP Agent).
The expect_invoke
method returns the following result
structure.
Field
Type
Description
result
Table
Container for returned attributes.
.tcap_ac_bin
String
Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result
Integer
Integer
result
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user
Integer
Integer
result-source-diagnostic.dialogue-service-user
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider
Integer
Integer
result-source-diagnostic.dialogue-service-provider
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.opcode
Integer
The received Invoke Operation Code.
.invoke_id
Integer
The received Invoke ID.
.parameter
String
The binary-encoded ASN.1 operation parameter.
.last_component
Integer
Returned as
1
if and only if this Invoke was the last TCAP component within a TCAP END message.
[Fragment] Example (Expect ApplyCharging Invoke):
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_ApplyCharging, 'INAP ApplyCharging')
.expect_result [Asynchronous]
The expect_result
method waits until a TCAP ReturnResult component is received on the specified TCAP transaction.
- If the transaction is not registered for this instance, an error is raised.
- If an ReturnResult component has previously been received but not handled, it will be returned immediately.
- If the received component is/was a Invoke/ReturnError, an error is raised.
- If the received message is/was a TCAP ABORT, an error is raised.
- If the transaction is closed with no unhandled components, an error is raised.
- If the timeout expires with no message received, an error is raised.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
seconds
Number
Override the default TCAP timer.
(Default = configured timer for TCAP Agent).
The expect_result
method returns the following result
structure.
Field
Type
Description
result
Table
Container for returned attributes.
.tcap_ac_bin
String
Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result
Integer
Integer
result
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user
Integer
Integer
result-source-diagnostic.dialogue-service-user
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider
Integer
Integer
result-source-diagnostic.dialogue-service-provider
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.opcode
Integer
The sent Invoke Operation Code for which this is a ReturnResult.
.invoke_id
Integer
The sent Invoke ID for which this is a ReturnResult.
.parameter
String
The binary-encoded ASN.1 operation parameter (if present).
.last_component
Integer
Returned as
1
if and only if this ReturnResult was the last TCAP component within a TCAP END message.
[Fragment] Example (Expect ProcessUnstructuredSSRequest ReturnResult):
result = tcap_api.expect_result ('hlr.scp.1')
tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequest / ReturnResult')
tcap_api.match_received_last_component ('hlr.scp.1', result, true)
local arg_ProcessUnstructuredSSRequestResult = map_api.decode_result (result.opcode, result.parameter, nil, nil)
local exp_ProcessUnstructuredSSRequestResult = { ussdString_text = 'Early Response Message' }
map_api.match_result (result.opcode, arg_ProcessUnstructuredSSRequestResult, exp_ProcessUnstructuredSSRequestResult, nil)
.expect_error [Asynchronous]
The expect_error
method waits until a TCAP ReturnError component is received on the specified TCAP transaction.
- If the transaction is not registered for this instance, an error is raised.
- If an ReturnError component has previously been received but not handled, it will be returned immediately.
- If the received component is/was a Invoke/ReturnResult, an error is raised.
- If the received message is/was a TCAP ABORT, an error is raised.
- If the transaction is closed with no unhandled components, an error is raised.
- If the timeout expires with no message received, an error is raised.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
seconds
Number
Override the default TCAP timer.
(Default = configured timer for TCAP Agent).
The expect_error
method returns the following result
structure.
Field
Type
Description
result
Table
Container for returned attributes.
.tcap_ac_bin
String
Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result
Integer
Integer
result
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user
Integer
Integer
result-source-diagnostic.dialogue-service-user
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider
Integer
Integer
result-source-diagnostic.dialogue-service-provider
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
.opcode
Integer
The sent Invoke Operation Code for which this is a ReturnError.
.invoke_id
Integer
The sent Invoke ID for which this is a ReturnError.
.error_code
Integer
The binary-encoded ASN.1 operation parameter.
.last_component
Integer
Returned as
1
if and only if this ReturnResult was the last TCAP component within a TCAP END message.
[Fragment] Example (Expect ProcessUnstructuredSSRequest ReturnError):
local result = tcap_api.expect_error ('hlr.scp.1')
tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequest / ReturnError')
tcap_api.match_received_last_component ('hlr.scp.1', result, true)
match.integer ('ProcessUnstructuredSSRequest error_code', result.error_code, 27)
.expect_empty_end [Asynchronous]
The expect_empty_end
method waits until a TCAP END is received on the specified TCAP transaction,
with no contained Components.
- If the transaction is not registered for this instance, an error is raised.
- If any component has previously been received but not handled, an error is raised.
- If the received message is/was a TCAP ABORT, an error is raised.
- If the timeout expires with no message received, an error is raised.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
seconds
Number
Override the default TCAP timer.
(Default = configured timer for TCAP Agent).
The expect_empty_end
method returns the following result
structure.
Field
Type
Description
result
Table
Container for returned attributes.
.tcap_ac_bin
String
Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result
Integer
Integer
result
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
tcap_aare_result_diagnostic_user
Integer
Integer
result-source-diagnostic.dialogue-service-user
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
tcap_aare_result_diagnostic_provider
Integer
Integer
result-source-diagnostic.dialogue-service-provider
from the AARE-apdu
if present.
This value is only returned for the first received TCAP component.
[Fragment] Example (Expect Empty End):
-- Expect Empty TCAP End within 2.5 seconds
result = tcap_api.expect_empty_end ('ssp.scp.1', 2.5)
.expect_abort [Asynchronous]
The expect_abort
method waits until a TCAP ABORT is received on the specified TCAP transaction,
with no contained Components.
- If the transaction is not registered for this instance, an error is raised.
- If any component has previously been received but not handled, an error is raised.
- If the transaction is closed with no unhandled ABORT, an error is raised.
- If the timeout expires with no message received, an error is raised.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the already initialised TCAP transaction.
seconds
Integer
Override the default TCAP timer.
(Default = configured timer for TCAP Agent).
The expect_abort
method returns the following result
structure.
Field
Type
Description
result
Table
Container for returned attributes.
.p_cause
Integer
The Protocol Cause, if present.
.u_source
Integer
The User Source, if present.
.u_info_0_octets
String
The content of the
user-information[0].encoding.octet-aligned
information element, if present.
[Fragment] Example (Expect Abort):
-- EXPECT TCAP Abort
result = tcap_api.expect_abort ('ssp.scp.1')
tester.match_pass ('Expect to receive an empty TCAP_END.', 'Received empty TCAP END on transaction ssp.scp.1, as expected.')
exp_Abort = {
p_cause = UNDEF,
u_info_0_octets = 'Plain ASCII',
u_source = 1
}
arg_Abort = tcap_api.match_abort (result.abort, exp_Abort)
.check_opcode [Pure Lua]
The check_opcode
method compares the opcode
attribute of the result
table returned by
the expect_invoke
operation, and raises a Lua error if it does not match the expected
value.
No action is performed if the opcode does match.
This method accepts the following parameters:
Field
Type
Description
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
opcode
Integer
The required opcode. This will typically be a constant from the
INAP Lua Agent API, or the MAP equivalent.
label
String
A brief string fragment to include in the error message.
[Fragment] Example (Check Opcode):
-- Abort script if the received opcode is not correct.
tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_ApplyCharging, 'INAP ApplyCharging')
.match_received_ac_bin [Synchronous]
The match_received_ac_bin
method performs a pass/fail match test of the TCAP Application Context value
received back from the first call to expect_invoke
or expect_empty_end
for a transaction.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
tcap_ac_bin
String
[Required] The expected binary TCAP Application Context string.
This is typically one of the entries in the tcap_api.APPLICATION_CONTEXT_ALIASES
table.
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_received_ac_bin
method returns nil
.
[Fragment] Example (Match Received TCAP AC):
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.match_received_ac_bin ('ssp.scp.1', result, tcap_api.APPLICATION_CONTEXT_ALIASES['camel3'])
.match_received_aare_result [Synchronous]
The match_received_aare_result
method performs a pass/fail match test of the result
attribute of the
TCAP AARE-apdu
value received back from the first call to expect_invoke
or expect_empty_end
for a transaction.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
tcap_aare_result
Integer
[Required] The expected integer value for
result
.
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_received_aare_result
method returns nil
.
[Fragment] Example (Match Received Result Parameter):
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.match_received_aare_result ('ssp.scp.1', result, 0)
.match_received_aare_result_diagnostic_user [Synchronous]
The match_received_aare_result_diagnostic_user
method performs a pass/fail match test of the
dialogue-service-user
attribute of the TCAP AARE-apdu
value received back from the first call
to expect_invoke
or expect_empty_end
for a transaction.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
tcap_aare_result_diagnostic_user
Integer
[Required] The expected integer value for
result-source-diagnostic.dialogue-service-user
.
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_received_aare_result_diagnostic_user
method returns nil
.
[Fragment] Example (Match Received User Diagnostic):
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.match_received_aare_result_diagnostic_user ('ssp.scp.1', result, 1)
.match_received_aare_result_diagnostic_provider [Synchronous]
The match_received_aare_result_diagnostic_provider
method performs a pass/fail match test of the
dialogue-service-provider
attribute of the TCAP AARE-apdu
value received back from the first call
to expect_invoke
or expect_empty_end
for a transaction.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
tcap_aare_result_diagnostic_provider
Integer
[Required] The expected integer value for
result-source-diagnostic.dialogue-service-provider
.
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_received_aare_result_diagnostic_provider
method returns nil
.
[Fragment] Example (Match Received Provider Diagnostic):
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.match_received_aare_result_diagnostic_provider ('ssp.scp.1', result, 3)
.match_received_last_component [Synchronous]
The match_received_last_component
method performs a pass/fail match test of the last_component
flag received back from a method call to expect_invoke
or expect_empty_end
for a transaction.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
result
Table
[Required] The returned
result
from the expect_invoke
method.
last_component
Boolean
[Required] Do we expect this to be (or not to be) the last component on this transaction.
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_received_last_component
method returns nil
.
[Fragment] Example (Match Last Component):
-- EXPECT Connect
result = tcap_api.expect_invoke ('ssp.scp.1')
tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_Connect, 'INAP Connect')
exp_Connect = { destinationRoutingAddress_digits = v_msisdn, destinationRoutingAddress_noa = '3' }
arg_Connect = inap_api.decode_op (result.opcode, result.parameter, nil, nil, exp_Connect)
-- Must be last component.
tcap_api.match_received_last_component ('ssp.scp.1', result, true)
.match_abort [Synchronous]
The match_abort
method compares the actual argument structure decoded from a TCAP Abort message
against an expected argument structure.
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
transaction
String
[Required] The key for the TCAP transaction, for the match pass/fail message.
abort
Table
[Required] The
abort
attribute of the result
from the expect_abort
method.
expected
Table
[Required] The expected structure of the received TCAP Abort.
For the structure of this parameter, see Tester Internals (TCAP Abort Operation).
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_abort
method returns nil
.
[Fragment] Example (Match TCAP Abort):
-- EXPECT TCAP Abort
result = tcap_api.expect_abort ('ssp.scp.1')
tester.match_pass ('Expect to receive an empty TCAP_ABORT.', 'Received TCAP ABORT on transaction ssp.scp.1, as expected.')
exp_Abort = {
p_cause = UNDEF,
u_info_0_octets = 'Plain ASCII',
u_source = 1
}
arg_Abort = tcap_api.match_abort (result.abort, exp_Abort)
.sccp_address_merge [Pure Lua]
The sccp_address_merge
method is a utility method that constructs an SCCP destination routing
address for use in the call to the initialise
method for a new outbound TCAP transaction.
It merges parameters from a local Table structure and from any supplied REST query args.
The locally-defined (inline) values take priority.
This method accepts the following parameters.
Field
Type
Description
extra_args
Table
Map of REST-supplied query args extracted from the
?
part of the REST URI.
node
String
[Required] The destination node name
scp
or srp
.
dra
Table
[Required] Inbound destination routing map.
The following parameters are processed separately.
dri
dpc
dssn
dgt_digits
dgt_noa
dgt_np
dgt_tt
For each parameter, the following logic is applied:
- If the inbound
dra
contains a value for this parameter, that value is used. - Otherwise, use the query arg value prefixed by the
node
name and a period.
.
For example, the query args value for scp.dpc
is used as the default destination point
code for sending a new TCAP BEGIN to the SCP node.
The sccp_address_merge
method returns a Table containing all of the indicated attributes for
which an explicit dra
or default extra_args
value was found.
[Fragment] Example (Match TCAP Abort):
local handler = function (args)
local scp_dra_prefs = { dgt_digits = '640003', dri = 0 }
local scp_dra = tcap_api.sccp_address_merge (args.content_json.test_details.content, 'scp', scp_dra_prefs)
tcap_api.initialise ('ssp.scp.1', tcap_api.APPLICATION_CONTEXT_ALIASES['camel3'], scp_dra)
Constants
The following TCAP constants are defined on the returned tcap_api
object.
TCAP Component and Message Types
The following component and message types are used for the sending and receiving of TCAP. Refer to the method-specific documentation. They are defined here for reference:
-- TCAP Component Type Constants.
tcap_api.CT_INVOKE = 'Invoke'
tcap_api.CT_RETURN_RESULT = 'ReturnResult'
tcap_api.CT_RETURN_ERROR = 'ReturnError'
-- TCAP Message Type Constants.
tcap_api.TYPE_BEGIN = 'BEGIN'
tcap_api.TYPE_CONTINUE = 'CONTINUE'
tcap_api.TYPE_END = 'END'
TCAP AC Aliases
The tcap_api.APPLICATION_CONTEXT_ALIASES
is a Lua table constant which provides
convenient access to some standard TCAP Application Context, for the purpose of
setting outbound TCAP Application Context via the .initialise
method, or for validating
received TCAP Application Context received in .tcap_ac_bin
from a successful return
of .expect_invoke
.
The values in this table are binary strings.
[Fragment] Example (Initialise Transaction with camel2
AC):
local scp_dra = {
dgt_digits = "049991000"
}
tcap_api.initialise (nil, 'ssp.scp.1', scp_dra, tcap_api.APPLICATION_CONTEXT_ALIASES['camel2'])
The current definition is:
-- These are the strict alias names which should be used in preference.
tcap.APPLICATION_CONTEXT_ALIASES = {
-- ETSI CS-1 SSP to SCP
cs1_ssp = "\004\000\001\001\001\000\000",
-- ETSI CS-1 IP to SCP
cs1_ip = "\004\000\001\001\001\002\000",
-- ETSI CS-2, ssf/scf AC, id-ac-cs2-ssf-scfGenericAC
cs2_ssf = "\004\000\001\001\020\003\004",
-- Application Context for camel v1.
camel1_ssf = "\004\000\000\001\000\050\000",
-- Application Context for CAMEL v2 (SSF to SCF).
camel2_ssf = "\004\000\000\001\000\050\001",
-- (SRF to SCF)
camel2_srf = "\004\000\000\001\000\052\001",
-- Application Context for CAMEL v3 (SSF to SCF).
camel3_ssf = "\004\000\000\001\021\003\004",
-- (SRF to SCF)
camel3_srf = "\004\000\000\001\020\003\00e",
-- Application Context for CAMEL v4 (SSF to SCF).
camel4_ssf = "\004\000\000\001\023\003\004",
-- (SRF to SCF)
camel4_srf = "\004\000\000\001\022\003\00e",
-- Application Context for Network Unstructured SS v2.
ussd2 = "\004\000\000\001\000\019\002",
-- Application Context for Network Unstructured MAP ATI v3.
ati3 = "\004\000\000\001\000\029\003"
}
-- And some less-strict aliases:
tcap.APPLICATION_CONTEXT_ALIASES['cs1'] = tcap.APPLICATION_CONTEXT_ALIASES['cs1_ssp']
tcap.APPLICATION_CONTEXT_ALIASES['etsi'] = tcap.APPLICATION_CONTEXT_ALIASES['cs1_ssp']
tcap.APPLICATION_CONTEXT_ALIASES['cs2'] = tcap.APPLICATION_CONTEXT_ALIASES['cs2_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel1'] = tcap.APPLICATION_CONTEXT_ALIASES['camel1_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel2'] = tcap.APPLICATION_CONTEXT_ALIASES['camel2_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel3'] = tcap.APPLICATION_CONTEXT_ALIASES['camel3_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel4'] = tcap.APPLICATION_CONTEXT_ALIASES['camel4_ssf']