Navigation :

re-INVITE (Outbound)

Introduction

These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAC role for an outbound re-INVITE transaction, sending an outbound SIP re-INVITE 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 reinvite_send_request and reinvite_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 re-INVITE message does not have its own (non-INVITE) context. It must exist within the context of the ongoing INVITE dialog.

re-INVITE (Outbound) API

.reinvite_send_request [Synchronous]

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

The reinvite_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`.
`sdp_content`	String	Optional SDP content (presumably an SDP Offer) to include in the SIP re-INVITE Request. (Default = do not include SDP in the re-INVITE Request Content).
`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 re-INVITE Request.
`.value`	String	The value of the extra header to add to the re-INVITE Request.

The reinvite_send_request method returns nil.

Example fragment sending re-INVITE without SDP:

-- Now we send AT ping (no SDP).
tsuo.reinvite_send_request (context, nil, nil)
tsuo.reinvite_expect_response (context, 200, "OK", nil)
tsuo.reinvite_send_2xx_ack (context)

.reinvite_expect_response [Asynchronous]

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

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

The reinvite_expect_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context as used in a previous call to `reinvite_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 re-INVITE 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 re-INVITE Response.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the re-INVITE 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).
`.ack_response`	Boolean	When set to a "true" value, this flag requests an unusual exception case. Specifically it indicates that the returned `CSeq` should be for the `ACK` method not `INVITE`. This is used in tests where we expect our re-INVITE `ACK` to be rejected, e.g. with a "481 Call/Transaction Does Not Exist". (Default = the returned CSeq is for the INVITE method).
`.sdp_media`	`tsuo.SDP_MEDIA_*`	If specified, this must be one of the pre-defined SDP Media Constants. The value `tsuo.SDP_MEDIA_NONE` means "No SDP should be present" in the received message. (Default = `tsuo.SDP_MEDIA_NONE` no SDP should be present).
`.sdp_suspended`	`tsuo.SDP_SUS_*`	If specified, this must be one of the pre-defined SDP Suspended Constants. This value is relevant only if SDP media is expected. (Default = `tsuo.SDP_SUS_NONE` the non-suspended (i.e. active) variant is sent/expected).
`.sdp_direction`	`tsuo.SDP_DIR_*`	If specified, this must be one of the pre-defined SDP Direction Constants. This value is relevant only if SDP media is expected and SDP suspended is not-suspended. (Default = `tsuo.SDP_DIR_SENDRECV` all non-suspended media streams are bi-directional).

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

Example: Normal use of reinvite_send_request.

tsuo.reinvite_send_request (context, nil, nil)
tv = match.elapsed ("Re-INVITE 2A (sent) for activity test (immediate)", tv, 0.0)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tsuo.reinvite_send_2xx_ack (context, {})
tv = match.elapsed ("Re-INVITE 2A (sent) for activity test ACK (immediate)", tv, 0.0)

Example: Special case for re-INVITE where the transaction times out and our ACK is eventually rejected.

tsuo.reinvite_send_request (context, nil, nil)
tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1A (OK but not yet ACK) for activity test (immediate)", tv, 0.0)

-- But we interrupt the ACK with our BYE.
-- This exposes Issue #SIP-14985

-- Send BYE from our side.
tsuo.bye_send_request (context)
tsuo.bye_expect_response (context, 200, "OK")
tv = match.elapsed ("BYE Confirmed (immediate)", tv, 0.0)

-- Wait for the retries to finish.
tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1B (OK but not yet ACK) for activity test (0.5s)", tv, 0.48, 0.52)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1C (OK but not yet ACK) for activity test (1.0s)", tv, 0.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1D (OK but not yet ACK) for activity test (2.0s)", tv, 1.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1E (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1F (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1G (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1H (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1I (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

tsuo.reinvite_expect_response (context, 200, "OK", nil)
tv = match.elapsed ("Re-INVITE 1J (OK but not yet ACK) for activity test (4.0s)", tv, 3.99)

-- Check that NO payload arrives in the next 5 seconds.
tsuo.expect_no_payload (context.call_id, 5)
tv = match.elapsed ("Re-INVITE no more retries (5.0s)", tv, 5.0)

-- This second one will now get bounced back as 481 not known, because the previous one shut down the registration.
tsuo.reinvite_send_2xx_ack (context, {})
tsuo.reinvite_expect_response (context, 481, "Call/Transaction Does Not Exist", nil, { ack_response = true })
tv = match.elapsed ("Re-INVITE 1B (sent and 481) for activity test ACK (immediate)", tv, 0.0)

.reinvite_send_2xx_ack [Synchronous]

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

The ACK is suitable for acknowledging a re-INVITE 2XX Response which was previously received using the reinvite_expect_response method.

This ACK is not suitable for acknowledging a re-INVITE 300-699 Response. There is currently no mechanism for acknowledging a non-success result from a re-INVITE. This is a missing feature in the test framework.

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 re-INVITE ACK for 2XX Request message with standard plus extra headers.
SDP Content is not supported in outbound re-INVITE ACK Request.
ISUP Content is not supported in outbound re-INVITE ACK Request.
Send that message to the pre-selected remote endpoint.

The reinvite_send_2xx_ack method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context as used in a previous call to `reinvite_expect_response`.
`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 re-INVITE ACK Request.
`.value`	String	The value of the extra header to add to the re-INVITE ACK Request.

The reinvite_send_2xx_ack method returns nil.

Example: See the above example for reinvite_send_request.