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 toinvite_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.
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 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.