sl: small fix in module README
[sip-router] / src / modules / sl / doc / sl_functions.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <section id="sl.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6
7     <title>Functions</title>
8
9     <section id="sl_send_reply">
10         <title>
11             <function>sl_send_reply(code, reason)</function>
12         </title>
13         <para>
14             For the current request, a reply is sent back having the given code
15             and text reason. The reply is sent stateless, totally independent
16             of the Transaction module and with no retransmission for the
17             INVITE's replies.
18         </para>
19         <para>
20                 If the code is in the range 300-399 (redirect reply), the current
21                 destination set is appended to the reply as Contact headers.
22                 The destination set contains the request URI (R-URI), if it is
23                 modified compared to the received one, plus the branches added to the
24                 request (e.g., after an append_branch() or lookup("location")).
25                 If the R-URI was changed but it is not desired to be part of the
26                 destination set, it can be reverted using the function revert_uri().
27         </para>
28         <para>
29                 Custom headers to the reply can be added using append_to_reply()
30                 function from textops module.
31         </para>
32         <para>Meaning of the parameters is as follows:</para>
33         <itemizedlist>
34             <listitem>
35                 <para><emphasis>code</emphasis> - Return code.
36                 </para>
37             </listitem>
38             <listitem>
39                 <para><emphasis>reason</emphasis> - Reason phrase.
40                 </para>
41             </listitem>
42         </itemizedlist>
43         <example>
44             <title><function>sl_send_reply</function> usage</title>
45             <programlisting>
46 ...
47 sl_send_reply("404", "Not found");
48 ...
49             </programlisting>
50         </example>
51     </section>
52     
53         <section id="send_reply">
54                 <title>
55                 <function moreinfo="none">send_reply(code, reason)</function>
56                 </title>
57                 <para>
58                 For the current request, a reply is sent back having the given code 
59                 and text reason. The reply is sent stateful or stateless, depending of 
60                 the <acronym>TM</acronym> module: if a transaction exists for the current
61                 request, then the reply is sent statefully, otherwise stateless.
62                 </para>
63                 <para>Meaning of the parameters is as follows:</para>
64                 <itemizedlist>
65                 <listitem>
66                         <para><emphasis>code</emphasis> - Return code.
67                         </para>
68                 </listitem>
69                 <listitem>
70                         <para><emphasis>reason</emphasis> - Reason phrase.
71                         </para>
72                 </listitem>
73                 </itemizedlist>
74                 <para>
75                         This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
76                         It can be used on ONREPLY_ROUTE executed by tm module (upon a
77                         t_on_reply() callback).
78                 </para>
79                 <example>
80                 <title><function>send_reply</function> usage</title>
81                 <programlisting format="linespecific">
82 ...
83 send_reply("404", "Not found");
84 ...
85 send_reply("403", "Invalid user - $fU");
86 ...
87 </programlisting>
88                 </example>
89         </section>
90
91     <section id="sl_reply_error">
92         <title>
93             <function>sl_reply_error()</function>
94         </title>
95         <para>
96             Sends back an error reply describing the nature of the last
97             internal error.  Usually this function should be used after a
98             script function that returned an error code.
99         </para>
100         <example>
101             <title><function>sl_reply_error</function> usage</title>
102             <programlisting>
103 ...
104 sl_reply_error();
105 ...
106             </programlisting>
107         </example>
108     </section>
109
110         <section id="sl_forward_reply">
111                 <title>
112                 <function moreinfo="none">sl_forward_reply([ code, [ reason ] ])</function>
113                 </title>
114                 <para>
115                 Forward statelessly the current received SIP reply, with the option to
116                 change the status code and reason text. The new code has to be in the same
117                 class. The received reply is forwarded as well by core when the config
118                 execution ended, unless it is dropped from config.
119                 </para>
120                 <para>Meaning of the parameters is as follows:</para>
121                 <itemizedlist>
122                 <listitem>
123                         <para><emphasis>code</emphasis> - Status code.
124                         </para>
125                 </listitem>
126                 <listitem>
127                         <para><emphasis>reason</emphasis> - Reason phrase.
128                         </para>
129                 </listitem>
130                 </itemizedlist>
131                 <para>
132                         This function can be used from ONREPLY_ROUTE.
133                 </para>
134                 <example>
135                 <title><function>send_reply</function> usage</title>
136                 <programlisting format="linespecific">
137 ...
138 if(status=="408")
139     sl_forward_reply("404", "Not found");
140 ...
141 </programlisting>
142                 </example>
143         </section>
144
145 </section>