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 [Synchronous]

The send_payload method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP message is sent to the specified 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:

Send the message to the pre-selected remote endpoint.

The send_payload method takes the following arguments:

Argument	Type	Description
`call_id`	Object	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 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 endpoints = tsuo.default_endpoints ({ local_rtp_port = 3668 })
local calling_party = '665566'
local called_party = '902112233'

-- 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)

-- Construct and Send INVITE Request.
context.invite_seq = context.local_seq
context.local_seq = context.local_seq + 1

-- Assign a new Via branch.
context.invite_branch = 'z9hG4bK.' .. n2svcd.auto_id ('branch')  -- Unique for the original INVITE Transaction
context.invite_via = 'SIP/2.0/UDP ' .. endpoints.local_sip_ip .. ':' .. endpoints.local_sip_port .. ';branch=' .. context.invite_branch .. ';rport'

local invite_http = {
  method = 'INVITE', uri = context.request_uri, protocol = 'SIP/2.0',
  headers = {
    { name = 'Via', value = context.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.invite_seq .. ' 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, endpoints.remote_sip_ip, endpoints.remote_sip_port, context.call_id, tsuo.INVITE_SECONDS)

-- 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`	Object	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	The bytes of the SIP message. For a UDP source, no checking has been performed, not even checking for a valid SIP header. For a TCP source, checking has been performed sufficient to determine the end of the message within the stream.
`.originator_ip`	Object	The far-end IP address for this UDP packet or TCP stream.
`.originator_port`	Object	The far-end UDP or TCP port for this UDP packet or TCP stream.

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)