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
|
Attribute |
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_app_name_<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.
Component InvokeID is assigned automatically. For an Invoke
a new InvokeID is assigned consecutively
for the transaction. For ReturnResult
or ReturnError
the most recently received Invoke ID for that
operation code copied across. Attempting to send ReturnResult
or ReturnError
for an operation
code not yet recieved on that transaction will fail.
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 Invoketcap_api.CT_RETURN_RESULT - TCAP Return Resulttcap_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" })
.get_pending [Synchronous]
The get_pending
method returns any currently pending (previously received but not yet provided)
TCAP Components or TCAP Abort for the indicated transaction. If this is the first time that any
get_*
or expect_*
method has returned information, then the TCAP Application Context and result
information is also provided.
The transaction pending buffers are then cleared, subsequent calls to get_pending
will not
include these returned components.
This method accepts the following parameters:
Field | Type | Description |
---|---|---|
transaction
|
String | [Required] The key for the already initialised TCAP transaction. |
The get_pending
method returns nil
if the transaction is not known.
If the transaction is known, then the get_pending
method returns the following result
structure.
Field | Type | Description |
---|---|---|
result
|
Table | Container for returned attributes. |
.state
|
OPEN / HALF / CLOSED
|
The state of the transaction.OPEN - Sent/Received TCAP CONTINUE but not END/ABORT.HALF - Send/Received TCAP BEGIN only.CLOSED - Send/Received TCAP END/ABORT.
|
.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. |
.components
|
Array of Table |
Array of all pending received components, or nil if no pending components.
|
.type
|
Invoke / ReturnResult / ReturnError
|
The type of this received component. |
.opcode
|
Integer | The received Invoke Operation Code for this component. |
.invoke_id
|
Integer | The received Invoke ID for this component. |
.parameter
|
String | The binary-encoded ASN.1 operation parameter for this component, if present. |
.error_code
|
Integer |
The error code, if this is a ReturnError component.
|
.last_component
|
Integer |
Returned as 1 if and only if this Invoke was the last TCAP component within a TCAP END message.
|
.abort
|
Object | An object representing the decoded Abort information, if Abort was received and is pending processing. |
.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.
|
.send_failure
|
String |
Indicates that an attempt to send TCAP Components or TCAP Abort on this transaction was rejected by the SigtranApp .This string is the reason field from the received TCAP-FAIL message.
|
[Fragment] Example (Send User Abort):
local result = tcap_api.get_pending ('ssp.scp.1')
if (result.abort) then
error ("Unexpected Abort")
end
local components = result.components
if (not components or (#components ~= 1)) then
error ("Expected exactly one component.")
end
.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 error code for this error. |
.parameter
|
String | The binary-encoded ASN.1 operation parameter (if present). |
.last_component
|
Integer |
Returned as 1 if and only if this ReturnError 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 |
---|---|---|
defaults
|
Table | [Required] Default destination routing parameter values. |
dra
|
Table | [Required] Specific destination routing parameters. |
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 corresponding value from the defaults map.
A new table is returned containing the map of specific values, with defaults applied.
[Fragment] Example (Initialise TCAP BEGIN DRA):
local args = ...
local scp_dra_defaults = { dgt_digits = '640003', dri = 0 }
local scp_dra = tcap_api.sccp_address_merge (scp_dra_defaults, args.content_json.scp_dest_dra)
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:
-- Agent Key (for n2svcd.progress)
tcap.AGENT_KEY = 'tcap'
-- Transaction state Constants
tcap.STATE_OPEN = 'OPEN'
tcap.STATE_HALF_OPEN = 'HALF'
tcap.STATE_CLOSED = 'CLOSED'
-- 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']