Termination (Attempt)

Introduction

An SCP Lua script may request that the call be terminated to a B-Party by sending INAP Continue or INAP Connect on the SSP transaction using RequestReportBCSMEvent to arm for the Answer, NoAnswer, Busy, RouteSelectFailure, and Abandon event detection points.

The Disconnect EDPs are not armed. There will be no ApplyCharging, nor CallInformationRequest.

The use of FurnishChargingInformation and/or SendChargingInformation is optional.

If an SRF is currently open then a prior DisconnectForwardConnection will be sent on the SSP transaction, and any external SRF transaction will be ended according to the applicable SRF configuration.

The processing will suspend until one of the armed EDPs is returned, or a guard timer expires. If the call is Answered or Abandoned or timed-out then no further telephony methods are permitted.

If the call result is Busy, NoAnswer, or RouteSelectFailure, then the service logic may carry on and attempt other telephony actions.

The LhoScpLuaService Termination (Attempt) API

.termination_attempt

This method provides full access to the Termination (Attempt) mechanism and is provided for use by custom service developers. In the majority of scenarios, one of the subsequently-described convenience methods should be sufficient and preferable. However, this full-featured alternative is provided for use by complex or non-standard services.

This method sends INAP Connect if the .address_digits is present, or INAP Continue if the address digits are not specified.

This method takes a single details parameter which is a Lua table with the following structure:

The termination_attempt method returns a structure indicating the result of the termination attempt.

Example (connect to called party with a prefix, no FCI, no SCI, redirection, not monitored/charged):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

local result = scp_api.termination_attempt ({
    address_digits = '1703' .. scp_call.normalised_called_party,
    redirecting_digits = '00889001234',
    redirection_info = { reason = 4, counter = 1 }
})

if (result.answered) then
    n2svcd.notice ("CALL ANSWERED = YES")

else
    if (result.controlled) then
        n2svcd.notice ('Controlled after EDP Name = %s', result.scp.edp_name)
        scp_api.release_call (5)

    else
        n2svcd.notice ('Control Lost after EDP Name = %s', result.scp.edp_name)
    end
end

return 

.continue_attempt

This is a convenience method for calling termination_attempt () which specifies the most commonly used parameters but no address digits, meaning that INAP Continue will be used.

The continue_attempt method takes the following arguments:

The continue_attempt method returns the same result structure as termination_attempt.

Example (continue with 30 second NoAnswer timer, not monitored/charged):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

local result = scp_api.continue_attempt (30)

-- If result.controlled = true then we are still in control of the call.
if (result.controlled) then
    n2svcd.notice ('Controlled after EDP Name = %s', result.scp.edp_name)
    scp_api.release_call (5)

else
    n2svcd.notice ('Control Lost after EDP Name = %s', result.scp.edp_name)
end

return 

.connect_attempt

This is a convenience method for calling termination_attempt () which specifies the most commonly used parameters including address digits, meaning that INAP Connect will be used.

The connect_attempt method takes the following arguments:

The connect_attempt method returns the same result structure as termination_attempt.

Example (connect to called party with a prefix, default NoAnswer, with FCI, not monitored/charged):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...
local called_party = '1703' .. scp_call.normalised_called_party

-- Binary in Lua is decimal-specified.
local fci_bin = '\01\02\03\04\255\238\221'

local result = scp_api.connect_attempt (called_party, nil, fci_bin)
if (result.answered) then
    n2svcd.notice ("CALL ANSWERED = YES")
end

-- This will automatically release the call (if needed) with default release cause.
return 

Example (connect to called party with a prefix, default NoAnswer, no FCI/SCI, B-Party beep with explicit ID, not monitored/charged):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...
local called_party = '1703' .. scp_call.normalised_called_party

local result = scp_api.connect_attempt (called_party, nil, nil, nil, { id = 1300 })
if (result.answered) then
    n2svcd.notice ("CALL ANSWERED = YES")
end

-- This will automatically release the call (if needed) with default release cause.
return 

.connect_monitored

This is a convenience method for calling termination_attempt () which sets the monitored Termination type flag, and allows for the setting of some commonly used parameters including address digits, meaning that INAP Connect will be used.

Setting the monitored flag means that the service logic will continue to be in the call control path for the duration of the talk time, and will receive monitor notification events after the successful ActivityTest/ActivityTestResult performs for each monitor interval.

When the connect_monitored () method (or a direct call to the termination_attempt ()) returns answered = true, the service logic is obliged to repeatedly call the monitor_check () method until the returned result no longer indicates that the call is being monitored.

The connect_monitored method takes the following arguments:

The connect_monitored method returns the same result structure as termination_attempt.

Example (monitored connect to a fixed number, 30 second monitor intervals, 600 seconds maximum call duration):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

local called_party = '07119222'

local result = scp_api.connect_monitored (called_party, nil, 30, 600)
if (result.answered) then
    n2svcd.notice ("CALL ANSWERED = YES")

    repeat
        result = scp_api.monitor_check ()
    until (not result.monitored)
end

-- This will automatically release the call (if needed) with default release cause.
return

.monitor_check [Asynchronous]

This monitor check method must be called by any script using monitored calls, after a monitored call attempt has been answered.

• A monitored call attempt is one which sets the monitored attribute in termination_attempt directly or via connect_monitored.
• An answered call attempt is one where the answered attribute is returned true.

The logic must repeat calls to result = scp_api.monitor_check until not result.monitored.

The script may perform other protocol actions prior to each invocation of monitor_check. These may include asynchronous actions, e.g. Diameter client or REST client actions via the corresponding agent.

See also the subsequent sections related to follow-on telephony actions, and to service-initiated hangup during monitored calls for further discussion of how the monitor_check method interacts with other telephony methods.

The monitor_check method takes no arguments.

The monitor_check method returns a table with the following structure:

If the call successfully completes the entire monitoring interval with both legs still connected, then the return value is:

• { controlled = true, monitored = true, monitored_secs = <integer> }

If the B-Leg is terminated but the A-Leg is still available, then follow-on telephony is possible, and the return is:

• { controlled = true, monitored = false, monitored_secs is not present, other fields will be present }

If the A-Leg is terminated, then the B-Leg will also be terminated and the return is:

• { controlled = false, monitored = false, monitored_secs is not present, other fields will be present }

.connect_charged

This is a convenience method for calling termination_attempt () which sets the charged Termination type flag, and allows for the setting of some commonly used parameters including address digits, meaning that INAP Connect will be used.

Setting the charged flag means that the service logic will continue to be in the call control path for the duration of the talk time, and will be requested to perform subsequent grants in relation to the ApplyCharging/ApplyChargingReport which are performed for each charge grant period.

When the connect_monitored () method (or a direct call to the termination_attempt ()) returns answered = true, the service logic is obliged to repeatedly call the charge_check () method until the returned result no longer indicates that the call is being charged. See the description below of charge_check () for the use of charge_extend () and charge_deny () after charge_check returns a result with charged = true.

The connect_charged method takes the following arguments:

The connect_charged method returns the same result structure as termination_attempt.

Example (charged connect to the original number, 60 second initial grant):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

local called_party = scp_call.normalised_called_party

local result = scp_api.connect_charged (called_party, nil, 60)
if (result.answered) then
    n2svcd.notice ("CALL ANSWERED = YES")

    local num_extends = 0

    while (true) do
        result = scp_api.charge_check ()

        if (not result.charged) then break end

        num_extends = num_extends + 1

        -- Allow two open-ended extensions.
        if (num_extends < 3) then
            scp_api.charge_extend (60)

        -- The final extension we set the release_at_expiry flag, the call will be ended by us.
        else
            scp_api.charge_extend (60, true)
        end
    end
end

-- This will automatically release the call (if needed) with default release cause.
return

.charge_check [Asynchronous]

This charge check method must be called by any script using charged calls, after the charged call attempt has initially been answered, and then subsequently after each call to charge_extend.

• A charged call attempt is one which sets the charged attribute in termination_attempt directly or via connect_charged.
• An answered call attempt is one where the answered attribute is returned true.

The script may perform other protocol actions prior to each invocation of charge_check. These may include asynchronous actions, e.g. Diameter client or REST client actions via the corresponding agent.

See also the subsequent sections related to follow-on telephony actions, and to service-initiated hangup during monitored calls for further discussion of how the charge_check method interacts with other telephony methods.

The charge_check method takes no arguments.

The charge_check method returns a table with the following structure:

If the call successfully completes the total granted time with both legs still connected, then the return value is:

• { controlled = true, charged = true, talk_ds_total = <integer> }

If the B-Leg is terminated but the A-Leg is still available, then follow-on telephony is possible, and the return is:

• { controlled = true, charged = false, talk_ds_total = <integer>, other fields will be present }

If the A-Leg is terminated, then the B-Leg will also be terminated and the return is:

• { controlled = false, charged = false, talk_ds_total = <integer>, other fields will be present }

Note: In some exception cases,

.charge_extend [Synchronous]

This charge grant method must be called by any script using charged calls, whenever the charge_check method returns result.charged = true and the service decides to grant a subsequent talk-time extension.

If the service does not wish to grant a talk-time extension, it should use the charge_deny () method instead.

The service may know in advance that this is to be the final permitted extension in which case it may use the release_at_expiry flag to request the service to automatically end the call (both legs) when this grant is consumed.

The script may perform other protocol actions prior to each invocation of charge_extend. These may include asynchronous actions, e.g. Diameter client or REST client actions via the corresponding agent.

See also the subsequent sections related to follow-on telephony actions, and to service-initiated hangup during monitored calls for further discussion of how the charge_extend method interacts with other telephony methods.

The charge_extend method takes the following arguments:

The charge_extend method returns true.

.charge_deny [Synchronous]

This charge grant method must be called by any script using charged calls, whenever the charge_check method returns result.charged = true and the service decides NOT to grant a subsequent talk-time extension.

The script may perform other protocol actions prior to the invocation of charge_deny. These may include asynchronous actions, e.g. Diameter client or REST client actions via the corresponding agent.

The call be torn-down (both legs).

NOTE: After calling charge_deny, the service logic must return and call charge_check one final time.

In this final case, charge_check is guaranteed to return charged = false to indicate that the call is no longer under charge control.

NOTE: Due to race conditions, it is possible that the A-Party or B-Party may hang-up in the background, prior to the charge deny operation being executed. Hence the returned value of the final call to charge_check may represent either:

• A-Party Hang-Up, call is no longer controlled (the deny did not apply).
• B-Party Hang-Up, call is still controlled (the deny did not apply).
• Charge Deny Hang-Up, call is no longer controlled.

The charge_deny method takes the following arguments:

The charge_deny method returns true.

Limited Telephony within Monitor/Charge

The termination_attempt, monitor_check, and charge_check methods can return:

• monitored = true or charged = true (which will also have)
• controlled = true

This is a limited form of telephony control. The service may in theory invoke:

• tcap_abort
• Lua error
• Lua return

All of these will result in an unclean shutdown.

Follow-On Telephony after Monitor/Charge

The monitor_check and charge_check methods can return:

• monitored = false or charged = false (but with)
• controlled = true

This occurs when the B-Leg of the monitored/charged call ends, but the A-Leg is still available.

At this time, all of the standard telephony methods are now available, including follow-on interaction and/or B-Leg termination.

Slow Service Logic

All service logic must respond promptly, within the service_logic_ms timer (default = 2500 milliseconds) configured for the LhoScpApp.

If the service logic response is not received within this time whenever it is expected, then the LhoScpApp will assume that call control has been abandoned, and will terminate the in-progress call with the loss of all legs.