Navigation :

Service Context

The service context is a Lua object that holds all information about the internal state of a network session as it is processed by the N2IWF. It is populated both by its own service logic (including OCS responses) and the protocol handler
library. Data may also be inserted into the service context by the protocol handler as required for call handling.

Attributes

The service context should only be modified using its methods. Direct access to its attributes is not recommended.

Methods

Note that as the service context is a Lua object, its methods should be accessed using the colon operator, e.g.:

service_context:get_by_dot ("key")

Getter / Setter Functions

Many service context functions operate as both getters and setters for network session information.

When called without parameters, the current value of the appropriate element is returned, if any.

They may be alternatively be provided with a single parameter in order to set the appropriate element.

Function	Parameter and Return Type	Description
`subscriber_msisdn`	String	The subscriber’s MSISDN.
`subscriber_imsi`	String	The subscriber’s IMSI.
`subscriber_uri`	String	The subscriber’s URI.
`service_identifier`	String	The Service-Identifier, if any, for the current session.
`rating_group`	String	The Rating-Group, if any, for the current session.
`service_context_id`	String	The Service-Context-Id for the current session.
`units_total`	Integer	The total units used for the network session.
`units_last`	Integer	The units used for the current reservation.
`loop_counter`	Integer	The current loop number.
`loop_requested`	Boolean	Whether a loop has been requested during this loop.
`network_ongoing`	Boolean	Whether the current action handling for the network session is ongoing.
`rating_ongoing`	Boolean	Whether the rating session is ongoing.
`controlled`	Boolean	Whether the network session is still controllable.
`final`	Boolean	Whether the last grant is the final one for this rating session.
`bypass`	Boolean	Whether the rating session has been bypassed by a pre-rating action.
`balances`	Table	The current internal balance information from the OCS.
`destination_ocs`	String	The current session destination for presentation to the OCS.
`destination_net`	String	The current session destination for the network response.

Getter Only Functions

Many service context functions act solely as getters for network session information.

These functions are always called without parameters to return the current value of the appropriate element, if any.

Function	Return Type	Description
`subscriber_identifiers`	Table	All subscriber identifiers in a table, keyed as defined in the N2IWF core. Possible keys are: `iwf_core.iwf_states.MSISDN` - the subscriber MSISDN `iwf_core.iwf_states.IMSI` - the subscriber IMSI `iwf_core.iwf_states.URI` - the subscriber URI
`last_gsu`	Integer	The last granted units in the rating session.
`grace_units`	Integer, Integer	The allowed and used units from the last grace handling.
`grace`	Boolean	Whether the network session is currently being handled in grace.
`get_edr_manager`	Object	Returns the EDR manager for the network session.
`originating`	Boolean	Whether the direction of the network session is considered to be originating by the network protocol handler.
`forwarding`	Boolean	Whether the direction of the network session is considered to be forwarding by the network protocol handler.
`terminating`	Boolean	Whether the direction of the network session is considered to be terminating by the network protocol handler.
`cug_match_found`	Boolean	Whether the last N2CUG external action found a match.
`cug_match_long`	String	The long number from the last N2CUG external action match, if any.
`cug_match_short`	String	The short code from the last N2CUG external action match, if any.
`cug_match_display_caller_sc`	Boolean	Whether the match from the last N2CUG external action allows caller short code display.
`cug_user_found`	Boolean	Whether the last N2CUG external action found a user.
`cug_user_long`	String	The long number from the last N2CUG external action user, if any.
`cug_user_is_ln`	Boolean	Whether the user from the last N2CUG external action was located by long number.

state / last_state

These functions return the current or the last N2IWF state, as defined in the N2IWF core. Possible values are:

iwf_core.iwf_states.NEW - new network session received
iwf_core.iwf_states.CONFIG - parse configuration
iwf_core.iwf_states.INIT_IWF - initialise N2IWF state
iwf_core.iwf_states.INIT_PROTO - initialise protocol handler
iwf_core.iwf_states.INIT_VARS - populate variables
iwf_core.iwf_states.EXT_ACTIONS - external action processing
iwf_core.iwf_states.REINIT_VARS - populate variables
iwf_core.iwf_states.PRE_RATING - pre-rating
iwf_core.iwf_states.RATING_INIT - initial rating interrogation
iwf_core.iwf_states.RATING_UPDATE - interim rating interrogation
iwf_core.iwf_states.RATING_TERM - final rating interrogation
iwf_core.iwf_states.POST_RATING - post-rating
iwf_core.iwf_states.ERROR - error handling

States are numeric values in the order above so can be directly compared.

The state function may be provided a single enumerated parameter in order to set the N2IWF internal state. This should not be done without prior consultation with N-Squared.

looping

This function may be called in order to prepare the service context for a loop. It will clear out any existing rating session information in readiness for another to be potentially created.

This function takes no parameters and returns nothing.

get_by_dot

This function behaves identically to the N2SVCD utility function get_by_dot but operates solely on the context_fields table within the service context and the service context additional selectors.

This function takes three positional parameters:

The table to examine. This is ignored for N2IWF service context additional selectors; the service context is always used for these.
The (possibly dot-notated) key to retrieve.
The comparison value being examined.

open_rating_session / continue_rating_session / finish_rating_session

These functions open, continue, or complete a rating session to the OCS.

Note that a service context can only have one rating session at any time. An open session must be completed before another can be started.

The open_rating_session function takes a required parameter giving the hook manager instance in use for the network session.

The continue_rating_session and finish_rating_session functions take an optional integer parameter for the used units from the last reservation, defaulting to 0 if not provided.

These functions return nothing.

add_used_amount

This function is used to add used units to the rating session in progress.

It takes an integer parameter representing the new units used. This is added to the running total for the network session, and replaces the current used units for this reservation. Accordingly, it should only be called once per reservation.

This function returns the new total amount of units used.

clear_units

This function will clear the current rating session total and last-granted units.

This function takes no parameters and returns nothing.

rating_session

This function returns the current rating session, if any.

This function takes no parameters.

grace_start / grace_end

These functions start or end grace handling on the network.

When starting grace, the units to allow (depending on the input protocol) must be provided as an integer.

When ending grace, the units used (depending on the input protocol) must be provided as an integer.

These functions return nothing.

update_var

This function can be used to update a variable. It will also notify the EDR manager of the change if the variable is configured to be written to an EDR or an EDR key is provided. Note that this function ignores the mutable value of the variable’s configuration.

This function takes three positional parameters:

The name of the variable, as configured in the N2SVCD LogicApp configuration.
The new value of the variable. If nil, this will clear the variable.
The EDR key to use to write this variable to an EDR. Overrides any configured EDR key for this variable.

This function returns nothing.

add_balance

This function can be used to add or update balance information from the OCS.

This function takes four positional parameters:

The balance name.
The delta to the balance. If not provided, defaults to 0.
The exponent to apply. If not provided, defaults to 0.
The OCS value for the currency translation to apply for balance presentation. If not present, currency translation will not apply.

This function returns the new value of the balance after the exponent and any previous balance value have been taken into account.

set_direction

This function is used to set the direction of the network session, overriding the decision made by the
network protocol handler.

It takes an enumerated parameter from the N2IWF core. Possible values are:

iwf_core.directions.ORIGINATING - an originating network session
iwf_core.directions.FORWARDING - a forwarding network session
iwf_core.directions.TERMINATING - a terminating network session

This function returns nothing.

set_cug_details

This function is used to store the results of a N2CUG external action. of the network session, overwriting the last results, if any.

This function takes a single argument, a table expected to be in the format of a normal N2CUG lookup result.

This function returns nothing.

set_hook_manager / get_hook_manager

These functions either set or get the hook manager in use for the network session.