Merge pull request #881 from mslehto/doctypo
[sip-router] / modules / rtpproxy / doc / rtpproxy_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14
15         <title>&adminguide;</title>
16
17         <section>
18         <title>Overview</title>
19         <para>
20                 This is a module that enables media streams to be proxied
21                 via an rtpproxy.  Rtpproxies know to work with this module
22                 are Sippy RTPproxy <ulink url="http://www.rtpproxy.org"></ulink>
23                 and ngcp-rtpproxy-ng
24                 <ulink url="http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng"></ulink>.
25                 Some features of the rtpproxy module apply only to one of the two rtpproxies.
26         </para>
27         </section>
28
29         <section>
30         <title>Multiple RTPProxy usage</title>
31         <para>
32                 The rtpproxy module can support multiple rtpproxies for
33                 balancing/distribution and control/selection purposes.
34         </para>
35         <para>
36                 The module allows definition of several sets of rtpproxies.
37                 Load-balancing will be performed over a set and the admin has the
38                 ability to choose what set should be used. The set is selected via
39                 its id - the id being defined with the set. Refer to the
40                 <quote>rtpproxy_sock</quote> module parameter definition for syntax
41                 description.
42         </para>
43         <para>
44                 The balancing inside a set is done automatically by the module based on
45                 the weight of each rtpproxy from the set.
46         </para>
47         <para>
48                 The selection of the set is done from script prior using
49                 unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
50                 functions - see the set_rtp_proxy_set() function.
51         </para>
52         <para>
53                 For backward compatibility reasons, a set with no id take by default
54                 the id 0. Also if no set is explicitly set before
55                 unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
56                 the 0 id set will be used.
57         </para>
58         <para>
59                 IMPORTANT: if you use multiple sets, take care and use the same set for
60                 both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
61         </para>
62         </section>
63
64         <section>
65         <title>Dependencies</title>
66         <section>
67                 <title>&kamailio; Modules</title>
68                 <para>
69                 The following modules must be loaded before this module:
70                         <itemizedlist>
71                         <listitem>
72                         <para>
73                                 <emphasis>tm module</emphasis> - (optional) if you want to
74                                 have rtpproxy_manage() fully functional
75                         </para>
76                         </listitem>
77                         </itemizedlist>
78                 </para>
79         </section>
80         <section>
81                 <title>External Libraries or Applications</title>
82                 <para>
83                 The following libraries or applications must be installed before
84                 running &kamailio; with this module loaded:
85                         <itemizedlist>
86                         <listitem>
87                         <para>
88                                 <emphasis>None</emphasis>.
89                         </para>
90                         </listitem>
91                         </itemizedlist>
92                 </para>
93         </section>
94         </section>
95
96         <section>
97         <title>Parameters</title>
98         <section id="rtpproxy.p.rtpproxy_sock">
99                 <title><varname>rtpproxy_sock</varname> (string)</title>
100                 <para>
101                 Used to define the list of RTPPRoxy instances to connect to.
102                 These can be UNIX sockets or IPv4/IPv6 UDP sockets.
103
104                 Each modparam entry will insert sockets into a single set. If no set ID is given, the default set ID '0' will be used. To define multiple sets add the set number at the beginning of each parameter followed by '=='.
105                 Sockets can be weighted by adding '=#' to a socket where # is an integer. A socket with a weight of 2 will be chosen twice as often as one with a weight of 1.
106                 </para>
107                 <para>
108                 <emphasis>
109                         Default value is <quote>NONE</quote> (disabled).
110                 </emphasis>
111                 </para>
112                 <example>
113                 <title>Set <varname>rtpproxy_sock</varname> parameter</title>
114                 <programlisting format="linespecific">
115 ...
116 # single rtproxy
117 modparam("rtpproxy", "rtpproxy_sock", "udp:localhost:12221")
118
119 # multiple rtproxies for LB
120 modparam("rtpproxy", "rtpproxy_sock",
121         "udp:localhost:12221 udp:localhost:12222")
122
123 # multiple sets of multiple rtproxies
124 modparam("rtpproxy", "rtpproxy_sock",
125         "1 == udp:localhost:12221 udp:localhost:12222")
126 modparam("rtpproxy", "rtpproxy_sock",
127         "2 == udp:localhost:12225")
128 ...
129 </programlisting>
130                 </example>
131         </section>
132         <section id="rtpproxy.p.rtpproxy_disable_tout">
133                 <title><varname>rtpproxy_disable_tout</varname> (integer)</title>
134                 <para>
135                 Once RTPProxy was found unreachable and marked as disabled, the rtpproxy
136                 module will not attempt to establish communication to RTPProxy for
137                 rtpproxy_disable_tout seconds.
138                 </para>
139                 <para>
140                 <emphasis>
141                         Default value is <quote>60</quote>.
142                 </emphasis>
143                 </para>
144                 <example>
145                 <title>Set <varname>rtpproxy_disable_tout</varname> parameter</title>
146                 <programlisting format="linespecific">
147 ...
148 modparam("rtpproxy", "rtpproxy_disable_tout", 20)
149 ...
150 </programlisting>
151                 </example>
152         </section>
153         <section id="rtpproxy.p.rtpproxy_tout">
154                 <title><varname>rtpproxy_tout</varname> (integer)</title>
155                 <para>
156                 Timeout value in waiting for reply from RTPProxy.
157                 </para>
158                 <para>
159                 <emphasis>
160                         Default value is <quote>1</quote>.
161                 </emphasis>
162                 </para>
163                 <example>
164                 <title>Set <varname>rtpproxy_tout</varname> parameter</title>
165                 <programlisting format="linespecific">
166 ...
167 modparam("rtpproxy", "rtpproxy_tout", 2)
168 ...
169 </programlisting>
170                 </example>
171         </section>
172         <section id="rtpproxy.p.rtpproxy_retr">
173                 <title><varname>rtpproxy_retr</varname> (integer)</title>
174                 <para>
175                 How many times the module should retry to send and receive after
176                 timeout was generated.
177                 </para>
178                 <para>
179                 <emphasis>
180                         Default value is <quote>5</quote>.
181                 </emphasis>
182                 </para>
183                 <example>
184                 <title>Set <varname>rtpproxy_retr</varname> parameter</title>
185                 <programlisting format="linespecific">
186 ...
187 modparam("rtpproxy", "rtpproxy_retr", 2)
188 ...
189 </programlisting>
190                 </example>
191         </section>
192         <section id="rtpproxy.p.nortpproxy_str">
193                 <title><varname>nortpproxy_str</varname> (string)</title>
194                 <para>
195                 This parameter sets the SDP attribute used by rtpproxy to mark
196                 the message's SDP attachemnt with information that it have
197                 already been changed.
198                 </para>
199                 <para>
200                 If empty string, no marker will be added or checked.
201                 </para>
202                 <note><para>
203                 The string must be a complete SDP line, including the EOH (\r\n).
204                 </para></note>
205                 <para>
206                 <emphasis>
207                         Default value is <quote>a=nortpproxy:yes\r\n</quote>.
208                 </emphasis>
209                 </para>
210                 <example>
211                 <title>Set <varname>nortpproxy_str</varname> parameter</title>
212                 <programlisting format="linespecific">
213 ...
214 modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
215 ...
216 </programlisting>
217                 </example>
218         </section>
219         <section id="rtpproxy.p.timeout_socket">
220                 <title><varname>timeout_socket</varname> (string)</title>
221                 <para>
222                 The parameter sets the RTP timeout socket, which is transmitted to the RTP-Proxy.
223                 It will be used by the RTP proxy to signal back that a media stream timed
224                 out.
225                 </para>
226                 <para>
227                 If it is an empty string, no timeout socket will be transmitted to the RTP-Proxy.
228                 </para>
229                 <para>
230                 <emphasis>
231                         Default value is <quote></quote> (nothing).
232                 </emphasis>
233                 </para>
234                 <example>
235                 <title>Set <varname>timeout_socket</varname> parameter</title>
236                 <programlisting format="linespecific">
237 ...
238 modparam("rtpproxy", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
239 ...
240 </programlisting>
241                 </example>
242         </section>
243         <section id="rtpproxy.p.ice_candidate_priority_avp">
244                 <title><varname>ice_candidate_priority_avp</varname> (string)</title>
245                 <para>
246                 If specified and if value of the avp value is not 0,
247                 <function>rtpproxy_manage</function> function adds
248                 ICE relay candidate attributes
249                 to sdp stream(s) containing ICE candidate attributes.
250                 </para>
251                 <para>
252                 If value of the avp is 1, added candidates
253                 have high priority.  If value of the avp is 2 (default),
254                 added candidates have low priority.
255                 </para>
256                 <para>
257                 <emphasis>
258                 There is no default value meaning that no ICE relay
259                 candidates are added in any circumstance.
260                 </emphasis>
261                 </para>
262                 <example>
263                 <title>Set <varname>ice_candidate_priority_avp</varname> parameter</title>
264                 <programlisting format="linespecific">
265 ...
266 modparam("rtpproxy", "ice_candidate_priority_avp", "$avp(ice_priority)")
267 ...
268 </programlisting>
269                 </example>
270         </section>
271         <section id="rtpproxy.p.extra_id_pv">
272                 <title><varname>extra_id_pv</varname> (string)</title>
273                 <para>
274                         The parameter sets the PV defination to use when the <quote>b</quote>
275                         parameter is used on unforce_rtp_proxy(), rtpproxy_offer(),
276                         rtpproxy_answer() or rtpproxy_manage() command.
277                 </para><para>
278                         Default is empty, the <quote>b</quote> parameter may not be used then.
279                 </para>
280                 <example>
281                 <title>Set <varname>extra_id_pv</varname> parameter</title>
282                 <programlisting format="linespecific">
283 ...
284 modparam("rtpproxy", "extra_id_pv", "$avp(extra_id)")
285 ...
286 </programlisting>
287                 </example>
288         </section>
289         <section id="rtpproxy.p.db_url">
290                 <title><varname>db_url</varname> (string)</title>
291                 <para>
292                         The database URL to load rtp_proxy sets from.
293                         If this parameter is set, the module will attempt to load the rtpproxy sets from the specified database and will ignore any 'rtpproxy_sock' modparams.
294                 </para>
295                 <para>
296                         Default is empty, a database will not be used.
297                 </para>
298                 <example>
299                 <title>Set <varname>db_url</varname> parameter</title>
300                 <programlisting format="linespecific">
301 ...
302 modparam("rtpproxy", "db_url", "mysql://user:passwb@localhost/database")
303 ...
304 </programlisting>
305                 </example>
306         </section>
307         <section id="rtpproxy.p.table_name">
308                 <title><varname>table_name</varname> (string)</title>
309                 <para>
310                         The name of the table containing the rtpproxy sets.
311                 </para>
312                 <para>
313                         Default value is <quote>rtpproxy</quote>.
314                 </para>
315                 <example>
316                 <title>Set <varname>table_name</varname> parameter</title>
317                 <programlisting format="linespecific">
318 ...
319 modparam("rtpproxy", "table_name", "my_rtpp_sets")
320 ...
321 </programlisting>
322                 </example>
323         </section>
324         <section id="rtpproxy.p.rtp_inst_pvar">
325                 <title><varname>rtp_inst_pvar</varname> (string)</title>
326                 <para>
327                         A pseudo variable to store the chosen RTPProxy address.
328                         If this parameter is set, the instance URL will be stored in the given variable.
329                 </para>
330                 <para>
331                         By default, this parameter is not set.
332                 </para>
333                 <example>
334                 <title>Set <varname>rtp_inst_pvar</varname> parameter</title>
335                 <programlisting format="linespecific">
336 ...
337 modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
338 ...
339 </programlisting>
340                 </example>
341                 <example>
342                 <title><varname>rtp_inst_pvar</varname> usage</title>
343                 <programlisting format="linespecific">
344 modparam("rtpproxy", "rtpproxy_sock",
345         "udp:localhost:12221 udp:localhost:12222")
346 modparam("rtpproxy", "rtp_inst_pvar", "$var(RTP_INSTANCE)")
347 ...
348 rtpproxy_manage("eiro");
349 xlog("L_INFO", "Chose rtpp instance $var(RTP_INSTANCE)\n");
350 # This will display 'udp:localhost:12222'
351 ...
352 </programlisting>
353                 </example>
354         </section>
355         </section>
356
357         <section>
358         <title>Functions</title>
359         <section id="rtpproxy.f.set_rtp_proxy_set">
360                 <title>
361                 <function moreinfo="none">set_rtp_proxy_set(setid)</function>
362                 </title>
363                 <para>
364                 Sets the Id of the rtpproxy set to be used for the next
365                 unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer()
366                 or rtpproxy_manage() command. The parameter can be an integer or
367                 a config variable holding an integer.
368                 </para>
369                 <para>
370                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
371                 BRANCH_ROUTE.
372                 </para>
373                 <example>
374                 <title><function>set_rtp_proxy_set</function> usage</title>
375                 <programlisting format="linespecific">
376 ...
377 set_rtp_proxy_set("2");
378 rtpproxy_offer();
379 ...
380 </programlisting>
381                 </example>
382         </section>
383         <section id="rtpproxy.f.rtpproxy_ofrer">
384                 <title>
385                 <function moreinfo="none">rtpproxy_offer([flags [, ip_address]])</function>
386                 </title>
387                 <para>
388                 Rewrites &sdp; body to ensure that media is passed through
389                 an &rtp; proxy. To be invoked
390                 on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK
391                 when SDPs are in 200 OK and ACK.
392                 </para>
393                 <para>Meaning of the parameters is as follows:</para>
394                 <itemizedlist>
395                 <listitem>
396                         <para>
397                         <emphasis>flags</emphasis> - flags to turn on some features.
398                         </para>
399                         <itemizedlist>
400                                 <listitem><para>
401                                 <emphasis>1</emphasis> - append first Via branch to Call-ID when sending
402                                 command to rtpproxy. This can be used to create one media session per branch
403                                 on the rtpproxy. When sending a subsequent <quote>delete</quote> command to
404                                 the rtpproxy, you can then stop just the session for a specific branch when
405                                 passing the flag '1' or '2' in the <quote>unforce_rtpproxy</quote>, or stop
406                                 all sessions for a call when not passing one of those two flags there. This is
407                                 especially useful if you have serially forked call scenarios where rtpproxy
408                                 gets an <quote>update</quote> command for a new branch, and then a
409                                 <quote>delete</quote> command for the previous branch, which would otherwise
410                                 delete the full call, breaking the subsequent <quote>lookup</quote> for the
411                                 new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
412                                 rtpproxy (now named rtpengine) at the moment!</emphasis>
413                                 </para></listitem>
414                                 <listitem><para>
415                                 <emphasis>2</emphasis> - append second Via branch to Call-ID when sending
416                                 command to rtpproxy. See flag '1' for its meaning.
417                                 </para></listitem>
418                                 <listitem><para>
419                                 <emphasis>3</emphasis> - behave like flag 1 is set for a request and
420                                 like flag 2 is set for a reply.
421                                 </para></listitem>
422                                 <listitem><para>
423                                 <emphasis>a</emphasis> - flags that UA from which message is
424                                 received doesn't support symmetric RTP. (automatically sets the 'r' flag)
425                                 </para></listitem>
426                                 <listitem><para>
427                                 <emphasis>b</emphasis> - append branch specific variable to Call-ID when sending
428                                 command to rtpproxy. This creates one rtpproxy session per unique variable.
429
430                                 Works similar to the 1, 2 and 3 parameter, but is usefull when forking to multiple
431                                 destinations on different address families or network segments, requiring different
432                                 rtpproxy parameters.
433
434                                 The variable value is taken from the <quote>extra_id_pv</quote>.
435
436                                 When used, it must be used in every call to rtpproxy_manage(), rtpproxy_offer(),
437                                 rtpproxy_answer() and rtpproxy_destroy() with the same contents of the PV.
438                                 The b parameter may not be used in conjunction with the 1, 2 or 3 parameter
439                                 to use the Via branch in the Call-ID.
440                                 </para></listitem>
441                                 <listitem><para>
442                                 <emphasis>l</emphasis> - force <quote>lookup</quote>, that is,
443                                 only rewrite SDP when corresponding session already exists
444                                 in the RTP proxy. By default is on when the session is to be
445                                 completed.
446                                 </para></listitem>
447                                 <listitem><para>
448                                 <emphasis>i, e</emphasis> - these flags specify the direction of the SIP
449                                 message. These flags only make sense when rtpproxy is running in bridge mode.
450                                 'i' means internal network (LAN), 'e' means external network (WAN). 'i'
451                                 corresponds to rtpproxy's first interface, 'e' corresponds to rtpproxy's
452                                 second interface. You always have to specify two flags to define
453                                 the incoming network and the outgoing network. For example, 'ie' should be
454                                 used for SIP message received from the local interface and sent out on the
455                                 external interface, and 'ei' vice versa. Other options are 'ii' and 'ee'.
456                                 So, for example if a SIP requests is processed with 'ie' flags, the corresponding
457                                 response must be processed with 'ie' flags.
458                                 </para><para>
459                                 Note: As rtpproxy in bridge mode is asymmetric per default, you have to specify
460                                 the 'w' flag for clients behind NAT! See also above notes!
461                                 </para></listitem>
462                                 <listitem><para>
463                                 <emphasis>x</emphasis> - this flag a shortcut for using the "ie" or "ei"-flags of RTP-Proxy,
464                                 in order to do automatic bridging between IPv4 on the
465                                 "internal network" and IPv6 on the "external network". The distinction is done by
466                                 the given IP in the SDP, e.g. a IPv4 Address will always call "ie" to the RTPProxy
467                                 (IPv4(i) to IPv6(e)) and an IPv6Address will always call "ei" to the RTPProxy (IPv6(e)
468                                 to IPv4(i)).
469                                 </para><para>
470                                 Note: Please note, that this will only work properly with non-dual-stack user-agents or with
471                                 dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
472                                 This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
473                                 having different m-lines with different IP-protocols grouped together.
474                                 </para></listitem>
475                                 <listitem><para>
476                                 <emphasis>f</emphasis> - instructs rtpproxy to ignore marks
477                                 inserted by another rtpproxy in transit to indicate that the
478                                 session is already goes through another proxy. Allows creating
479                                 a chain of proxies.
480                                 </para></listitem>
481                                 <listitem><para>
482                                 <emphasis>r</emphasis> - flags that IP address in SDP should
483                                 be trusted. Without this flag, rtpproxy ignores address in
484                                 the SDP and uses source address of the SIP message as media
485                                 address which is passed to the RTP proxy.
486                                 </para></listitem>
487                                 <listitem><para>
488                                 <emphasis>o</emphasis> - flags that IP from the origin
489                                 description (o=) should be also changed.
490                                 </para></listitem>
491                                 <listitem><para>
492                                 <emphasis>c</emphasis> - flags to change the session-level
493                                 SDP connection (c=) IP if media-description also includes
494                                 connection information.
495                                 </para></listitem>
496                                 <listitem><para>
497                                 <emphasis>w</emphasis> - flags that for the UA from which
498                                 message is received, support symmetric RTP must be forced.
499                                 </para></listitem>
500                                 <listitem><para>
501                                 <emphasis>zNN</emphasis> - requests the RTPproxy to perform
502                                 re-packetization of RTP traffic coming from the UA which
503                                 has sent the current message to increase or decrease payload
504                                 size per each RTP packet forwarded if possible.  The NN is the
505                                 target payload size in ms, for the most codecs its value should
506                                 be in 10ms increments, however for some codecs the increment
507                                 could differ (e.g. 30ms for GSM or 20ms for G.723).  The
508                                 RTPproxy would select the closest value supported by the codec.
509                                 This feature could be used for significantly reducing bandwith
510                                 overhead for low bitrate codecs, for example with G.729 going
511                                 from 10ms to 100ms saves two thirds of the network bandwith.
512                                 </para></listitem>
513                         </itemizedlist>
514                 </listitem>
515                 <listitem><para>
516                 <emphasis>ip_address</emphasis> - new SDP IP address.
517                 </para></listitem>
518                 </itemizedlist>
519                 <para>
520                 This function can be used from ANY_ROUTE.
521                 </para>
522                 <example>
523                 <title><function>rtpproxy_offer</function> usage</title>
524                 <programlisting format="linespecific">
525 route {
526 ...
527     if (is_method("INVITE")) {
528         if (has_body("application/sdp")) {
529             if (rtpproxy_offer())
530                 t_on_reply("1");
531         } else {
532             t_on_reply("2");
533         }
534     }
535     if (is_method("ACK") &amp;&amp; has_body("application/sdp"))
536         rtpproxy_answer();
537 ...
538 }
539
540 onreply_route[1]
541 {
542 ...
543     if (has_body("application/sdp"))
544         rtpproxy_answer();
545 ...
546 }
547
548 onreply_route[2]
549 {
550 ...
551     if (has_body("application/sdp"))
552         rtpproxy_offer();
553 ...
554 }
555 </programlisting>
556                 </example>
557         </section>
558         <section id="rtpproxy.f.rtpproxy_answer">
559                 <title>
560                 <function moreinfo="none">rtpproxy_answer([flags [, ip_address]])</function>
561                 </title>
562                 <para>
563                 Rewrites &sdp; body to ensure that media is passed through
564                 an &rtp; proxy. To be invoked
565                 on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK
566                 when SDPs are in 200 OK and ACK.
567                 </para>
568                 <para>
569                 See rtpproxy_answer() function description above for the meaning of the
570                 parameters.
571                 </para>
572                 <para>
573                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
574                 FAILURE_ROUTE, BRANCH_ROUTE.
575                 </para>
576                 <example>
577                  <title><function>rtpproxy_answer</function> usage</title>
578                 <para>
579                 See rtpproxy_offer() function example above for example.
580                 </para>
581                 </example>
582         </section>
583         <section id="rtpproxy.f.rtpproxy_destroy">
584                 <title>
585                 <function moreinfo="none">rtpproxy_destroy([flags])</function>
586                 </title>
587                 <para>
588                 Tears down the RTPProxy session for the current call.
589                 </para>
590                 <para>
591                 This function can be used from ANY_ROUTE.
592                 </para>
593                 <para>Meaning of the parameters is as follows:</para>
594                 <itemizedlist>
595                 <listitem>
596                         <para>
597                         <emphasis>flags</emphasis> - flags to turn on some features.
598                         </para>
599                         <itemizedlist>
600                                 <listitem><para>
601                                 <emphasis>1</emphasis> - append first Via branch to Call-ID when sending
602                                 command to rtpproxy. This can be used to create one media session per branch
603                                 on the rtpproxy. When sending a subsequent <quote>delete</quote> command to
604                                 the rtpproxy, you can then stop just the session for a specific branch when
605                                 passing the flag '1' or '2' in the <quote>unforce_rtpproxy</quote>, or stop
606                                 all sessions for a call when not passing one of those two flags there. This is
607                                 especially useful if you have serially forked call scenarios where rtpproxy
608                                 gets an <quote>update</quote> command for a new branch, and then a
609                                 <quote>delete</quote> command for the previous branch, which would otherwise
610                                 delete the full call, breaking the subsequent <quote>lookup</quote> for the
611                                 new branch. <emphasis>This flag is only supported by the ngcp-mediaproxy-ng
612                                 rtpproxy (now named rtpengine) at the moment!</emphasis>
613                                 </para></listitem>
614                                 <listitem><para>
615                                 <emphasis>2</emphasis> - append second Via branch to Call-ID when sending
616                                 command to rtpproxy. See flag '1' for its meaning.
617                                 </para></listitem>
618                                 <listitem><para>
619                                 <emphasis>b</emphasis> - append branch specific variable to Call-ID when sending
620                                 command to rtpproxy. See rtpproxy_offer() for details.
621                                 <listitem><para>
622                                 </para></listitem>
623                                 <emphasis>t</emphasis> - do not include To tag to <quote>delete</quote> command to rtpproxy thus causing full call to be deleted. Useful for deleting unused rtpproxy call when 200 OK is received on a branch, where rtpproxy is not needed.
624                                 </para></listitem>
625                         </itemizedlist>
626                 </listitem>
627                 </itemizedlist>
628                 <example>
629                 <title><function>rtpproxy_destroy</function> usage</title>
630                 <programlisting format="linespecific">
631 ...
632 rtpproxy_destroy();
633 ...
634 </programlisting>
635                 </example>
636         </section>
637         <section id="rtpproxy.f.unforce_rtp_proxy">
638                 <title>
639                 <function moreinfo="none">unforce_rtp_proxy()</function>
640                 </title>
641                 <para>
642                         Same as rtpproxy_destroy().
643                 </para>
644         </section>
645
646     <section id="rtpproxy.f.rtpproxy_manage">
647         <title>
648         <function moreinfo="none">rtpproxy_manage([flags [, ip_address]])</function>
649         </title>
650                 <para>
651                 Manage the RTPProxy session - it combines the functionality of
652                 rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
653                 internally based on message type and method which one to execute.
654                 </para>
655                 <para>
656                 It can take the same parameters as <function>rtpproxy_offer().</function>
657                 The flags parameter to rtpproxy_manage() can be a configuration variable
658                 containing the flags as a string.
659                 </para>
660                 <para>
661                 Functionality:
662                 </para>
663                 <itemizedlist>
664                 <listitem>
665                         <para>
666                         If INVITE with SDP, then do <function>rtpproxy_offer()</function>
667                         </para>
668                 </listitem>
669                 <listitem>
670                         <para>
671                         If INVITE with SDP, when the tm module is loaded, mark transaction with
672                         internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
673                         <function>rtpproxy_answer()</function>
674                         </para>
675                 </listitem>
676                 <listitem>
677                         <para>
678                         If ACK with SDP, then do <function>rtpproxy_answer()</function>
679                         </para>
680                 </listitem>
681                 <listitem>
682                         <para>
683                         If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
684                         <function>unforce_rtpproxy()</function>. Be careful with calling
685                         this function after resuming a suspended transaction (e.g., after
686                         t_continue()), because the context of executed route is FAILURE
687                         ROUTE (in other words, rtpproxy_manage() in the route block of
688                         t_continue() does the same as in failure_route).
689                         </para>
690                 </listitem>
691                 <listitem>
692                         <para>
693                         If reply to INVITE with code >= 300 do <function>unforce_rtpproxy()</function>
694                         </para>
695                 </listitem>
696                 <listitem>
697                         <para>
698                         If reply with SDP to INVITE having code 1xx and 2xx, then
699                         do <function>rtpproxy_answer()</function> if the request had SDP or tm is not loaded,
700                         otherwise do <function>rtpproxy_offer()</function>
701                         </para>
702                 </listitem>
703         </itemizedlist>
704
705                 <para>
706                 This function can be used from ANY_ROUTE.
707                 </para>
708                 <example>
709                  <title><function>rtpproxy_manage</function> usage</title>
710                 <programlisting format="linespecific">
711 ...
712 rtpproxy_manage();
713 ...
714 </programlisting>
715                 </example>
716         </section>
717
718         <section id="rtpproxy.f.rtpproxy_stream2uac">
719         <title>
720             <function>rtpproxy_stream2uac(prompt_name, count)</function>,
721         </title>
722         <para>
723             Instruct the RTPproxy to stream prompt/announcement pre-encoded with
724             the makeann command from the RTPproxy distribution. The uac/uas
725             suffix selects who will hear the announcement relatively to the current
726             transaction - UAC or UAS. For example invoking the
727             <function>rtpproxy_stream2uac</function> in the request processing
728             block on ACK transaction will play the prompt to the UA that has
729             generated original INVITE and ACK while
730             <function>rtpproxy_stop_stream2uas</function> on 183 in reply
731             processing block will play the prompt to the UA that has generated 183.
732         </para>
733         <para>
734             Apart from generating announcements, another possible application
735             of this function is implementing music on hold (MOH) functionality.
736             When count is -1, the streaming will be in loop indefinitely until
737             the appropriate <function>rtpproxy_stop_stream2xxx</function> is issued.
738         </para>
739         <para>
740             In order to work correctly, these functions require that a session in the
741             RTPproxy already exists. Also those functions don't alter the SDP, so that
742             they are not a substitute for calling <function>rtpproxy_offer</function>
743             or <function>rtpproxy_answer</function>.
744         </para>
745         <para>
746             This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
747         </para>
748         <para>Meaning of the parameters is as follows:</para>
749         <itemizedlist>
750             <listitem>
751                 <para>
752                     <emphasis>prompt_name</emphasis> - name of the prompt to
753                     stream. Should be either absolute pathname or pathname
754                     relative to the directory where RTPproxy runs.
755                 </para>
756             </listitem>
757             <listitem>
758                 <para>
759                     <emphasis>count</emphasis> - number of times the prompt
760                     should be repeated. A value of -1 means that it will
761                     be streaming in a loop indefinitely, until the appropriate
762                     <function>rtpproxy_stop_stream2xxx</function> is issued.
763                 </para>
764             </listitem>
765         </itemizedlist>
766         <example>
767             <title><function>rtpproxy_stream2xxx</function> usage</title>
768             <programlisting>
769 ...
770     if (is_method("INVITE")) {
771         rtpproxy_offer();
772         if (is_audio_on_hold()) {
773             rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
774         } else {
775             rtpproxy_stop_stream2uas();
776         };
777     };
778 ...
779             </programlisting>
780         </example>
781         </section>
782         <section id="rtpproxy.f.rtpproxy_stream2uas">
783         <title>
784             <function>rtpproxy_stream2uas(prompt_name, count)</function>
785         </title>
786         <para>
787                 See function <function>rtpproxy_stream2uac(prompt_name, count)</function>.
788         </para>
789         </section>
790         <section id="rtpproxy.f.rtpproxy_stop_stream2uac">
791         <title>
792             <function>rtpproxy_stop_stream2uac()</function>,
793         </title>
794         <para>
795             Stop streaming of announcement/prompt/MOH started previously by the
796             respective <function>rtpproxy_stream2xxx</function>.  The uac/uas
797             suffix selects whose announcement relatively to tha current
798             transaction should be stopped - UAC or UAS.
799         </para>
800         <para>
801             These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
802         </para>
803         </section>
804         <section id="rtpproxy.f.start_recording">
805                 <title>
806                 <function moreinfo="none">start_recording()</function>
807                 </title>
808                 <para>
809                 This function will send a signal to the RTP-Proxy to record
810                 the RTP stream on the RTP-Proxy.
811                 <emphasis>This function is only supported by Sippy RTPproxy at the moment!</emphasis>
812                 </para>
813                 <para>
814                 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
815                 </para>
816                 <example>
817                 <title><function>start_recording</function> usage</title>
818                 <programlisting format="linespecific">
819 ...
820 start_recording();
821 ...
822                 </programlisting>
823                 </example>
824         </section>
825         <section id="rtpproxy.f.rtpproxy_stop_stream2uas">
826         <title>
827             <function>rtpproxy_stop_stream2uas(prompt_name, count)</function>
828         </title>
829         <para>
830                 See function <function>rtpproxy_stop_stream2uac(prompt_name, count)</function>.
831         </para>
832         </section>
833
834
835         </section>
836
837         <section>
838                 <title>Exported Pseudo Variables</title>
839                 <section id="rtpproxy.pv.rtpstat">
840                         <title><function moreinfo="none">$rtpstat</function></title>
841                         <para>
842                         Returns the RTP-Statistics from the RTP-Proxy. The RTP-Statistics from the RTP-Proxy
843                         are provided as a string and it does contain several packet-counters. The statistics
844                         must be retrieved before the session is deleted (before <function>unforce_rtpproxy()</function>).
845                         </para>
846
847                 <example>
848                 <title>$rtpstat-Usage</title>
849                 <programlisting format="linespecific">
850 ...
851     append_hf("X-RTP-Statistics: $rtpstat\r\n");
852 ...
853                 </programlisting>
854                 </example>
855                 </section>
856
857         </section>
858
859         <section>
860                 <title><acronym>MI</acronym> Commands</title>
861                 <section>
862                         <title><function moreinfo="none">nh_enable_rtpp</function></title>
863                         <para>
864                         Enables a rtp proxy if parameter value is greater than 0.
865                         Disables it if a zero value is given.
866                         </para>
867                         <para>
868                         The first parameter is the rtp proxy url (exactly as defined in
869                         the config file).
870                         </para>
871                         <para>
872                         The second parameter value must be a number in decimal.
873                         </para>
874                         <para>
875                         NOTE: if a rtpproxy is defined multiple times (in the same or
876                         different sets), all of its instances will be enabled/disabled.
877                         </para>
878                         <example>
879                         <title>
880                         <function moreinfo="none">nh_enable_rtpp</function> usage</title>
881                         <programlisting format="linespecific">
882 ...
883 $ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
884 ...
885                         </programlisting>
886                         </example>
887                 </section>
888
889                         <section>
890                         <title><function moreinfo="none">nh_show_rtpp</function></title>
891                         <para>
892                         Displays all the rtp proxies and their information: set and
893                         status (disabled or not, weight and recheck_ticks).
894                         </para>
895                         <para>
896                         No parameter.
897                         </para>
898                         <example>
899                         <title>
900                                 <function moreinfo="none">nh_show_rtpp</function> usage</title>
901                         <programlisting format="linespecific">
902 ...
903 $ &ctltool; fifo nh_show_rtpp
904 ...
905                         </programlisting>
906                         </example>
907                 </section>
908         </section>
909
910 </chapter>
911