Navigation :

REGISTER (Outbound)

Introduction

These methods in from TestSipLuaAgent Lua API are used for tests which perform the SIP UAC role for a non-INVITE transaction, sending an outbound SIP REGISTER Request and expecting one or more responses.

REGISTER (Outbound) API

.register_send_request [Synchronous]

The register_send_request method sends a TEST-SIP-SEND message to the TestSipApp to request that an outbound SIP REGISTER 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 non-INVITE context and increment it.
Construct a new SIP REGISTER Request message with standard plus extra headers.
Set the Content to be empty.
Send that message to the pre-selected remote endpoint.

The register_send_request method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The non-INVITE context for this transaction, returned by `non_invite_context`.
`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 REGISTER Request.
`.value`	String	The value of the extra header to add to the REGISTER Request.

The register_send_request method returns nil.

Example of sending two SIP REGISTER Requests:

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 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  = '665566'
local username      = '665566'
local password      = 'ABC'

-- Get a SIP outcall context from our helper library.
local context = tsuo.non_invite_context (endpoints, calling_party, called_party, { contact_expires = '3600' })

-- Switch the authentication mode to DIGEST.
n2svcd.management_configuration_scalar ('LHO', 'sip_auth_schema', 'digest')

-- Attempt to register again this time expecting an unauthorized response.
tsuo.register_send_request (context)

-- Expect REGISTER response (401 Unauthorized).
local response = tsuo.register_expect_response (context, 401, "Unauthorized")

-- Generate the authorization header for our request.
local www_auth_header = tsuo.header_fetch (response.headers, "WWW-Authenticate")
local authorization_header = tsuo.auth_header_value (context, 'REGISTER', www_auth_header, username, password)

-- Attempt to register again this time expecting a successful auth response.
tsuo.register_send_request (context, { { name = "Authorization", value = authorization_header } })

-- Expect REGISTER response 200 OK.
tsuo.register_expect_response (context, 200, "OK")

-- Switch the authentication mode back to OPEN.
n2svcd.management_configuration_scalar ('LHO', 'sip_auth_schema', 'open')

return

This example performs two separate transactions. The context is initialized only once, hence:

Both transactions share the same Call-ID.
Each transaction has a unique Via Branch.
Each transaction has a unique local URI tag (the “From” tag).
No Dialog is completed.

This is appropriate behavior in this scenario.

.register_expect_response [Asynchronous]

The register_expect_response method will request the TestSipLuaAgent to wait until an inbound SIP REGISTER 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 CANCEL Response message.

A series of standard match tests will be performed on the received message headers - To/From/Via/etc.
The received Content must be empty.
The received Content-Type is ignored.

The register_expect_response method takes the following arguments:

Argument	Type	Description
`context`	Object	[Required] The non-INVITE context for this transaction as used for `register_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 REGISTER 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 REGISTER Response.
`.value`	`UNDEF` or String or Array of String	The value of the header to test from the REGISTER 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".

This method returns the decoded SIP REGISTER Response message, as returned by the “n2.http” utility module.

Example: See the above example for register_send_request.