Navigation :

CANCEL (Inbound)

Introduction

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

It is important to be aware that the context supplied to the cancel_send_request and cancel_expect_response methods must be an inbound INVITE context. I.e. a context returned by invite_expect_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 (Inbound) API

.cancel_expect_request [Asynchronous]

The cancel_expect_request method will request the TestSipLuaAgent to wait until an inbound SIP CANCEL Request message is received, in the context of a previously established inbound INVITE transaction/dialog 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 Request 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_request method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] An existing inbound INVITE context, as created by a previous call to `invite_expect_request`.
`extra_headers`	Array of Object	An optional list of extra headers to be tested in the CANCEL Request. 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 Request.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the CANCEL Request. 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 Request message, as returned by the “n2.http” utility module.

Example of expecting SIP CANCEL Request after provisional response:

local context = tsuo.invite_expect_request (endpoints, { ['User-Agent'] = "N-Squared LHO" })
local call_pcv = context.invite_pcv

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

-- Send Trying & Ringing.
tsuo.invite_send_response (context, 100, "Trying")
tsuo.invite_send_response (context, 180, "Ringing")
tv = match.elapsed ("Received SIP INVITE (immediate)", tv, 0)

-- The NoAnswer timer is 4 seconds.  Then we get a CANCEL.
tsuo.cancel_expect_request (context)
tsuo.cancel_send_response (context, 200, "OK")
tv = match.elapsed ("Received CANCEL (4.0s)", tv, 3.95, 4.1)

-- And now we will end the call as per the CANCEL request.
tsuo.invite_send_response (context, 487, "Request Terminated")
tsuo.invite_expect_decline_ack (context, { ['P-Charging-Vector'] = UNDEF })
tv = match.elapsed ("Completed 487 + ACK (immediate)", tv, 0.0)

.cancel_send_response [Synchronous]

The cancel_send_response method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP CANCEL Response 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:

Construct a new SIP CANCEL Response message with standard plus extra headers.
Send that message to the pre-selected remote endpoint.

The cancel_send_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context, as used for a previous call to `cancel_expect_request`.
`code`	Integer	[Required] The integer code value to send, e.g. 200.
`message`	String	[Required] The string message value to send, e.g. "OK".
`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 Response.
`.name`	String	The name of the extra header to add to the CANCEL Response.
`.value`	String	The value of the extra header to add to the CANCEL Response.

Example: See the above example for cancel_expect_request.