Navigation :

Payload Methods

Introduction

These methods in from TestSipLuaAgent Lua API are direct access to the payload methods.

In nearly all cases, your test script should use the “expect” methods for a specific inbound SIP Request or Response. The only time when these methods should be used is when testing an unusual/broken/exception case where the test does not follow the “correct” SIP behavior.

Payload API

.send_payload [Asynchronous]

The send_payload method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP message be sent for a call.

An error will be raised if the SIP message cannot be sent for any reason.

The send_payload method takes the following arguments:

Argument	Type	Description
`bytes`	String	[Required] The SIP message bytes to send.
`call_id`	String	[Required] The SIP Call-ID for the call that the message to be sent is associated with. This must be a valid Call-ID for a previously established call.
`is_request`	Boolean	[Required] `True` if the SIP message to be sent is a request.
`method`	String	[Required] If the SIP message to be sent is a request, the request method (e.g. INVITE). If the SIP message to be sent is a response, the method in the associated request.
`code`	`100` - `699`	[Required if the SIP message to be sent is a response.] The SIP response status code (e.g. 200). `TestSipApp` uses this parameter to ensure subsequent requests are sent to the correct remote target.
`via_branch`	String	[Required if the SIP message to be sent is a response.] The SIP `Via` header `branch` parameter value. `TestSipApp` uses this parameter to select the correct route to send the response.

The send_payload method returns nil.

Example: Constructing and sending a payload which omits the From header.

local n2svcd = require "n2.n2svcd"
local utils = require "n2.utils"
local http = require "n2.http"
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 calling_party = '665566'
local called_party = '902112233'

-- Get a SIP outcall context from our helper library.
local context = tsuo.invite_context (nil, calling_party, called_party)
tsuo.dummy_rtp_endpoint (context)

-- Construct the SDP
local sdp_offer = tsuo.sdp_offer (context, tsuo.SDP_LINPHONE)

-- Construct and Send INVITE Request.
context.outbound.invite.cseq = context.local_cseq
context.local_cseq = context.local_cseq + 1

context.outbound.invite.via = tsuo.new_via (context)

local invite_http = {
  method = 'INVITE', uri = context.request_uri, protocol = 'SIP/2.0',
  headers = {
    { name = 'Via', value = tsuo.stringify_via (context.outbound.invite.via) },
    { name = 'Via', value = 'Second VIA Header' },
    { name = 'Via', value = 'Bottom VIA Header' },
    { name = 'To', value = context.remote_uri },
    { name = 'Call-ID', value = context.call_id },
    { name = 'Contact', value = context.contact },
    { name = 'CSeq', value =  context.out_invite_cseq .. ' INVITE' },
    { name = 'Max-Forwards', value = tsuo.MAX_FORWARDS },
    { name = 'Allow', value = tsuo.ALLOW },
  }
}
table.insert (invite_http.headers, { name = 'Content-Type', value = 'application/sdp' })
table.insert (invite_http.headers, { name = 'Content-Length', value = string.len (sdp_offer) })
invite_http.content = sdp_offer

local invite_bytes = http.request_encode (invite_http)
tsuo.send_payload (invite_bytes, context.call_id, true, 'INVITE')

-- No response is received, the SIP INVITE Request is invalid and will be discarded by the service.
...

.expect_payload [Asynchronous]

The expect_payload method will request the TestSipLuaAgent to wait until an inbound SIP message is received in the context of the specified Call-ID, or else for a registered in-call for which the Call-ID is not yet known.

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.

No tests are performed on this message.

The expect_payload method takes the following arguments:

Argument	Type	Description
`call_id`	String	Specify the Call-ID for which we expect to receive a SIP message. If this value is `nil` then we expect to receive a SIP message associated for an active incall registration. (Default = wait for a new inbound SIP invite for an open registration).
`seconds`	Integer	Override the default timeout for how long we wait. (Default = the currently configured default agent timeout).

The method returns the following table on success.

Argument	Type	Description
`result`	Object	An object describing the received SIP message.
`.payload`	String	[Required] The received SIP message bytes.
`.local_contact_host`	String	The `TestSipApp`'s configured `sip_contact_host`. This is the globally accessible host or IP address that can be used to contact the `TestSipApp`. `TestSipLuaAgent` may use this to construct the `Contact` header in outbound SIP messages. This attribute is only present for the first inbound SIP request for a new in-call.
`.local_contact_port`	Positive Integer	The `TestSipApp`'s configured `sip_contact_port`. This is the globally accessible port associated with `local_contact_host` that can be used to contact the `TestSipApp`. `TestSipLuaAgent` may use this to construct the `Contact` header in outbound SIP messages. This attribute is only present for the first inbound SIP request for a new in-call.
`.transport`	`tcp` / `udp`	[Required] The SIP transport that the remote peer used to send the message.
`.bound_local_ips`	Array of IP Address	[Required] An array of the bound local IP addresses associated with the socket that received the message.
`.bound_local_port`	Positive Integer	[Required] The bound local port associated with the socket that received the message.
`local_public_host`	String	The `TestSipApp`'s configured `sip_public_*_host`. This is the publicly accessible host or IP address that can be used to contact the `TestSipApp` using the selected transport. `TestSipLuaAgent` may use this to construct the `Via` header in outbound SIP requests. This attribute is only present for the first inbound SIP request for a new in-call.
`local_public_port`	Positive Integer	The `TestSipApp`'s configured `sip_public_*_port`. This is the publicly accessible port associated with `local_contact_host` that can be used to contact the `TestSipApp` using the selected transport. `TestSipLuaAgent` may use this to construct the `Via` header in outbound SIP requests. This attribute is only present for the first inbound SIP request for a new in-call.
`.peer_remote_ips`	Array of IP Address	[Required] An array of the remote IP addresses associated with the route that the remote peer used to send the message.
`.peer_remote_port`	Positive Integer	[Required] The remote port associated with the route that the remote peer used to send the message.

Example getting payload using the direct payload method:

-- Expect SIP Response
local result = tsuo.expect_payload (context.call_id)
local response_bytes = result.payload
local response = http.response_decode (response_bytes)

.expect_no_payload [Asynchronous]

The expect_payload method will request the TestSipLuaAgent to wait and ensure that no inbound SIP message is received in the context of the specified Call-ID.

The agent will wait up until the expect_secs configured value for a SIP message to not arrive. An error will be raised if any message is received in this time.

The expect_no_payload method takes the following arguments:

Argument	Type	Description
`call_id`	Object	[Required] Specify the Call-ID for which we expect to receive no SIP message.
`seconds`	Integer	Override the default timeout for how long we wait. (Default = the currently configured default agent timeout).

The method returns nil on success.

Example checking for no payload:

-- Expect no SIP message for this call in the next 5 seconds.
tsuo.expect_no_payload (context.call_id, 5)