INVITE (Inbound)
Introduction
These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAS role for an inbound INVITE transaction, expecting an inbound SIP INVITE Request for an as-yet-unknown Call-ID, which will begin a new dialog with associated Test SIP Library INVITE context.
The method invite_expect_request
has two specific unique points which are distinct from other “expect”
methods related to inbound messages, specifically:
- Before calling this method, the test script must first call the register_incall method.
- This method returns a new INVITE context for subsequent Test SIP library methods (instead of requiring a context parameter).
INVITE (Inbound) API
.invite_expect_request [Asynchronous]
The invite_expect_request
method will request the TestSipLuaAgent to wait until an inbound
SIP INVITE Request message is received, for a new SIP Call-ID
which does not yet currently
belong to any other Test SIP instance, and which has a secondary attribute (e.g. calling party,
called party) which matches the currently active “incall registration” made by this test script.
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.
- The received message is checked for validity and presence of mandatory SIP attributes.
- 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.
- A new Test SIP INVITE context object is created and returned.
The invite_expect_request
method takes the following arguments:
Argument | Type | Description |
---|---|---|
endpoints
|
Object |
[Required] The endpoints object defining the IP address and ports which will be used for
sending and receiving messages for this UAC transaction. This object is typically constructed using the default_endpoints method.
|
extra_headers
|
Array of Object |
An optional list of extra headers to be tested in the INVITE 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 INVITE Request. |
.value
|
UNDEF or String or Array of String
|
The value of the header to test from the INVITE 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". |
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
|
Byte String |
Optional ISUP bytes which we expect to receive in the INVITE Request. 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). |
This method returns the decoded SIP INVITE Request message, as returned by the “n2.http” utility module.
Example of expecting SIP INVITE Request to suspend after receiving 200 OK with media:
-- Construct an SDP Offer with only PCMU (including telephone-event).
local sdp_offer = tsuo.sdp_offer (context, tsuo.SDP_MEDIA_LINPHONE)
-- Construct and Send INVITE Request containing the SDP Offer.
tsuo.invite_send_request (context, sdp_offer)
-- Expect Trying (no Ringing) from the IVR.
tsuo.invite_expect_response (context, 100, "Trying")
-- Expect INVITE Answer Response (200 OK) immediately also.
-- The SDP Answer is expected to be PCMU with telephone-event.
--
local response = tsuo.invite_expect_response (context, 200, "OK", nil, { sdp_media = tsuo.SDP_MEDIA_LINPHONE_U })
tsuo.invite_send_2xx_ack (context)
-- We now expect a INVITE which contains an SDP Offer that is:
-- PCMU without telephone-event
-- Suspended using the "inactive" media attribute.
--
tsuo.invite_expect_request (context, {}, { sdp_media = tsuo.SDP_MEDIA_NT_LINPHONE_U, sdp_suspended = tsuo.SDP_SUS_INACTIVE })
-- We construct our INVITE SDP Answer to be identical to the received INVITE Offer.
tsuo.sdp_answer (context, tsuo.SDP_MEDIA_NT_LINPHONE_U, nil, tsuo.SDP_SUS_INACTIVE)
-- tsuo.invite_send_response (context, 100, "Trying")
tsuo.invite_send_response (context, 200, "OK", sdp_answer)
tsuo.invite_expect_2xx_ack (context, {})
.invite_expect_request_resend [Asynchronous]
The invite_expect_request_resend
method will request the TestSipLuaAgent to wait until an inbound
SIP INVITE Request message is received, for an existing Call-ID for which an inbound INVITE Request
was previously received through the invite_expect_request
.
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 Request, or if the received SIP message is not an INVITE
Request message, or if the INVITE Request is not a re-send of the previously received message.
- The received message is checked for validity and presence of mandatory SIP attributes.
- 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_request_resend
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 INVITE 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 INVITE Request. |
.value
|
UNDEF or String or Array of String
|
The value of the header to test from the INVITE 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". |
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
|
Byte String |
Optional ISUP bytes which we expect to receive in the INVITE Request. 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). |
This method returns the decoded SIP INVITE Request message, as returned by the “n2.http” utility module.
Example of expecting SIP INVITE Request to suspend after receiving 200 OK with media:
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 rest_agent = require "n2.n2svcd.rest_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 scenario = '003'
local calling_party = '7000'
local called_party = '0800777' .. scenario
-- Register for this called party (overwrite any previous registration).
tsuo.register_incall ({ called_party = called_party })
-- Start timer for elapsed checking.
local tv = match.elapsed ()
-- Open a rest client request to start the call.
local result = rest_agent.send_request (nil, {
path = '/outcall_pa_internal',
query = 'calling_party=' .. calling_party ..
'&called_party=' .. called_party ..
'&scenario=' .. scenario
})
local rest_response = rest_agent.expect_response ()
tv = match.elapsed ("Received REST Response (immediate)", tv, 0.0)
--------
-- SIP INVITE Request
--------
local context = tsuo.invite_expect_request (endpoints, { ['User-Agent'] = "N-Squared LHO", Scenario = scenario })
local call_pcv = context.invite_pcv
tv = match.elapsed ("Received SIP INVITE (immediate)", tv, 0)
-- Wait 0.5 seconds so that we get a re-send on the INVITE.
tsuo.invite_expect_request_resend (context, { ['User-Agent'] = "N-Squared LHO", Scenario = scenario })
.invite_send_response [Synchronous]
The invite_send_response
method sends a TEST-SIP-SEND
message to the TestSipApp to request that
an outbound SIP INVITE 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 INVITE Response message with standard plus extra headers.
- SDP Content is added, if it was requested.
- ISUP Content is not supported in outbound INVITE Response.
- Send that message to the pre-selected remote endpoint.
The invite_send_response
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context, as used for a previous call to invite_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". |
sdp_content
|
String |
The SDP Content to include in the SIP message. (Default = do not include SDP 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 Response. |
.name
|
String | The name of the extra header to add to the INVITE Response. |
.value
|
String | The value of the extra header to add to the INVITE Response. |
Example: See the above example for invite_expect_request.
.invite_expect_2xx_ack [Asynchronous]
The invite_expect_2xx_ack
method will request the TestSipLuaAgent to wait until an inbound
SIP INVITE ACK Request message is received, in the context of a previously established inbound
or outbound INVITE transaction/dialog which belongs to this Lua script instance. This must be
a INVITE ACK suitable for the 2xx Response sent by us.
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
ACK Request message suitable for the 2xx INVITE Response sent by us.
- 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 INVITE ACK Request.
The invite_expect_2xx_ack
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context, as used for a previous call to invite_send_response
with a SIP Status Code in the range 200-299.
|
extra_headers
|
Array of Object |
An optional list of extra headers to be tested in the INVITE ACK 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 INVITE ACK Request. |
.value
|
UNDEF or String or Array of String
|
The value of the header to test from the INVITE ACK 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". |
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).
|
Example: See the above example for invite_expect_request.
.invite_expect_decline_ack [Asynchronous]
The invite_expect_decline_ack
method will request the TestSipLuaAgent to wait until an inbound
SIP INVITE ACK Request message is received, in the context of a previously established inbound
or outbound INVITE transaction/dialog which belongs to this Lua script instance. This must be
a INVITE ACK suitable for the 300-699 Response sent by us.
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
ACK Request message suitable for the 300-699 INVITE Response sent by us.
- 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 INVITE ACK Request.
- No ISUP Content is permitted for inbound INVITE ACK Request.
The invite_expect_decline_ack
method takes the following arguments:
Argument | Type | Description |
---|---|---|
context
|
Object |
[Required] The INVITE context, as used for a previous call to invite_send_response
with a SIP Status Code in the range 300-699.
|
extra_headers
|
Array of Object |
An optional list of extra headers to be tested in the INVITE ACK 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 INVITE ACK Request. |
.value
|
UNDEF or String or Array of String
|
The value of the header to test from the INVITE ACK 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". |
Example: A INVITE for which we receive a subsequent CANCEL.
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 rest_agent = require "n2.n2svcd.rest_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 scenario = '001'
local calling_party = '7000'
local called_party = '0800777' .. scenario
-- Register for this called party (overwrite any previous registration).
tsuo.register_incall ({ called_party = called_party })
-- Open a rest client request to start the call.
local result = rest_agent.send_request (nil, {
path = '/outcall_pa_internal',
query = 'calling_party=' .. calling_party ..
'&called_party=' .. called_party ..
'&scenario=' .. scenario
})
local rest_response = rest_agent.expect_response ()
--------
-- SIP INVITE Request
--------
local context = tsuo.invite_expect_request (endpoints, { ['User-Agent'] = "N-Squared LHO", Scenario = scenario })
local call_pcv = context.invite_pcv
-- Construct and Send INVITE Response.
tsuo.invite_send_response (context, 602, "Unknown Reason", nil, {
{ name = 'Other', value = 'Test Header; my=tag' }, -- Logged in EDR and is returned in 602.
{ name = 'P-Charging-Vector', value = call_pcv } -- Echo the P-Charging-Vector in the response.
})
-- Table 1, RFC 3455 says that P-Charging-Vector should not appear in ACK.
tsuo.invite_expect_decline_ack (context, { ['P-Charging-Vector'] = UNDEF })
-- Deliberately pretend we lost the response. Don't ACK yet. Wait for the 602 to be repeated.
n2svcd.wait (0.5)
tsuo.invite_send_response (context, 602, "Unknown Reason", nil, {
{ name = 'Other', value = 'Test Header; my=tag' } -- Logged in EDR and is returned in 602.
})
-- Deliberately pretend we lost the response. Don't ACK yet. Wait for the 602 to be repeated.
-- Table 1, RFC 3455 says that P-Charging-Vector should not appear in ACK.
tsuo.invite_expect_decline_ack (context, { ['P-Charging-Vector'] = UNDEF })