Navigation :

BYE (Outbound)

Introduction

These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAC role for an outbound BYE transaction, sending an outbound SIP BYE Request in the context of a previously established inbound or outbound SIP INVITE transaction/dialog for which a dialog has been confirmed, i.e. for which the remote URI tag is known.

It is important to be aware that the context supplied to the bye_send_request and bye_expect_response methods must be an INVITE context. It may be either:

An outbound INVITE context created by invite_context and used in a call to invite_send_request, or
An inbound INVITE context returned by invite_expect_request.

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

BYE (Outbound) API

.bye_send_request [Synchronous]

The bye_send_request method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP BYE 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 BYE Request message with standard plus extra headers.
The P-Charging-Vector from the INVITE will be included.
SDP Content is not supported in outbound BYE Request.
ISUP Content is added, if it was requested.
Send that message to the pre-selected remote endpoint.

The bye_send_request method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] An existing INVITE context, as created by `invite_context` and previously used in a call to `invite_send_request` or else as was created by a call to `invite_expect_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 BYE Request.
`.value`	String	The value of the extra header to add to the BYE Request.
`options`	Object	Additional override/customisation behavior for this test message. (Default = see defaults for individual options).
`.isup_bytes`	Byte String	Optional ISUP bytes to be included in the BYE Request. If ISUP is included then the `Content-Type` header will be set to `tsuo.ISUP_CONTENT_TYPE` (Default = do not include ISUP content).

The bye_send_request method returns nil.

Example fragment sending BYE with ISUP:

-- Send BYE from our side.  With ISUP REL.
local isup_rel_bytes = utils.hex_to_bin ('0d 02 00 02 8a 90')
local isup_rlc_bytes = nil

tsuo.bye_send_request (context, {
    { name = 'Route', value = '<sip:p1.example.com;lr>' },
    { name = 'Route', value = '<sip:p2.domain.com;lr>' }
}, { isup_bytes = isup_rel_bytes })
tv = match.elapsed ("Send BYE (1.0s)", tv, 1.0)

-- Expect immediate aknowledgement with ISUP RLC.
tsuo.bye_expect_response (context, 200, "OK", nil, { isup_bytes = isup_rlc_bytes })
tv = match.elapsed ("BYE Confirmed (immediate)", tv, 0.0)

.bye_expect_response [Asynchronous]

The bye_expect_response method will request the TestSipLuaAgent to wait until an inbound SIP BYE 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 BYE Response message.

A series of standard match tests will be performed on the received message headers - To/From/Via/etc.
No SDP Content is permitted for inbound BYE Response.
The expected ISUP Content and Content-Type is verified, or confirmed to be absent.

The bye_expect_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context as used in a previous call to `bye_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 BYE 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 BYE Response.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the BYE 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".
`options`	Object	Additional override/customisation behavior for this test message. (Default = see defaults for individual options).
`.isup_bytes`	Byte String	Optional ISUP bytes which we expect to receive in the BYE Response. If ISUP is expected then the `Content-Type` header value (top-level only) must contain `application/ISUP`. If ISUP is not expected, then the Content must be empty and the Content-Type header is ignored (since SDP is not permitted). (Default = expect to receive no ISUP content).

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

Example: See the above example for bye_send_request.