INVITE (Outbound)
Introduction
These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAC role for
an outbound INVITE transaction, sending an outbound SIP INVITE Request to begin a call/dialog,
which always begins with invite_send_request
.
Within this dialog there may subsequently be additional in-dialog transactions such as CANCEL (Outbound),
BYE (Inbound or Outbound) and re-INVITE (Inbound or Outbound). All of these in-dialog transactions
will use the same INVITE context as is used for the invite_send_request
.
INVITE (Outbound) API
.invite_send_request [Synchronous]
The invite_send_request
method sends a TEST-SIP-SEND
message to the TestSipApp to request that
an outbound SIP 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 INVITE Request message with standard plus extra headers.
- SDP Content may be present in the outbound INVITE Request.
- ISUP Content may be present in the outbound INVITE Request.
- Send that message to the pre-selected remote endpoint.
The invite_send_request
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] An existing INVITE context, as created by invite_context .
|
sdp_content
|
String |
Optional SDP content (presumably an SDP Offer) to include in the SIP INVITE Request. (Default = do not include SDP in the 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 INVITE Request. |
.value
|
String | The value of the extra header to add to the INVITE 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 invite_send_request
method returns nil
.
Example fragment sending INVITE:
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 = ...
-- Static for our call.
local endpoints = tsuo.default_endpoints ({ local_rtp_port = 3668 })
local calling_party = '666666'
local called_party = '407000'
-- Get a SIP outcall context from our helper library.
local context = tsuo.invite_context (endpoints, calling_party, called_party)
-- Construct the SDP
local sdp_offer = tsuo.sdp_offer (context, tsuo.SDP_LINPHONE)
-- Start timer for elapsed checking.
local tv = match.elapsed ()
-- Construct and Send INVITE Request.
tsuo.invite_send_request (context, sdp_offer, {
{ name = 'P-Charging-Vector', value = 'PCV #1' }
})
-- Expect Trying automatically. No ringing.
tsuo.invite_expect_response (context, 100, "Trying", { ['User-Agent'] = "N-Squared LHO" })
-- Then a Progress to connect us to the RTP for the announcement.
tsuo.invite_expect_response (context, 183, "Session Progress", {}, { sdp_media = tsuo.SDP_MEDIA_LINPHONE_U })
tv = match.elapsed ("Early Media (immediate)", tv, 0.0)
-- Then there is a pre-call announcement (internal).
-- Then a Progress to suspend us from the RTP after the announcement.
tsuo.invite_expect_response (context, 183, "Session Progress", {}, { sdp_media = tsuo.SDP_MEDIA_NT_LINPHONE_U, sdp_suspended = tsuo.SDP_SUS_INACTIVE })
tv = match.elapsed ("Early Media suspend after announcement (0.65s)", tv, 0.65)
-- Then a 180 Ringing passthrough for the new B-Leg.
tsuo.invite_expect_response (context, 180, "Ringing")
tv = match.elapsed ("180 Ringing (immediate)", tv, 0.0)
-- Then a 200 OK for the new B-Leg.
tsuo.invite_expect_response (context, 200, "OK", nil, { sdp_media = tsuo.SDP_MEDIA_LINPHONE_U })
tsuo.invite_send_2xx_ack (context)
tv = match.elapsed ("200 OK (2.0s)", tv, 1.98)
.invite_expect_response [Asynchronous]
The invite_expect_response
method will request the TestSipLuaAgent to wait until an inbound
SIP 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 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.
- The expected ISUP Content and Content-Type is verified, or confirmed to be absent.
The invite_expect_response
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context as used in a previous call to invite_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 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 INVITE Response. |
.value
|
UNDEF or String or Array of String
|
The value of the header to test from the 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). |
.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).
|
.isup_bytes
|
String |
Optional ISUP bytes which we expect to receive in the INVITE Response. If ISUP is expected then the Content-Type header value (top-level or multipart) must contain application/ISUP .If ISUP is not expected, then there must be no ISUP Content, and if no SDP content is present then there must be no Content body. (Default = expect to receive no ISUP content). |
.text_plain
|
String |
If specified, this must that the SIP INVITE Reponse content should contain exactly the indicated plain text. No SDP or ISUP content may be present in this case. (Default = plain text should not be present). |
This method returns the decoded SIP INVITE Response message, as returned by the “n2.http” utility module.
Example: See the above example for invite_send_request.
.invite_send_2xx_ack [Synchronous]
The invite_send_2xx_ack
method sends a TEST-SIP-SEND
message to the TestSipApp to request that
an outbound SIP INVITE ACK Request is sent to the previously determined remote endpoint IP and port address.
The ACK is suitable for acknowledging a INVITE 2XX Response which was previously received using
the invite_expect_response
method. This ACK is not suitable for acknowledging a INVITE 300-699 Response.
Use the invite_send_decline_ack
for that purpose.
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 INVITE ACK for 2XX Request message with standard plus extra headers.
- SDP Content may be present in the outbound INVITE 2xx ACK Request.
- ISUP Content is not supported in outbound INVITE 2xx ACK Request.
- Send that message to the pre-selected remote endpoint.
The invite_send_2xx_ack
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context as used in a previous call to invite_expect_response .
|
sdp_content
|
String |
Optional SDP content to include in the SIP INVITE 2xx ACK Request. (Default = do not include SDP in the INVITE 2xx ACK 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 INVITE ACK Request. |
.value
|
String | The value of the extra header to add to the INVITE ACK Request. |
The invite_send_2xx_ack
method returns nil
.
Example: See the above example for invite_send_request.
.invite_send_decline_ack [Synchronous]
The invite_send_decline_ack
method sends a TEST-SIP-SEND
message to the TestSipApp to request that
an outbound SIP INVITE ACK Request is sent to the previously determined remote endpoint IP and port address.
The ACK is suitable for acknowledging a INVITE 300-600 Response which was previously received using
the invite_expect_response
method. This ACK is not suitable for acknowledging a INVITE 2xx Response.
Use the invite_send_2xx_ack
for that purpose.
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:
- Re-use the original INVITE CSeq from the INVITE context.
- Construct a new SIP INVITE ACK for 300-699 Request message with standard plus extra headers.
- SDP Content is not supported in outbound INVITE 300-699 ACK Request.
- ISUP Content is not supported in outbound INVITE 300-699 ACK Request.
- Send that message to the pre-selected remote endpoint.
The invite_send_decline_ack
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context as used in a previous call to invite_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 INVITE ACK Request. |
.value
|
String | The value of the extra header to add to the INVITE ACK Request. |
The invite_send_decline_ack
method returns nil
.
Example: Our SIP INVITE Request is declined.
-- Construct and Send INVITE Request.
tsuo.invite_send_request (context, sdp_offer, { { name = 'Scenario', value = '400' } })
-- Expect Trying & Ringing automatically.
tsuo.invite_expect_response (context, 100, "Trying")
tsuo.invite_expect_response (context, 180, "Ringing")
tv = match.elapsed ("Ring Notification (1.0ss)", tv, 0.95)
-- Expect INVITE Response (Status Code 400).
tsuo.invite_expect_response (context, 400, "Bad Request")
tv = match.elapsed ("Initial 400", tv, 0.95)
-- Deliberately pretend we lost the response. Don't ACK yet. Wait for the 400 to be repeated.
tsuo.invite_expect_response (context, 400, "Bad Request")
tv = match.elapsed ("Retransmitted 400", tv, 0.49)
-- Construct and Send ACK Request suitable for the 300-699 response we received.
tsuo.invite_send_decline_ack (context)