<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module provides functions for checking and managing the
		<acronym>SDP</acronym> payloads of SIP messages.
	</para>
	<para>
		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.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
		<para>
		The module does not export any config parameters yet.
		</para>
	</section>

	<section>
	<title>Functions</title>
	<section id="sdpops.f.remove_codecs_by_id">
	    <title>
		<function moreinfo="none">sdp_remove_codecs_by_id(list [, mtype])</function>
	    </title>
	    <para>
			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.
	    </para>
	    <para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_remove_codecs_by_id</function> usage</title>
		<programlisting format="linespecific">
...
# 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");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.remove_codecs_by_name">
	    <title>
		<function moreinfo="none">sdp_remove_codecs_by_name(list [, mtype])</function>
	    </title>
	    <para>
			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.
	    </para>
		<para>
			Optional parameter mtype can be provided to apply the operations
			only to the streams matching m=mtype.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_remove_codecs_by_name</function> usage</title>
		<programlisting format="linespecific">
...
# remove PCMU
sdp_remove_codecs_by_name("PCMU");
# remove PCMU, PCMA and GSM
sdp_remove_codecs_by_name("PCMU,PCMA,GSM");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.remove_line_by_prefix">
	<title>
		<function moreinfo="none">sdp_remove_line_by_prefix(string [, mtype])</function>
	</title>
	<para>
			Remove all SDP attribute lines beginning with 'string'
			in all media streams.
	</para>
		<para>
			Optional parameter mtype can be provided to apply the operations
			only to the streams matching m=mtype.
	    </para>
	<para>
			This function can be used from ANY_ROUTE.
	</para>
	<example>
	<title><function>sdp_remove_line_by_prefix</function> usage</title>
	<programlisting format="linespecific">
...
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-");
}

...
</programlisting>
	</example>
        </section>
	<section id="sdpops.f.keep_codecs_by_id">
	    <title>
		<function moreinfo="none">sdp_keep_codecs_by_id(list [, mtype])</function>
	    </title>
	    <para>
			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.
	    </para>
		<para>
			Optional parameter mtype can be provided to apply the operations
			only to the streams matching m=mtype.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_keep_codecs_by_id</function> usage</title>
		<programlisting format="linespecific">
...
# 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");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.keep_codecs_by_name">
	    <title>
		<function moreinfo="none">sdp_keep_codecs_by_name(list [, mtype])</function>
	    </title>
	    <para>
			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.
	    </para>
		<para>
			Note that you have to explicitly keep 'telephone-event' in the list
			of names if you want to keep DTMF attributes.
	    </para>
		<para>
			Optional parameter mtype can be provided to apply the operations
			only to the streams matching m=mtype.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_keep_codecs_by_name</function> usage</title>
		<programlisting format="linespecific">
...
# keep only PCMU
sdp_keep_codecs_by_name("PCMU");
# keep PCMU, PCMA and GSM
sdp_keep_codecs_by_name("PCMU,PCMA,GSM");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_media">
	    <title>
		<function moreinfo="none">sdp_with_media(type)</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_media</function> usage</title>
		<programlisting format="linespecific">
...
# check for video stream
if(sdp_with_media("video"))
{
    # the session has a video stream
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_active_media">
	    <title>
		<function moreinfo="none">sdp_with_active_media(type)</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_active_media</function> usage</title>
		<programlisting format="linespecific">
...
# check for active video stream
if(sdp_with_active_media("video"))
{
    # the session has an active video stream
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_remove_media">
	    <title>
		<function moreinfo="none">sdp_remove_media(type)</function>
	    </title>
	    <para>
		Remove the streams that match on 'm=type ...' line. The
		parameter can be static string or variable holding the media type.
	    </para>
            <para>
		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.
            </para>
<blockquote><attribution>RFC 3264</attribution>
            <para>
6 Generating the Answer
	    </para>
            <para>
   [...]
	    </para>
            <para>
   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.
            </para>
</blockquote>
            <para>
		So this may not work with all Endpoints, especially if they
		follow RFC 3264 precisely (e.g. JSSIP).
            </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_remove_media</function> usage</title>
		<programlisting format="linespecific">
...
# remove video stream
sdp_remove_media("video");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_transport">
	    <title>
		<function moreinfo="none">sdp_with_transport(type)</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_transport</function> usage</title>
		<programlisting format="linespecific">
...
# check for RTP/SAVP stream
if(sdp_with_transport("UDP/TLS/RTP/SAVPF"))
{
    # the session has a UDP/TLS/RTP/SAVPF stream
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_transport_like">
	    <title>
		<function moreinfo="none">sdp_with_transport_like(type)</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_transport_like</function> usage</title>
		<programlisting format="linespecific">
...
# 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
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_transport">
	    <title>
		<function moreinfo="none">sdp_transport(pv)</function>
	    </title>
	    <para>
		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.
	    </para>
	    <para>
		  This function can be used from ANY_ROUTE.
	    </para>
	    <example>
	      <title><function>sdp_transport</function> usage</title>
	      <programlisting format="linespecific">
...
sdp_transport("$avp(caller_rtp_transport)");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_remove_transport">
	    <title>
		<function moreinfo="none">sdp_remove_transport(type)</function>
	    </title>
	    <para>
		Remove the streams that match on 'm=media port type ...' line. The
		parameter can be static string or variable holding the transport type.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_remove_transport</function> usage</title>
		<programlisting format="linespecific">
...
# remove stream with transport RTP/AVP
sdp_remove_transport("RTP/AVP");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_codecs_by_id">
	    <title>
		<function moreinfo="none">sdp_with_codecs_by_id(list)</function>
	    </title>
	    <para>
			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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_codecs_by_id</function> usage</title>
		<programlisting format="linespecific">
...
# 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")) { ... }
...
</programlisting>
	    </example>
	</section>
	<section id="sdspops.f.sdp.with_codecs_by_name">
	    <title>
		<function moreinfo="none">sdp_with_codecs_by_name(list)</function>
	    </title>
	    <para>
			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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_codecs_by_name</function> usage</title>
		<programlisting format="linespecific">
...
# 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")) { ... }
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_print">
	    <title>
		<function moreinfo="none">sdp_print(level)</function>
	    </title>
	    <para>
		Print the SDP internal structure to log 'level'. The
		parameter can be static integer or variable holding the integer
		value of the log level.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_print</function> usage</title>
		<programlisting format="linespecific">
...
# print the SDP
sdp_print("1");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_get">
	    <title>
		<function moreinfo="none">sdp_get(avpvar)</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_get</function> usage</title>
		<programlisting format="linespecific">
...
sdp_get("$avp(sdp)");
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_content">
	    <title>
		<function moreinfo="none">sdp_content([sloppy])</function>
	    </title>
	    <para>
		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.
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_content</function> usage</title>
		<programlisting format="linespecific">
...
if(sdp_content()) {
    ...
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_with_ice">
	    <title>
		<function moreinfo="none">sdp_with_ice()</function>
	    </title>
	    <para>
		Return true if the SIP message has SDP body that contains ICE candidate attribute(s).
	    </para>
		<para>
			This function can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>sdp_with_ice</function> usage</title>
		<programlisting format="linespecific">
...
if(sdp_with_ice()) {
    ...
}
...
</programlisting>
	    </example>
	</section>
	<section id="sdpops.f.sdp_get_line_startswith">
		<title>
			<function moreinfo="none">sdp_get_line_startswith(avpvar, string)</function>
		</title>
		<para>
			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.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
			<title><function>sdp_get_line_startswith</function> usage</title>
			<programlisting format="linespecific">
...
if(sdp_get_line_startswith("$avp(mline)", "m=")) {
	xlog("m-line: $avp(mline)\n");
}
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_get_address_family">
			<title>
		<function moreinfo="none">sdp_get_address_family()</function>
			</title>
			<para>
			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
			</para>
		<example>
		<title><function>sdp_get_address_family</function>usage</title>
		<programlisting>
<![CDATA[
...
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) ");
}
...
]]>
		</programlisting>
			</example>
	</section>
	<section id="sdpops.f.sdp_iterator_start">
		<title>
		<function moreinfo="none">sdp_iterator_start(iname)</function>
		</title>
		<para>
			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.
		</para>
		<para>
			The parameter can be a dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_start</function> usage</title>
		<programlisting format="linespecific">
...
sdp_iterator_start("s1");
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_iterator_end">
		<title>
		<function moreinfo="none">sdp_iterator_end(iname)</function>
		</title>
		<para>
			Close the iterator identified by iname parameter. The iname value
			must be the same used for sdp_iterator_start().
		</para>
		<para>
			The parameter can be dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_end</function> usage</title>
		<programlisting format="linespecific">
...
sdp_iterator_end("s1");
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_iterator_next">
		<title>
		<function moreinfo="none">sdp_iterator_next(iname)</function>
		</title>
		<para>
			Move the iterator to the next line in the body. It must
			be called also after sdp_iterator_start() to get the first
			header.
		</para>
		<para>
			The return code is false when there is no other header in the list.
		</para>
		<para>
			The SDP line is accessible via variable $sdpitval(iname) - it contains
			also the EOL chars.
		</para>
		<para>
			The parameter can be dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_next</function> usage</title>
		<programlisting format="linespecific">
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        xlog("body line: $sdpitval(s1)");
    }
    sdp_iterator_end("s1");
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_iterator_rm">
		<title>
		<function moreinfo="none">sdp_iterator_rm(iname)</function>
		</title>
		<para>
			Remove the body line at the current iterator position.
		</para>
		<para>
			The parameter can be dynamic string with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_rm</function> usage</title>
		<programlisting format="linespecific">
...
    sdp_iterator_start("s1");
    while(sdp_iterator_next("s1")) {
        if($sdpitval(s1)=~"abc") {
            sdp_iterator_rm("s1");
        }
    }
    sdp_iterator_end("s1");
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_iterator_append">
		<title>
		<function moreinfo="none">sdp_iterator_append(iname, text)</function>
		</title>
		<para>
			Add text after the line at the current iterator possition.
		</para>
		<para>
			The parameters can be dynamic strings with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_append</function> usage</title>
		<programlisting format="linespecific">
...
    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");
...
</programlisting>
		</example>
	</section>
	<section id="sdpops.f.sdp_iterator_insert">
		<title>
		<function moreinfo="none">sdp_iterator_insert(iname, text)</function>
		</title>
		<para>
			Add text before the line at the current iterator possition.
		</para>
		<para>
			The parameters can be dynamic strings with variables.
		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>sdp_iterator_insert</function> usage</title>
		<programlisting format="linespecific">
...
    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");
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
		<title>Exported Variables</title>
		<section>
			<title><varname>$sdp( )</varname></title>
			<para>Access to SDP attributes</para>
				<itemizedlist>
				<listitem><para>
					<emphasis>$sdp(body)</emphasis> - full SDP body (read only)
				</para></listitem>
				<listitem><para>
					<emphasis>$sdp(sess_version)</emphasis> - sess-version -attribute
					from SDP o= -line. When set to special value -1, current value
					is incremented. (read + write)
				</para></listitem>
				<listitem><para>
					<emphasis>$sdp(c:ip)</emphasis> - connection IP (read only)
					- taken from first media strea if specified, otherwise from
					first session.
				</para></listitem>
				</itemizedlist>
			<para>
			Exported pseudo-variables are also documented at &kamwikilink;
			</para>
		</section>
		<section>
			<title><varname>$sdpitval( )</varname></title>
			<para>Return the value of to SDP line iterator with the given
			name: $sdpitval(name).</para>
		</section>
	</section>

</chapter>
