Document rtpproxy_stream2xxx and rtpproxy_stop_stream2xxx.

modules_s/nathelper/doc/functions.xml

@@ -233,4 +233,82 @@ $c2 = @nathelper.rewrite_contact[1].nameaddr.uri;
 	</example>
     </section>
 
+    <section id="rtpproxy_stream2xxx">
+        <title>
+            <function>rtpproxy_stream2uac(prompt_name, count)</function>
+            <function>rtpproxy_stream2uas(prompt_name, count)</function>
+        </title>
+        <para>
+            Instruct the RTPproxy to stream prompt/announcement pre-encoded with
+            the makeann command from the RTPproxy distribution. The uac/uas
+            suffix selects who will hear the announcement relatively to tha current
+            transaction - UAC or UAS. For example invoking the
+            <function>rtpproxy_stream2uac</function> in the request processing
+            block on ACK transaction will play the prompt to the UA that has
+            generated original INVITE and ACK while
+            <function>rtpproxy_stop_stream2uas</function> on 183 in reply
+            processing block will play the prompt to the UA that has generated 183.
+        </para>
+        <para>
+            Apart from generating announcements, another possible application
+            of this function is implementing music on hold (MOH) functionality.
+            When count is -1, the streaming will be in loop indefinitely until
+            the appropriate <function>rtpproxy_stop_stream2xxx</function> is issued.
+        </para>
+        <para>
+            In order to work correctly, functions require that the session in the
+            RTPproxy already exists. Also those functions don't alted SDP, so that
+            they are not substitute for calling <function>rtpproxy_offer</function>,
+            <function>rtpproxy_answer</function> or
+            <function>force_rtp_proxy</function>.
+        </para>
+        <para>Meaning of the parameters is as follows:</para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis>prompt_name</emphasis> - name of the prompt to
+                    stream.  Should be either absolute pathname or pathname
+                    relative to the directory where RTPproxy runs.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis>count</emphasis> - number of times the prompt
+                    should be repeated.  The value of -1 means that it will
+                    be streaming in loop indefinitely, until appropriate
+                    <function>rtpproxy_stop_stream2xxx</function> is issued.
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <example>
+            <title><function>rtpproxy_stream2xxx</function> usage</title>
+            <programlisting>
+...
+      if (method == "INVITE") {
+          rtpproxy_offer();
+          if (detect_hold()) {
+              rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", -1);
+          } else {
+              rtpproxy_stop_stream2uas();
+          };
+      };
+...
+            </programlisting>
+        </example>
+    </section>
+
+    <section id="rtpproxy_stop_stream2xxx">
+        <title>
+            <function>rtpproxy_stop_stream2uac()</function>
+            <function>rtpproxy_stop_stream2uas()</function>
+        </title>
+        <para>
+            Stop streaming of announcement/prompt/MOH started previously by the
+            respective <function>rtpproxy_stream2xxx</function>.  The uac/uas
+            suffix selects whose announcement relatively to tha current
+            transaction should be stopped - UAC or UAS.
+        </para>
+    </section>
+
 </section>