Navigation :

CANCEL (Outbound)

Introduction

These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAC role for an outbound CANCEL transaction, sending an outbound SIP CANCEL Request in the context of a previously established outbound SIP INVITE transaction/dialog for which a final INVITE Response has not yet been received.

It is important to be aware that the context supplied to the cancel_send_request and cancel_expect_response methods must be an outbound INVITE context. I.e. a context created by invite_context and used in a call to invite_send_request.

i.e. The CANCEL message does not have its own (non-INVITE) context. It must exist within the context of the ongoing INVITE dialog.

CANCEL (Outbound) API

.cancel_send_request [Synchronous]

The cancel_send_request method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP CANCEL Request is sent to the previously determined remote endpoint IP and port address.

Control will return immediately to the Lua script. There is no wait for any confirmation from the TestSipApp. If there is a problem sending then the TestSipAgent will subsequently send us a TEST-SIP-FAIL message which will be detected if and when any subsequent SIP messaging is performed by the test script.

The method will:

Assign a new, unique Via Branch.
Claim the current local CSeq within the INVITE context and increment it.
Construct a new SIP CANCEL Request message with standard plus extra headers.
ISUP Content is not supported in outbound CANCEL Request.
SDP Content is not supported in outbound CANCEL Request.
Send that message to the pre-selected remote endpoint.

The cancel_send_request method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] An existing outbound INVITE context, as created by `invite_context` and previously used in a call to `invite_send_request`.
`extra_headers`	Array of Object	An optional list of extra headers. Each object in the array must have a `name` and a `value`. A header name may appear more than once in this array to support repeated headers in the Request.
`.name`	String	The name of the extra header to add to the CANCEL Request.
`.value`	String	The value of the extra header to add to the CANCEL Request.

The cancel_send_request method returns nil.

Example of sending SIP CANCEL Request after provisional response:

local n2svcd = require "n2.n2svcd"
local utils = require "n2.utils"
local match = require "n2.n2svcd.tester.match"
local manage = require "n2.n2svcd.tester.manage"
local edr_file_agent = require "n2.n2svcd.edr_file_agent"
local tsuo = require "n2.n2svcd.tester.test_sip_agent"

local args = ...

-- Start timer for elapsed checking.
local tv = match.elapsed ()

-- Checkpoint stats for "Logic" and "LHO" apps.
local stats_Logic = match.stats ('Logic')
local stats_LHO = match.stats ('LHO')


-- Static for our call.
local endpoints = tsuo.default_endpoints ({ local_rtp_port = 3668 })
local calling_party = '665566'
local called_party = '4000'

-- Get a SIP outcall context from our helper library.
local context = tsuo.invite_context (endpoints, calling_party, called_party, {
    prack_supported = true,
    contact_sip_instance = '"<urn:uuid:27b843f9-d300-49fb-b108-fff03a6369e3>"',
    contact_expires = '3600'
})

-- Construct the SDP
local sdp_offer = tsuo.sdp_offer (context, tsuo.SDP_LINPHONE)

-- Construct and Send INVITE Request.
tsuo.invite_send_request (context, sdp_offer, { { name = 'Prefer-EM', value = '1' } })

-- Expect Trying & Ringing.
tsuo.invite_expect_response (context, 100, "Trying", { ['User-Agent'] = "N-Squared LHO" })
tsuo.invite_expect_response (context, 180, "Ringing")
match.elapsed ("Ring Notification (immediate)", tv, 0.0)

tsuo.invite_expect_response (context, 180, "Ringing")
match.elapsed ("Ring Re-send (0.5s)", tv, 0.49)

tsuo.invite_expect_response (context, 180, "Ringing")
tv = match.elapsed ("Ring Re-send (1.5s)", tv, 1.49)

-- PRACK the 180.  Have to do this before the 183 can be sent.
tsuo.invite_send_prack (context)
tsuo.invite_expect_prack_response (context, 200, "OK")
tv = match.elapsed ("PRACK 180 completed (immediate)", tv, 0.0)

-- Expect INVITE Answer Response (200 OK) after 2 seconds.
tsuo.invite_expect_response (context, 183, "Session Progress")
tv = match.elapsed ("Early Media (2.0s)", tv, 1.99)

-- PRACK the 183.
tsuo.invite_send_prack (context)
tsuo.invite_expect_prack_response (context, 200, "OK")
tv = match.elapsed ("PRACK 183 completed (immediate)", tv, 0.0)

-- Ack the 200.
-- tsuo.invite_send_2xx_ack (context)

-- Voice call in progress.
-- The "Goodbye" announcement is 0.65 seconds and it is played twice before hangup.
-- We interrupt after 1.0 seconds, so roughly mid-way through the second "Goodbye".
--
n2svcd.wait (1.0)

-- NOTE: We can use CANCEL in this case because we haven't received a final response for the INVITE.
--
-- Send CANCEL from our side.
tsuo.cancel_send_request (context)
tv = match.elapsed ("Send CANCEL (1.0s)", tv, 1.0)

-- Expect immediate acknowledgement.
tsuo.cancel_expect_response (context, 200, "OK")
tv = match.elapsed ("CANCEL Confirmed (immediate)", tv, 0.0)

-- Expect immediate termination on the INVITE.
tsuo.invite_expect_response (context, 487, "Request Terminated")
tv = match.elapsed ("INVITE Terminated (immediate)", tv, 0.0)

-- Construct and Send ACK Request suitable for the 487 response we received.
tsuo.invite_send_decline_ack (context)

.cancel_expect_response [Asynchronous]

The cancel_expect_response method will request the TestSipLuaAgent to wait until an inbound SIP CANCEL Response message is received, in the context of a previously established transaction which belongs to this Lua script instance.

The agent will wait up until the expect_secs configured value for a SIP message to arrive. An error will be raised if no message is received in this time. An error will be raised if the received message is not a SIP Reponse, or if the received SIP message is not a CANCEL Response message.

A series of standard match tests will be performed on the received message headers - To/From/Via/etc.
The received Content must be empty.
The received Content-Type is ignored.

The cancel_expect_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context as used in a previous call to `cancel_send_request`.
`code`	Integer	[Required] The expected integer code value, e.g. 200.
`message`	String	[Required] The expected string message value, e.g. "OK".
`extra_headers`	Array of Object	An optional list of extra headers to be tested in the CANCEL Response. Each object in the array must have a `name` and a `value`. If a header is expected to appear more than once, then `value` may be an Array of String.
`.name`	String	The name of the extra header to test for in the CANCEL Response.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the CANCEL Response. The value `UNDEF` means "test that this header is not present". A String value means "test" that the first header instance has this value. An Array of String value means "test that the header exists N times with these values".

This method returns the decoded SIP CANCEL Response message, as returned by the “n2.http” utility module.

Example: See the above example for cancel_send_request.