☰
Navigation :

Test SIP Messages

Introduction

The Test SIP Application (TestSipApp) serves as an endpoint for sending and receiving SIP messages over TCP and UDP. This functionality is driven by a Lua Test script via the TestSipLuaAgent.

The internal messages exchanged between the TestSipLuaAgent and the TestSipApp are:

TEST-SIP-FAIL

The TEST-SIP-FAIL message is sent from the TestSipApp to the TestSipLuaAgent to indicate that the most recent TEST-SIP-PREPARE-OUTCALL, TEST-SIP-REGISTER-INCALL, or TEST-SIP-SEND message was not handled successfully.

Specifically:

The attributes of the TEST-SIP-FAIL message are:

Field Type Description
call_id String The SIP Call-ID identifying the call that the failure is associated with, if known.
reason String [Required] A short description of the reason for the failure.

TEST-SIP-PREPARE-OUTCALL

The TEST-SIP-PREPARE-OUTCALL message is sent from the TestSipLuaAgent to the TestSipApp to instruct the TestSipApp to prepare for an out-call to a specified called party.

The TestSipApp will attempt to identify an appropriate peer and transport for the out-call. The peer must be configured in such a way that it can be used to trunk calls to the specified called party, and TestSipApp must have an active route to the peer.

After sending this message, the TestSipLuaAgent should send no further messages until it receives one of the following messages from the TestSipApp:

If the TestSipApp cannot identify an appropriate peer and transport, the TestSipApp will send a TEST-SIP-FAIL message to the TestSipLuaAgent.

Otherwise if successful, the TestSipApp will send a TEST-SIP-PREPARED-OUTCALL message to the TestSipLuaAgent.

The attributes of the TEST-SIP-PREPARE-OUTCALL message are:

Field Type Description
call_id String [Required] The SIP Call-ID that will be used to identify the out-call.
called_party (+)Hex String [Required] The called party for the out-call.
peer_id String The identifier for a configured sip_peer to use for the out-call.
This peer must be able trunk calls to the specified called_party.
If not specified, TestSipApp will use trunk, peer group, and peer configuration to attempt to identify the first peer that can be used to trunk calls to the called party.
(Default = not specified; use the first peer identified by TestSipApp).
transport tcp / udp The SIP transport to use for the out-call.
TestSipApp must have an active route to the selected peer for this transport.
(Default = not specified; use the peer's transport policy to identify the most preferred transport with an active route).

TEST-SIP-PREPARED-OUTCALL

The TEST-SIP-PREPARED-OUTCALL message is sent from the TestSipApp to the TestSipLuaAgent to indicate that the most recent TEST-SIP-PREPARE-OUTCALL message was processed successfully, and the TestSipApp is now ready to handle an out-call to the specified called party.

The attributes of the TEST-SIP-PREPARED-OUTCALL message are:

TEST-SIP-REGISTER-INCALL

The TEST-SIP-REGISTER-INCALL message is sent from the TestSipLuaAgent to the TestSipApp to indicate that the TestSipLuaAgent is expecting an inbound in-call.

TestSipApp will store relevant details so that when an inbound SIP request is received, it can pass the request to the appropriate TestSipLuaAgent.

After sending this message, the TestSipLuaAgent should send no further messages until it receives one of the following messages from the TestSipApp:

  • TEST-SIP-REGISTERED-INCALL
  • TEST-SIP-FAIL

If the TEST-SIP-REGISTER-INCALL does not contain sufficient detail to match and handle an inbound SIP request, the TestSipApp will send a TEST-SIP-FAIL message to the TestSipLuaAgent.

Otherwise if successful, the TestSipApp will send a TEST-SIP-REGISTERED-INCALL message to the TestSipLuaAgent.

The attributes of the TEST-SIP-REGISTER-INCALL message are:

Field Type Description
expires_ts Positive Integer [Required] The UNIX epoch when the prepared out-call will expire.
TestSipLuaAgent should send the first SIP request for the call before this time.
local_contact_host String [Required] 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.
local_contact_port Positive Integer [Required] 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.
peer_id String [Required] The identifier of the configured SIP peer that TestSipApp selected for the out-call.
This will be the same as the TEST-SIP-PREPARE-OUTCALL peer_id parameter if it was specified.
remote_domain String [Required] The sip_domain configured for the peer that TestSipApp selected for the out-call.
TestSipLuaAgent may use this to construct the Request-URI and To header in outbound SIP messages.
transport tcp / udp [Required] The SIP transport that TestSipApp selected for the out-call.
This will be the same as the TEST-SIP-PREPARE-OUTCALL transport parameter if it was specified.
bound_local_ips Array of IP Address [Required] An array of the bound local IP addresses associated with the route to the selected peer for the selected transport.
bound_local_port Positive Integer [Required] The bound local port associated with the route to the selected peer for the selected transport.
local_public_host String [Required] 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.
local_public_port Positive Integer [Required] 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.
peer_remote_ips Array of IP Address [Required] An array of the remote IP addresses associated with the route to the selected peer for the selected transport.
peer_remote_port Positive Integer [Required] The remote port associated with the route to the selected peer for the selected transport.
Field Type Description
match Object [Required] A structure containing one or more of the following attributes.
Inbound SIP requests must match all specified attributes.
calling_party (+)Hex String This attribute is used to match against the userinfo part of the P-Asserted-Identity (if present) or From header address in the inbound SIP request.
The attribute value must fully match the userinfo part. There is currently no support for prefix, partial, or wild-card matching.
called_party (+)Hex String This attribute is used to match against the userinfo part of the Request URI address in the inbound SIP request.
The attribute value must fully match the userinfo part. There is currently no support for prefix, partial, or wild-card matching.

TEST-SIP-REGISTERED-INCALL

The TEST-SIP-REGISTERED-INCALL message is sent from the TestSipApp to the TestSipLuaAgent to indicate that the most recent TEST-SIP-REGISTER-INCALL message was processed successfully, and the TestSipApp is now ready to match inbound SIP requests.

The attributes of the TEST-SIP-REGISTERED-INCALL message are:

TEST-SIP-RECV

The TEST-SIP-RECV message is sent from the TestSipApp to the TestSipLuaAgent to indicate that a SIP message (request or response) has been received for a call. The message may be the first request for a new in-call, or a subsequent message for an existing in-call or out-call.

The attributes of the TEST-SIP-RECV message are:

Field Type Description
expires_ts Positive Integer [Required] The UNIX epoch when the in-call registration will expire.
The first inbound SIP request for the in-call must be received before this time.
Field Type Description
call_id String [Required] The SIP Call-ID in the 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.

TEST-SIP-SEND

The TEST-SIP-SEND message is sent from the TestSipLuaAgent to the TestSipApp to instruct the TestSipApp to send a SIP message (request or response) for a call. The message may be the first request for a new out-call, or a subsequent message for an existing in-call or out-call.

After sending this message, the TestSipLuaAgent should send no further messages until it receives one of the following messages from the TestSipApp:

If the TestSipApp fails to send the message for any reason, the TestSipApp will send a TEST-SIP-FAIL message to the TestSipLuaAgent.

Otherwise if successful, the TestSipApp will send a TEST-SIP-SENT message to the TestSipLuaAgent.

The attributes of the TEST-SIP-SEND message are:

Field Type Description
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.
payload String [Required] The SIP message bytes to send.

TEST-SIP-SENT

The TEST-SIP-SENT message is sent from the TestSipApp to the TestSipLuaAgent to indicate that the SIP message associated with the most recent TEST-SIP-SEND message was sent successfully.

The attributes of the TEST-SIP-SENT message are:

Field Type Description
expires_ts Positive Integer [Required] The UNIX epoch when the call will expire.
The next inbound SIP message must be received or the next outbound SIP message must be sent before this time.

TEST-SIP-SHUTDOWN

The TEST-SIP-SHUTDOWN message is sent from the TestSipLuaAgent to the TestSipLuaApp to instruct the TestSipApp to shut down an instance.

This message is normally sent when a test completes.

The TEST-SIP-SHUTDOWN message does not have any attributes.