mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
541 lines
15 KiB
541 lines
15 KiB
<?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 "../../../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)</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");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="sdpops.f.remove_codecs_by_name">
|
|
<title>
|
|
<function moreinfo="none">sdp_remove_codecs_by_name(list)</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>
|
|
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)</function>
|
|
</title>
|
|
<para>
|
|
Remove all SDP attribute lines beginning with 'string'
|
|
in all media streams.
|
|
</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 explicitely 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 of 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 of 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>
|
|
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 of the SDP has 'media=media port type ...' line. Useful to check
|
|
the transport of the RTP sessions, such as 'RTP/AVP', 'RTP/SAVP' or 'RTP/SAVPF'. 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_with_transport</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# check for RTP/SAVP stream
|
|
if(sdp_with_transport("RTP/SAVP"))
|
|
{
|
|
# the session has a SRTP/SAVP stream
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="sdpops.f.sdp_with_transport_like">
|
|
<title>
|
|
<function moreinfo="none">sdp_with_transport_like(string)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the SDP has 'media=media port type ...' line,
|
|
where type contains string. 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.
|
|
</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>
|
|
</chapter>
|
|
|