SDPOPS Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2011 asipto.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters
        4. Functions

              4.1. sdp_remove_codecs_by_id(list [, mtype])
              4.2. sdp_remove_codecs_by_name(list [, mtype])
              4.3. sdp_remove_line_by_prefix(string [, mtype])
              4.4. sdp_keep_codecs_by_id(list [, mtype])
              4.5. sdp_keep_codecs_by_name(list [, mtype])
              4.6. sdp_with_media(type)
              4.7. sdp_with_active_media(type)
              4.8. sdp_remove_media(type)
              4.9. sdp_with_transport(type)
              4.10. sdp_with_transport_like(type)
              4.11. sdp_transport(pv)
              4.12. sdp_remove_transport(type)
              4.13. sdp_with_codecs_by_id(list)
              4.14. sdp_with_codecs_by_name(list)
              4.15. sdp_print(level)
              4.16. sdp_get(avpvar)
              4.17. sdp_content([sloppy])
              4.18. sdp_with_ice()
              4.19. sdp_get_line_startswith(avpvar, string)
              4.20. sdp_get_address_family()
              4.21. sdp_iterator_start(iname)
              4.22. sdp_iterator_end(iname)
              4.23. sdp_iterator_next(iname)
              4.24. sdp_iterator_rm(iname)
              4.25. sdp_iterator_append(iname, text)
              4.26. sdp_iterator_insert(iname, text)

        5. Exported Variables

              5.1. $sdp( )
              5.2. $sdpitval( )

   List of Examples

   1.1. sdp_remove_codecs_by_id usage
   1.2. sdp_remove_codecs_by_name usage
   1.3. sdp_remove_line_by_prefix usage
   1.4. sdp_keep_codecs_by_id usage
   1.5. sdp_keep_codecs_by_name usage
   1.6. sdp_with_media usage
   1.7. sdp_with_active_media usage
   1.8. sdp_remove_media usage
   1.9. sdp_with_transport usage
   1.10. sdp_with_transport_like usage
   1.11. sdp_transport usage
   1.12. sdp_remove_transport usage
   1.13. sdp_with_codecs_by_id usage
   1.14. sdp_with_codecs_by_name usage
   1.15. sdp_print usage
   1.16. sdp_get usage
   1.17. sdp_content usage
   1.18. sdp_with_ice usage
   1.19. sdp_get_line_startswith usage
   1.20. sdp_get_address_familyusage
   1.21. sdp_iterator_start usage
   1.22. sdp_iterator_end usage
   1.23. sdp_iterator_next usage
   1.24. sdp_iterator_rm usage
   1.25. sdp_iterator_append usage
   1.26. sdp_iterator_insert usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters
   4. Functions

        4.1. sdp_remove_codecs_by_id(list [, mtype])
        4.2. sdp_remove_codecs_by_name(list [, mtype])
        4.3. sdp_remove_line_by_prefix(string [, mtype])
        4.4. sdp_keep_codecs_by_id(list [, mtype])
        4.5. sdp_keep_codecs_by_name(list [, mtype])
        4.6. sdp_with_media(type)
        4.7. sdp_with_active_media(type)
        4.8. sdp_remove_media(type)
        4.9. sdp_with_transport(type)
        4.10. sdp_with_transport_like(type)
        4.11. sdp_transport(pv)
        4.12. sdp_remove_transport(type)
        4.13. sdp_with_codecs_by_id(list)
        4.14. sdp_with_codecs_by_name(list)
        4.15. sdp_print(level)
        4.16. sdp_get(avpvar)
        4.17. sdp_content([sloppy])
        4.18. sdp_with_ice()
        4.19. sdp_get_line_startswith(avpvar, string)
        4.20. sdp_get_address_family()
        4.21. sdp_iterator_start(iname)
        4.22. sdp_iterator_end(iname)
        4.23. sdp_iterator_next(iname)
        4.24. sdp_iterator_rm(iname)
        4.25. sdp_iterator_append(iname, text)
        4.26. sdp_iterator_insert(iname, text)

   5. Exported Variables

        5.1. $sdp( )
        5.2. $sdpitval( )

1. Overview

   This module provides functions for checking and managing the SDP
   payloads of SIP messages.

   Examples of functions this module offers: remove codecs from SDP, check
   the media stream types and return attributes of SDP document. For the
   full list of the features provided by this module and the
   implementation state, please read the list of exported functions.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None

3. Parameters

   The module does not export any config parameters yet.

4. Functions

   4.1. sdp_remove_codecs_by_id(list [, mtype])
   4.2. sdp_remove_codecs_by_name(list [, mtype])
   4.3. sdp_remove_line_by_prefix(string [, mtype])
   4.4. sdp_keep_codecs_by_id(list [, mtype])
   4.5. sdp_keep_codecs_by_name(list [, mtype])
   4.6. sdp_with_media(type)
   4.7. sdp_with_active_media(type)
   4.8. sdp_remove_media(type)
   4.9. sdp_with_transport(type)
   4.10. sdp_with_transport_like(type)
   4.11. sdp_transport(pv)
   4.12. sdp_remove_transport(type)
   4.13. sdp_with_codecs_by_id(list)
   4.14. sdp_with_codecs_by_name(list)
   4.15. sdp_print(level)
   4.16. sdp_get(avpvar)
   4.17. sdp_content([sloppy])
   4.18. sdp_with_ice()
   4.19. sdp_get_line_startswith(avpvar, string)
   4.20. sdp_get_address_family()
   4.21. sdp_iterator_start(iname)
   4.22. sdp_iterator_end(iname)
   4.23. sdp_iterator_next(iname)
   4.24. sdp_iterator_rm(iname)
   4.25. sdp_iterator_append(iname, text)
   4.26. sdp_iterator_insert(iname, text)

4.1.  sdp_remove_codecs_by_id(list [, mtype])

   Remove the codecs provided in the parameter 'list' from all media
   streams found in SDP payload. The parameter 'list' must be one item or
   a comma separated list of numeric codec IDs. The parameter can be a
   static string or a variable holding the list of numeric codec IDs.

   This function can be used from ANY_ROUTE.

   Example 1.1. sdp_remove_codecs_by_id usage
...
# remove PCMU
sdp_remove_codecs_by_id("0");
# remove PCMU, PCMA and GSM
sdp_remove_codecs_by_id("0,8,3");
sdp_remove_codecs_by_id("17", "audio");
sdp_remove_codecs_by_id("23", "video");
...

4.2.  sdp_remove_codecs_by_name(list [, mtype])

   Remove the codecs provided in the parameter 'list' from all media
   streams found in SDP payload. The parameter 'list' must be one item or
   a comma separated list of codec names. The parameter can be a static
   string or a variable holding the list of codec names.

   Optional parameter mtype can be provided to apply the operations only
   to the streams matching m=mtype.

   This function can be used from ANY_ROUTE.

   Example 1.2. sdp_remove_codecs_by_name usage
...
# remove PCMU
sdp_remove_codecs_by_name("PCMU");
# remove PCMU, PCMA and GSM
sdp_remove_codecs_by_name("PCMU,PCMA,GSM");
...

4.3.  sdp_remove_line_by_prefix(string [, mtype])

   Remove all SDP attribute lines beginning with 'string' in all media
   streams.

   Optional parameter mtype can be provided to apply the operations only
   to the streams matching m=mtype.

   This function can be used from ANY_ROUTE.

   Example 1.3. sdp_remove_line_by_prefix usage
...
if ($si == "2001:DB8::8:800:200C:417A"
        and ( has_body("application/sdp") or has_body("multipart/mixed")))
{
    xlog("L_INFO", "Cleaning ugly SDP from $si\n");
    sdp_remove_codecs_by_name("X-NSE");
    sdp_remove_line_by_prefix("a=X-");
}

...

4.4.  sdp_keep_codecs_by_id(list [, mtype])

   Keep only the codecs provided in the parameter 'list' from all media
   streams found in SDP payload. The parameter 'list' must be one item or
   a comma separated list of numeric codec IDs. The parameter can be a
   static string or a variable holding the list of numeric codec IDs.

   Optional parameter mtype can be provided to apply the operations only
   to the streams matching m=mtype.

   This function can be used from ANY_ROUTE.

   Example 1.4. sdp_keep_codecs_by_id usage
...
# keep only PCMU
sdp_keep_codecs_by_id("0");
# keep PCMU, PCMA and GSM in audio stream
sdp_keep_codecs_by_id("0,8,3", "audio");
...

4.5.  sdp_keep_codecs_by_name(list [, mtype])

   Keep only the codecs provided in the parameter 'list' from all media
   streams found in SDP payload. The parameter 'list' must be one or a
   comma separated list of codec names. The parameter can be a static
   string or a variable holding the list of codec names.

   Note that you have to explicitly keep 'telephone-event' in the list of
   names if you want to keep DTMF attributes.

   Optional parameter mtype can be provided to apply the operations only
   to the streams matching m=mtype.

   This function can be used from ANY_ROUTE.

   Example 1.5. sdp_keep_codecs_by_name usage
...
# keep only PCMU
sdp_keep_codecs_by_name("PCMU");
# keep PCMU, PCMA and GSM
sdp_keep_codecs_by_name("PCMU,PCMA,GSM");
...

4.6.  sdp_with_media(type)

   Return true if the SDP has 'media=type ...' line. Useful to check the
   content of the RTP sessions, such as 'audio' or 'video'. The parameter
   can be static string or variable holding the media type.

   This function can be used from ANY_ROUTE.

   Example 1.6. sdp_with_media usage
...
# check for video stream
if(sdp_with_media("video"))
{
    # the session has a video stream
}
...

4.7.  sdp_with_active_media(type)

   Return true if the SDP has 'media=type ...' line and the media is
   active. Useful to check the content of the RTP sessions, such as
   'audio' or 'video'. Active media means the port is non-zero and the
   direction is not "inactive" The parameter can be static string or
   variable holding the media type.

   This function can be used from ANY_ROUTE.

   Example 1.7. sdp_with_active_media usage
...
# check for active video stream
if(sdp_with_active_media("video"))
{
    # the session has an active video stream
}
...

4.8.  sdp_remove_media(type)

   Remove the streams that match on 'm=type ...' line. The parameter can
   be static string or variable holding the media type.

   Note: If this is executed on a request, the callee should reply without
   the Media too. However, RFC 3264 mandates, that the reply should
   contain the exact same number of "m=" lines as the request.


   6 Generating the Answer

   [...]

   For each "m=" line in the offer, there MUST be a corresponding "m="
   line in the answer. The answer MUST contain exactly the same number of
   "m=" lines as the offer. This allows for streams to be matched up based
   on their order. This implies that if the offer contained zero "m="
   lines, the answer MUST contain zero "m=" lines.

     --RFC 3264

   So this may not work with all Endpoints, especially if they follow RFC
   3264 precisely (e.g. JSSIP).

   This function can be used from ANY_ROUTE.

   Example 1.8. sdp_remove_media usage
...
# remove video stream
sdp_remove_media("video");
...

4.9.  sdp_with_transport(type)

   Return true if the SDP has 'media=media port type ...' line. Useful to
   check the transport of the RTP sessions, such as 'RTP/AVP', 'RTP/SAVP',
   'RTP/SAVPF' or 'UDP/TLS/RTP/SAVPF'. The parameter can be static string
   or variable holding the transport type. The function does an exact
   match of the strings.

   This function can be used from ANY_ROUTE.

   Example 1.9. sdp_with_transport usage
...
# check for RTP/SAVP stream
if(sdp_with_transport("UDP/TLS/RTP/SAVPF"))
{
    # the session has a UDP/TLS/RTP/SAVPF stream
}
...

4.10.  sdp_with_transport_like(type)

   Returns true if the SDP has 'media=media port type ...' line, where
   type contains the string in the parameter. The parameter can be static
   string or variable holding a string.

   This function can be used from ANY_ROUTE.

   Example 1.10. sdp_with_transport_like usage
...
# check for SAVPF stream
if(sdp_with_transport_like("SAVPF"))
{
    # the session has a SAVPF stream, e.g., RTP/SAVPF or UDP/TLS/RTP/SAVPF
}
...

4.11.  sdp_transport(pv)

   Assigns common media transport (if any) of 'm' lines to pv argument.
   Returns 1 if common media transport was found, -2 if there was no
   common media transport, and -1 in case of error.

   This function can be used from ANY_ROUTE.

   Example 1.11. sdp_transport usage
...
sdp_transport("$avp(caller_rtp_transport)");
...

4.12.  sdp_remove_transport(type)

   Remove the streams that match on 'm=media port type ...' line. The
   parameter can be static string or variable holding the transport type.

   This function can be used from ANY_ROUTE.

   Example 1.12. sdp_remove_transport usage
...
# remove stream with transport RTP/AVP
sdp_remove_transport("RTP/AVP");
...

4.13.  sdp_with_codecs_by_id(list)

   Returns true if any of the codecs provided in the parameter 'list' from
   all media streams is found in SDP payload. The parameter 'list' must be
   one or a comma separated list of numeric codec IDs. The parameter can
   be a static string or a variable holding the list of numeric codec IDs.

   This function can be used from ANY_ROUTE.

   Example 1.13. sdp_with_codecs_by_id usage
...
# test for PCMU
if(sdp_with_codecs_by_id("0")) { ... }
# test for PCMU, PCMA or GSM
if(sdp_with_codecs_by_id("0,8,3")) { ... }
...

4.14.  sdp_with_codecs_by_name(list)

   Returns true if any of the codecs provided in the parameter 'list' from
   all media streams is found in SDP payload. The parameter 'list' must be
   one item or a comma separated list of codec names. The parameter can be
   a static string or a variable holding the list of codec names.

   This function can be used from ANY_ROUTE.

   Example 1.14. sdp_with_codecs_by_name usage
...
# test for PCMU
if(sdp_with_codecs_by_name("PCMU")) { ... }
# test for PCMU, PCMA or GSM
if(sdp_with_codecs_by_name("PCMU,PCMA,GSM")) { ... }
...

4.15.  sdp_print(level)

   Print the SDP internal structure to log 'level'. The parameter can be
   static integer or variable holding the integer value of the log level.

   This function can be used from ANY_ROUTE.

   Example 1.15. sdp_print usage
...
# print the SDP
sdp_print("1");
...

4.16.  sdp_get(avpvar)

   Store the SDP part of message body in an AVP. Return 1 if SDP is found,
   -1 on error and -2 if there is no SDP part in the message body.

   This function can be used from ANY_ROUTE.

   Example 1.16. sdp_get usage
...
sdp_get("$avp(sdp)");
...

4.17.  sdp_content([sloppy])

   Return true if the SIP message has SDP body or a SDP part in body. If
   an argument is given, the function does not parse message body, but
   returns true if Content-Type is "application/sdp" or if that string
   exists in "multipart/mixed" body.

   This function can be used from ANY_ROUTE.

   Example 1.17. sdp_content usage
...
if(sdp_content()) {
    ...
}
...

4.18.  sdp_with_ice()

   Return true if the SIP message has SDP body that contains ICE candidate
   attribute(s).

   This function can be used from ANY_ROUTE.

   Example 1.18. sdp_with_ice usage
...
if(sdp_with_ice()) {
    ...
}
...

4.19.  sdp_get_line_startswith(avpvar, string)

   Store the search part of SDP body message with line beginning with
   'string' in an AVP. Return 1 if 'string' is found in SDP, -1 on error
   and -2 if there is no SDP part in the message body. The second
   parameter can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.19. sdp_get_line_startswith usage
...
if(sdp_get_line_startswith("$avp(mline)", "m=")) {
        xlog("m-line: $avp(mline)\n");
}
...

4.20.  sdp_get_address_family()

   It helps to get IP address family at c line from sdp body. It returns
   -1 on error, 4 for IP4 and 6 for IP6

   Example 1.20. sdp_get_address_familyusage
...
if(is_method("INVITE") && has_body("application/sdp")){
        $avp(af) = sdp_get_address_family();
        xlog("L_INFO","ADDRESS FAMILY OF SDP C line $avp(af) ");
}
...

4.21.  sdp_iterator_start(iname)

   Start an iterator for lines in the body of the current SIP message. The
   parameter iname is used to identify the iterator. There can be up to 4
   iterators at the same time, with different name.

   The parameter can be a dynamic string with variables.

   This function can be used from ANY_ROUTE.

   Example 1.21. sdp_iterator_start usage
...
sdp_iterator_start("s1");
...

4.22.  sdp_iterator_end(iname)

   Close the iterator identified by iname parameter. The iname value must
   be the same used for sdp_iterator_start().

   The parameter can be dynamic string with variables.

   This function can be used from ANY_ROUTE.

   Example 1.22. sdp_iterator_end usage
...
sdp_iterator_end("s1");
...

4.23.  sdp_iterator_next(iname)

   Move the iterator to the next line in the body. It must be called also
   after sdp_iterator_start() to get the first header.

   The return code is false when there is no other header in the list.

   The SDP line is accessible via variable $sdpitval(iname) - it contains
   also the EOL chars.

   The parameter can be dynamic string with variables.

   This function can be used from ANY_ROUTE.

   Example 1.23. sdp_iterator_next usage
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        xlog("body line: $sdpitval(s1)");
    }
    sdp_iterator_end("s1");
...

4.24.  sdp_iterator_rm(iname)

   Remove the body line at the current iterator position.

   The parameter can be dynamic string with variables.

   This function can be used from ANY_ROUTE.

   Example 1.24. sdp_iterator_rm usage
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        if($sdpitval(s1)=~"abc") {
            sdp_iterator_rm("s1");
        }
    }
    sdp_iterator_end("s1");
...

4.25.  sdp_iterator_append(iname, text)

   Add text after the line at the current iterator possition.

   The parameters can be dynamic strings with variables.

   This function can be used from ANY_ROUTE.

   Example 1.25. sdp_iterator_append usage
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        if($sdpitval(s1)=~"^a=info:xyz") {
            sdp_iterator_append("s1", "a=info:abc\r\n");
            break;
        }
    }
    sdp_iterator_end("s1");
...

4.26.  sdp_iterator_insert(iname, text)

   Add text before the line at the current iterator possition.

   The parameters can be dynamic strings with variables.

   This function can be used from ANY_ROUTE.

   Example 1.26. sdp_iterator_insert usage
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        if($sdpitval(s1)=~"^a=info:xyz") {
            sdp_iterator_insert("s1", "a=info:abc\r\n");
            break;
        }
    }
    sdp_iterator_end("s1");
...

5. Exported Variables

   5.1. $sdp( )
   5.2. $sdpitval( )

5.1. $sdp( )

   Access to SDP attributes
     * $sdp(body) - full SDP body (read only)
     * $sdp(sess_version) - sess-version -attribute from SDP o= -line.
       When set to special value -1, current value is incremented. (read +
       write)
     * $sdp(c:ip) - connection IP (read only) - taken from first media
       strea if specified, otherwise from first session.

   Exported pseudo-variables are also documented at
   https://www.kamailio.org/wikidocs/

5.2. $sdpitval( )

   Return the value of to SDP line iterator with the given name:
   $sdpitval(name).
