☰
Navigation :

SDP Methods & Constants

Introduction

The TestSipLuaAgent Lua API library file test_sip_agent.lua provides methods and constants for building SDP to send in output SIP Test messages, and also to define the options parameters for testing received SDP in the methods which expect inbound SDP.

The methods for building outbound SDP are:

The methods which accept an sdp_content parameter for sending SDP are:

When validating received SDP you must specify the expected sdp_media and potentially either sdp_suspended (if you expect to receive a “suspended” session descriptor) or sdp_direction if you expect to receive a session descriptor for a mono-directional stream.

Those SDP expectation attributes can set in the options parameter of the following methods:

SDP Constants

SDP Media Constants

The TestSIPAgent API provides support for some representative SDP structures. These exist for the convenience of test writers who are implementing SIP behavior tests and RTP timing scenario tests, where all that is needed is a simple, quick SDP construction.

These media types cover PCMU, PCMA, and AMR-WB codecs which are all that the N2SIP framework internal media server is currently capable of generating.

The following media type constants for defined:

-- SDP "No Media" constant.
tsuo.SDP_MEDIA_NONE = false                           -- SDP media is not present

-- SDP media constants for SDP Offer and matching logic.
tsuo.SDP_MEDIA_LINPHONE = 'linphone'                  -- SDP multiple-media Offer sent in original INVITE (Linphone-style)
tsuo.SDP_MEDIA_METASWITCH = 'metaswitch'              -- SDP multiple-media Offer sent in original INVITE (MetaSwitch-style)
tsuo.SDP_MEDIA_N2_UA = 'n2_ulaw_alaw'                 -- SDP multiple-media Offer sent Late in INVITE 200 OK Response (N-Squared RTP uLaw/aLaw)

-- SDP media constants for SDP Answer and matching logic.
tsuo.SDP_MEDIA_N2_U = 'n2_ulaw'                       -- SDP single-media (uLaw only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP uLaw)
tsuo.SDP_MEDIA_N2_A = 'n2_alaw'                       -- SDP single-media (aLaw only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP aLaw)
tsuo.SDP_MEDIA_N2_AMRNB = 'n2_amrnb'                  -- SDP multiple-media (AMR[-NB] only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR[-NB])
tsuo.SDP_MEDIA_N2_AMRNB_OA = 'n2_amrnb_oa'            -- SDP single-media (octet-aligned AMR[-NB] only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR[-NB])
tsuo.SDP_MEDIA_N2_AMRNB_BE = 'n2_amrnb_be'            -- SDP single-media (bandwidth-efficient AMR[-NB] only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR[-NB])
tsuo.SDP_MEDIA_N2_AMRWB = 'n2_amrwb'                  -- SDP multiple-media (AMR-WB only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR-WB)
tsuo.SDP_MEDIA_N2_AMRWB_OA = 'n2_amrwb_oa'            -- SDP single-media (octet-aligned AMR-WB only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR-WB)
tsuo.SDP_MEDIA_N2_AMRWB_BE = 'n2_amrwb_be'            -- SDP single-media (bandwidth-efficient AMR-WB only) Answer sent Late in INVITE 200 OK Response (N-Squared RTP AMR-WB)
tsuo.SDP_MEDIA_LINPHONE_U = 'linphone_ulaw'           -- SDP single-media (uLaw only) Answer with telephone-event
tsuo.SDP_MEDIA_METASWITCH_A = 'metaswitch_alaw'       -- SDP single-media (aLaw only) Answer with telephone-event
tsuo.SDP_MEDIA_NT_N2_UA = 'NT_n2_ulaw_alaw'           -- SDP multiple-media/Answer Offer (N-Squared RTP uLaw/aLaw) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_U = 'NT_n2_ulaw'                 -- SDP single-media (uLaw only) Answer (N-Squared RTP uLaw) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_A = 'NT_n2_alaw'                 -- SDP single-media (aLaw only) Answer (N-Squared RTP aLaw) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRNB = 'NT_n2_amrnb'            -- SDP dual-media (AMR-[NB] only) Answer (N-Squared RTP AMR[-NB]) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRNB_OA = 'NT_n2_amrnb_oa'      -- SDP single-media (octet-aligned AMR-[NB] only) Answer (N-Squared RTP AMR[-NB]) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRNB_BE = 'NT_n2_amrnb_be'      -- SDP single-media (bandwidth-efficient AMR-[NB] only) Answer (N-Squared RTP AMR[-NB]) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRWB = 'NT_n2_amrwb'            -- SDP dual-media (AMR-WB only) Answer (N-Squared RTP AMR-WB) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRWB_OA = 'NT_n2_amrwb_OA'      -- SDP single-media (octet-aligned AMR-WB only) Answer (N-Squared RTP AMR-WB) with NO telephone-event
tsuo.SDP_MEDIA_NT_N2_AMRWB_BE = 'NT_n2_amrwb_be'      -- SDP single-media (bandwidth-efficient AMR-WB only) Answer (N-Squared RTP AMR-WB) with NO telephone-event
tsuo.SDP_MEDIA_NT_LINPHONE_U = 'NT_linphone_ulaw'     -- SDP single-media (uLaw only) Answer with NO telephone-event
tsuo.SDP_MEDIA_NT_METASWITCH_A = 'NT_metaswitch_alaw' -- SDP single-media (aLaw only) Answer with NO telephone-event
Constant Value Description
tsuo.SDP_MEDIA_NONE false No SDP media should be present, the Content-Type for SDP should not be present.
This is not used for encoding SDP Offer or Answer bodies, but is used for tests where the test explicitly does not expect any SDP body to be received.

SDP Suspended Constants

The SDP Suspended values specify if the SDP being constructed is “supended” i.e. “inactive” or not.

This value is relevant only when the SDP Media type is specified.

By default, the non-suspended SDP session description is constructed to send, or expected to be received, which is the equivalent of specifying tsuo.SDP_SUS_NONE.

The constants are:

-- SDP suspension flags (implies a single-stream offer/answer)
tsuo.SDP_SUS_NONE = false           -- SDP stream is not suspended
tsuo.SDP_SUS_INACTIVE = 'inactive'  -- SDP single-media Offer/Answer with 'a=inactive'
tsuo.SDP_SUS_NO_HOST = 'no_host'    -- SDP single-media Offer/Answer with 0.0.0.0 address

SDP Direction Constants

The SDP Suspended values specify if the media is expected to be bi-direction or mono-directional.

This value is relevant only when the SDP Media type is specified and the SDP is active (i.e. not suspended).

By default a non-suspended media stream is constructed to send or expected to be received as “sendrecv”.

-- SDP Direction attributes.
tsuo.SDP_DIR_NONE = false             -- No stream direction attribute is present
tsuo.SDP_DIR_SENDRECV = 'sendrecv'    -- The "a=sendrecv" attribute is added
tsuo.SDP_DIR_SENDONLY = 'sendonly'    -- The "a=sendonly" attribute is added
tsuo.SDP_DIR_RECVONLY = 'recvonly'    -- The "a=recvonly" attribute is added

SDP Methods

.sdp_offer [Pure Lua]

This method constructs an SDP Offer body for the indicated media type, suitable for sending as the sdp_content SDP Offer parameter for the methods indicated above.

An SDP Offer constructed by the Test SIP Lua library is never suspended, and never contains a direction attribute when an SDP Offer is applicable.

Only a few

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.
.sdp_media tsuo.SDP_MEDIA_LINPHONE / tsuo.SDP_MEDIA_METASWITCH / tsuo.SDP_MEDIA_N2_UA [Required] This must be one of the SDP Media Constants supported for Offer construction.

SDP Methods

.sdp_answer [Pure Lua]

This method constructs an SDP Answer body for the indicated media type and suspended/direction parameters, suitable for sending as the sdp_content parameter for the methods indicated above when an SDP Answer is applicable.

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.
.sdp_media tsuo.SDP_MEDIA_N2_U / tsuo.SDP_MEDIA_N2_A / tsuo.SDP_MEDIA_N2_AMRNB / tsuo.SDP_MEDIA_N2_AMRNB_OA / tsuo.SDP_MEDIA_N2_AMRNB_BE / tsuo.SDP_MEDIA_N2_AMRWB / tsuo.SDP_MEDIA_N2_AMRWB_OA / tsuo.SDP_MEDIA_N2_AMRWB_BE / tsuo.SDP_MEDIA_LINPHONE_U / tsuo.SDP_MEDIA_METASWITCH_A / tsuo.SDP_MEDIA_NT_N2_UA / tsuo.SDP_MEDIA_NT_N2_U / tsuo.SDP_MEDIA_NT_N2_A / tsuo.SDP_MEDIA_NT_N2_AMRNB / tsuo.SDP_MEDIA_NT_N2_AMRNB_OA / tsuo.SDP_MEDIA_NT_N2_AMRNB_BE / tsuo.SDP_MEDIA_NT_N2_AMRWB / tsuo.SDP_MEDIA_NT_N2_AMRWB_OA / tsuo.SDP_MEDIA_NT_N2_AMRWB_BE / tsuo.SDP_MEDIA_NT_LINPHONE_U / tsuo.SDP_MEDIA_NT_METASWITCH_A [Required] This must be one of the pre-defined SDP Media Constants for which SDP Answer is supported.
.sdp_suspended tsuo.SDP_SUS_* If specified, this must be one of the pre-defined SDP Suspended Constants.
(Default = tsuo.SDP_SUS_NONE the non-suspended (i.e. active) variant is constructed).
.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 suspended is not-suspended.
(Default = the stream direction is not specified in the SDP).

.parse_sdp [Synchronous]

Parses an SDP session string and returns an object representation of the individual elements.

Argument Type Description
value String [Required] The SDP string content to be parsed.

The parse_sdp method returns a complex nested object representation of the SDP.

Argument Type Description
sdp Object The container for the SDP information.
.session_name String The supplied session version string.
.session_name Integer The supplied session version number.
.connection Object Container for connection inforation.
.ip4 Object Container for IPv4 connection inforation.
.address IPv4 Address The IPv4 connection address as a dot-separated numeric field.
.originator Object Container for originator inforation.
.ip4 Object Container for IPv4 originator inforation.
.address IPv4 Address The IPv4 originator address as a dot-separated numeric field.
.username String The originator username.
.id Integer The originator numeric ID.
.medias Array of String The names of all media types defined in this SDP.
These are the keys of the media sub-table.
.media Object Container for all media types.
Each media type defined in the medias list should exist as a key here.
Each key may have the following characteristics defined.
.<Media Type Key> Object For a voice session the Media Type Key is nearly always "audio".
Definition of the media stream for this media type.
.name String The Media Type Key name is repeated as a sub-element.
.port Integer The RTP UDP port number for this media.
.encodings Integer The integer IDs of all media encodings defined for this media type.
These are the keys of the encoding sub-table.
.encoding Object Container for all media encoding details.
Each encoding type defined in the encodings list for this media should exist as a key here.
Each key may have the following characteristics defined.
.<Encoding ID Key> Object Some encoding types have hard-coded IDs assigned in the RTP RFC document, others are dynamic.
Definition of the encoding for this encoding ID.
.name String Name of the encoding associated with this encoding ID.
This name is not guaranteed to be unique across encoding IDs.
.clock_rate Integer The clock rate in Hz.
.attributes Array of String Array of free-form attributes defined in fmtp elements for this encoding.

Example: Parse SDP and check that the received values match the EDR values.

local sdp = tsuo.parse_sdp (invite_response.content)
if (match.kpath_size (edrs, 'list.RTP-ESTABLISH', 1)) then error ("Missing EDR(s) for RTP-ESTABLISH.") end
match.kpath_string (edrs, 'list.RTP-ESTABLISH.[0].LOCAL_IP', sdp.connection.ip4.address)
match.kpath_integer (edrs, 'list.RTP-ESTABLISH.[0].LOCAL_PORT', sdp.media.audio.port)