Navigation :

re-INVITE (Inbound)

Introduction

These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAS role for an inbound re-INVITE transaction, expecting an inbound 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_expect_request and reinvite_send_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 (Inbound) API

.reinvite_expect_request [Asynchronous]

The reinvite_expect_request method will request the TestSipLuaAgent to wait until an inbound SIP re-INVITE Request message is received, in the context of a previously established inbound or outbound INVITE transaction/dialog 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 Request 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 Request.

The reinvite_expect_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 to be tested in the re-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 re-INVITE Request.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the re-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).

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

Example of expecting SIP re-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 re-INVITE which contains an SDP Offer that is:
--    PCMU without telephone-event
--    Suspended using the "inactive" media attribute.
--
tsuo.reinvite_expect_request (context, {}, { sdp_media = tsuo.SDP_MEDIA_NT_LINPHONE_U, sdp_suspended = tsuo.SDP_SUS_INACTIVE })

-- We construct our re-INVITE SDP Answer to be identical to the received re-INVITE Offer.
tsuo.sdp_answer (context, tsuo.SDP_MEDIA_NT_LINPHONE_U, nil, tsuo.SDP_SUS_INACTIVE)

-- tsuo.reinvite_send_response (context, 100, "Trying")
tsuo.reinvite_send_response (context, 200, "OK", sdp_answer)
tsuo.reinvite_expect_2xx_ack (context, {})

.reinvite_send_response [Synchronous]

The reinvite_send_response method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP re-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 re-INVITE Response message with standard plus extra headers.
SDP Content is added, if it was requested.
ISUP Content is not supported in outbound re-INVITE Response.
Send that message to the pre-selected remote endpoint.

The reinvite_send_response method takes the following arguments:

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

Example: See the above example for reinvite_expect_request.

.reinvite_expect_2xx_ack [Asynchronous]

The reinvite_expect_2xx_ack method will request the TestSipLuaAgent to wait until an inbound SIP re-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 re-INVITE ACK suitable for the 2xx 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 re-INVITE ACK Request.
No ISUP Content is permitted for inbound re-INVITE ACK Request.

The reinvite_expect_2xx_ack method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context, as used for a previous call to `reinvite_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 re-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 re-INVITE ACK Request.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the re-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: See the above example for reinvite_expect_request.

.reinvite_expect_decline_ack [Asynchronous]

The reinvite_expect_decline_ack method will request the TestSipLuaAgent to wait until an inbound SIP re-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 re-INVITE ACK suitable for the 300-699 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 re-INVITE ACK Request.
No ISUP Content is permitted for inbound re-INVITE ACK Request.

The reinvite_expect_decline_ack method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context, as used for a previous call to `reinvite_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 re-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 re-INVITE ACK Request.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the re-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 re-INVITE for which we receive a subsequent CANCEL.

-- We receive an inbound re-INVITE
tsuo.reinvite_expect_request (context, {}, { sdp_media = tsuo.SDP_MEDIA_NT_LINPHONE_U, sdp_suspended = tsuo.SDP_SUS_INACTIVE })

-- We give a 100 Trying, but don't actually conclude this.
tsuo.reinvite_send_response (context, 100, "Trying")

-- Time passes.  The far-end will cancel the re-INVITE.
tsuo.reinvite_cancel_expect_request (context, {})
tsuo.reinvite_cancel_send_response (context, 200, "OK")

-- We terminate the re-INVITE as requested, and get an appropriate ACK.
tsuo.reinvite_send_response (context, 487, "Request Terminated")
tsuo.reinvite_expect_decline_ack (context, {})

.reinvite_cancel_expect_request [Asynchronous]

The reinvite_cancel_expect_request method will request the TestSipLuaAgent to wait until an inbound SIP re-INVITE CANCEL Request message is received, in the context of a previously established inbound or outbound INVITE transaction/dialog which belongs to this Lua script instance.

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 re-INVITE CANCEL Request.
No ISUP Content is permitted for inbound re-INVITE CANCEL Request.

The reinvite_cancel_expect_request method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context, as used for a previous call to `reinvite_expect_request`.
`extra_headers`	Array of Object	An optional list of extra headers to be tested in the re-INVITE CANCEL 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 re-INVITE CANCEL Request.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the re-INVITE CANCEL 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: See the above example for reinvite_expect_decline_ack.

.reinvite_cancel_send_response [Synchronous]

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

The method will:

Construct a new SIP re-INVITE CANCEL Response message with standard plus extra headers.
ISUP Content is not supported in outbound re-INVITE CANCEL Response.
ISUP Content is not supported in outbound re-INVITE CANCEL Response.
Send that message to the pre-selected remote endpoint.

The reinvite_cancel_send_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The INVITE context, as used for a previous call to `reinvite_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".
`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 re-INVITE CANCEL Response.
`.value`	String	The value of the extra header to add to the re-INVITE CANCEL Response.

Example: See the above example for reinvite_expect_decline_ack.