322bd41f70df2c2ce74051bace6d88bd8a6f9443
[sip-router] / modules / textopsx / doc / 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="textopsx.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6     <title>Functions</title>
7
8         <section id="textopsx.msg_apply_changes">
9                 <title>
10                 <function moreinfo="none">msg_apply_changes()</function>
11                 </title>
12                 <para>
13                 Use this function to apply changes performed on SIP request content. Be
14                 careful when using this function;  due to special handling of changes
15                 to the SIP message buffer so far, using this function might change
16                 the behaviour of your config.  Do test your config properly!
17                 </para>
18                 <para>
19                 This function can be used from REQUEST_ROUTE.
20                 </para>
21                 <example>
22                 <title><function>msg_apply_changes()</function> usage</title>
23                 <programlisting format="linespecific">
24 ...
25 append_hf("My-Header: yes\r\n");
26 if(msg_apply_changes())
27 {
28     # msg buffer has a new content
29     if(is_present_hf("My-Header"))
30     {
31         # will get here always
32     }
33 }
34 ...
35 </programlisting>
36                 </example>
37         </section>
38
39     <section id="textopsx.change_reply_status">
40         <title>
41             <function>change_reply_status(code, reason)</function>
42         </title>
43         <para>
44                 Intercept a SIP reply (in an onreply_route) and change its status code 
45                 and reason phrase prior to forwarding it.
46         </para>
47         <para>Meaning of the parameters is as follows:</para>
48         <itemizedlist>
49             <listitem>
50                 <para><emphasis>code</emphasis> - Status code.
51                 </para>
52             </listitem>
53             <listitem>
54                 <para><emphasis>reason</emphasis> - Reason phrase.
55                 </para>
56             </listitem>
57         </itemizedlist>
58                 <para>
59                 This function can be used from ONREPLY_ROUTE.
60                 </para>
61         <example>
62             <title><function>change_reply_status</function> usage</title>
63             <programlisting>
64 ...
65 onreply_route {
66     if (@status == "603") {
67         change_reply_status(404, "Not Found");
68         exit;
69     }
70 }
71 ...
72             </programlisting>
73         </example>
74     </section>
75
76         <section id="textopsx.remove_body">
77                 <title>
78                 <function moreinfo="none">remove_body()</function>
79                 </title>
80                 <para>
81                 Use this function to remove the body of SIP requests or replies.
82                 </para>
83                 <para>
84                 This function can be used from ANY_ROUTE.
85                 </para>
86                 <example>
87                 <title><function>remove_body()</function> usage</title>
88                 <programlisting format="linespecific">
89 ...
90 remove_body();
91 ...
92 </programlisting>
93                 </example>
94         </section>
95
96         <section id="textopsx.keep_hf">
97                 <title>
98                 <function moreinfo="none">keep_hf(regexp)</function>
99                 </title>
100                 <para>
101                         Remove headers that don't match the regular expression regexp.
102                         Several header are ignored always (thus not removed): Via, From,
103                         To, Call-ID, CSeq, Content-Lenght, Content-Type, Max-Forwards,
104                         Contact, Route, Record-Route -- these can be removed one by one
105                         with remove_hf().
106                 </para>
107                 <para>
108                 This function can be used from ANY_ROUTE.
109                 </para>
110                 <example>
111                 <title><function>keep_hf()</function> usage</title>
112                 <programlisting format="linespecific">
113 ...
114 keep_hf("User-Agent");
115 ...
116 </programlisting>
117                 </example>
118         </section>
119
120         <section id="textopsx.fnmatch">
121                 <title>
122                 <function moreinfo="none">fnmatch(value, expr [, flags])</function>
123                 </title>
124                 <para>
125                         Match the value against the expr using shell-style pattern
126                         for file name matching (see man page for C function fnmatch()).
127                         It is known to be faster and use less-memory than regular expressions.
128                 </para>
129                 <para>
130                         Parameter 'flags' is optional and can be 'i' to do case insensitive
131                         matching.
132                 </para>
133                 <para>
134                 This function can be used from ANY_ROUTE.
135                 </para>
136                 <example>
137                 <title><function>fnmatch()</function> usage</title>
138                 <programlisting format="linespecific">
139 ...
140 if(fnmatch("$rU", "123*"))
141 {
142     ...
143 }
144 ...
145 </programlisting>
146                 </example>
147         </section>
148
149     <section id="append_hf_value">
150         <title>
151             <function>append_hf_value(hf, hvalue)</function>
152         </title>
153         <para>
154                 Append new header value after an existing header, if no index acquired append at the end of
155                 list. Note that a header may consist of comma delimited list of values.
156         </para>
157         <para>Meaning of the parameters is as follows:</para>
158         <itemizedlist>
159             <listitem>
160                 <para><emphasis>hf</emphasis> - Header field to be appended. Format: HFNAME [ [IDX] ].
161                 If index is not specified new header is inserted at the end of message.
162                 </para>
163             </listitem>
164             <listitem>
165                 <para><emphasis>hvalue</emphasis> - Value to be added, config var formatting supported.
166                 </para>
167             </listitem>
168         </itemizedlist>
169         <example>
170             <title><function>append_hf_value</function> usage</title>
171             <programlisting>
172 ...
173 append_hf_value("foo", "gogo;stamp=$Ts")   # add new header
174 append_hf_value("foo[1]", "gogo")  # add new value behind first value
175 append_hf_value("foo[-1]", "$var(Bar)") # try add value to the last header, if not exists add new header
176 ...
177             </programlisting>
178         </example>
179     </section>
180
181     <section id="insert_hf_value">
182         <title>
183             <function>insert_hf_value(hf, hvalue)</function>
184         </title>
185         <para>
186                 Insert new header value before an existing header, if no index acquired insert before first
187                 hf header. Note that a header may consist of comma delimited list of values.
188                 To insert value behing last value use <function>appenf_hf_value</function>.
189         </para>
190         <para>Meaning of the parameters is as follows:</para>
191         <itemizedlist>
192             <listitem>
193                 <para><emphasis>hf</emphasis> - Header field to be appended. Format: HFNAME [ [IDX] ].
194                 If index is not specified new header is inserted at the top of message.
195                 </para>
196             </listitem>
197             <listitem>
198                 <para><emphasis>hvalue</emphasis> - Value to be added, config var formatting supported.
199                 </para>
200             </listitem>
201         </itemizedlist>
202         <example>
203             <title><function>insert_hf_value</function> usage</title>
204             <programlisting>
205 ...
206 insert_hf_value("foo[2]", "gogo")
207 insert_hf_value("foo", "$avp(foo)")   # add new header at the top of list
208 insert_hf_value("foo[1]", "gogo") # try add to the first header
209 ...
210             </programlisting>
211         </example>
212     </section>
213
214     <section id="remove_hf_value">
215         <title>
216             <function>remove_hf_value(hf_par)</function>
217         </title>
218         <para>
219                 Remove the header value from existing header, Note that a header may consist of comma delimited list of values.
220         </para>
221         <para>Meaning of the parameters is as follows:</para>
222         <itemizedlist>
223             <listitem>
224                 <para><emphasis>hf_par</emphasis> - Header field/param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ]
225                 If asterisk is specified as index then all values are affected.
226                 </para>
227             </listitem>
228         </itemizedlist>
229         <example>
230             <title><function>remove_hf_value</function> usage</title>
231             <programlisting>
232 ...
233 remove_hf_value("foo")  # remove foo[1]
234 remove_hf_value("foo[*]")  # remove all foo's headers
235 remove_hf_value("foo[-1]") # last foo
236 remove_hf_value("foo.bar")  # delete parameter
237 remove_hf_value("foo[*].bar") # for each foo delete bar parameters
238 ...
239             </programlisting>
240         </example>
241     </section>
242
243     <section id="remove_hf_value2">
244         <title>
245             <function>remove_hf_value2(hf_par)</function>
246         </title>
247         <para>
248                 Remove specified header or parameter. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).
249
250         </para>
251         <para>Meaning of the parameters is as follows:</para>
252         <itemizedlist>
253             <listitem>
254                 <para><emphasis>hf_par</emphasis> - Header/param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ]
255                 If asterisk is specified as index then all values are affected.
256                 </para>
257             </listitem>
258         </itemizedlist>
259         <example>
260             <title><function>remove_hf_value2</function> usage</title>
261             <programlisting>
262 ...
263 remove_hf_value2("foo")  # remove foo[1]
264 remove_hf_value2("foo[*]")  # remove all foo's headers, the same as remove_hf_header("foo[*]");
265 remove_hf_value2("foo[-1]") # last foo
266 remove_hf_value2("foo.bar")  # delete parameter
267 remove_hf_value2("foo[*].bar") # for each foo delete bar parameters
268 ...
269             </programlisting>
270         </example>
271     </section>
272
273     <section id="assign_hf_value">
274         <title>
275             <function>assign_hf_value(hf, hvalue)</function>
276         </title>
277         <para>
278                 Assign value to specified header value / param.
279         </para>
280         <para>Meaning of the parameters is as follows:</para>
281         <itemizedlist>
282             <listitem>
283                         <para><emphasis>hf_para</emphasis> - Header field value / param to be appended.
284                                 Format: HFNAME [ [IDX] ] [. PARAM]
285                 If asterisk is specified as index then all values are affected.
286                 </para>
287             </listitem>
288             <listitem>
289                         <para><emphasis>hvalue</emphasis> - Value to be assigned, config var
290                                 formatting supported. If value is empty then no equal sign apears in param.
291                 </para>
292             </listitem>
293         </itemizedlist>
294         <example>
295             <title><function>assign_hf_value</function> usage</title>
296             <programlisting>
297 ...
298 assign_hf_value("foo", "gogo")  # foo[1]
299 assign_hf_value("foo[-1]", "gogo")  # foo[last_foo]
300
301 assign_hf_value("foo.bar", "")
302 assign_hf_value("foo[3].bar", "")
303 assign_hf_value("foo[*]", "")  # remove all foo's, empty value remains
304 assign_hf_value("foo[*].bar", "")  # set empty value (ex. lr)
305 ...
306             </programlisting>
307         </example>
308     </section>
309
310     <section id="assign_hf_value2">
311         <title>
312             <function>assign_hf_value2(hf, hvalue)</function>
313         </title>
314         <para>
315                 Assign value to specified header. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).
316         </para>
317         <para>Meaning of the parameters is as follows:</para>
318         <itemizedlist>
319             <listitem>
320                 <para><emphasis>hf_para</emphasis> - Header field value / param to be appended. Format: HFNAME [ [IDX] ] [. PARAM]
321                 If asterisk is specified as index then all values are affected.
322                 </para>
323             </listitem>
324             <listitem>
325                         <para><emphasis>hvalue</emphasis> - Value to be assigned, config var formatting supported.
326                                 If value is empty then no equal sign apears in param.
327                 </para>
328             </listitem>
329         </itemizedlist>
330         <example>
331             <title><function>assign_hf_value2</function> usage</title>
332             <programlisting>
333 ...
334 assign_hf_value2("Authorization.integrity-protected", "\"yes\"")
335 assign_hf_value2("foo[-1]", "gogo")  # foo[last_foo]
336 assign_hf_value2("foo[*].bar", "")  # set empty value (ex. lr)
337 ...
338             </programlisting>
339         </example>
340     </section>
341
342     <section id="include_hf_value">
343         <title>
344             <function>include_hf_value(hf, hvalue)</function>
345         </title>
346         <para>
347                 Add value in set if not exists, eg. "Supported: path,100rel".
348         </para>
349         <para>Meaning of the parameters is as follows:</para>
350         <itemizedlist>
351             <listitem>
352                 <para><emphasis>hf</emphasis> - Header field name to be affected.
353                 </para>
354             </listitem>
355             <listitem>
356                 <para><emphasis>hvalue</emphasis> - config var formatting supported.
357                 </para>
358             </listitem>
359         </itemizedlist>
360         <example>
361             <title><function>include_hf_value</function> usage</title>
362             <programlisting>
363 ...
364 include_hf_value("Supported", "path");
365 ...
366             </programlisting>
367         </example>
368     </section>
369
370     <section id="exclude_hf_value">
371         <title>
372             <function>exclude_hf_value(hf, hvalue)</function>
373         </title>
374         <para>
375                 Remove value from set if exists, eg. "Supported: path,100rel".
376         </para>
377         <para>Meaning of the parameters is as follows:</para>
378         <itemizedlist>
379             <listitem>
380                 <para><emphasis>hf</emphasis> - Header field name to be affected.
381                 </para>
382             </listitem>
383             <listitem>
384                 <para><emphasis>hvalue</emphasis> - config formatting supported.
385                 </para>
386             </listitem>
387         </itemizedlist>
388         <example>
389             <title><function>exclude_hf_value</function> usage</title>
390             <programlisting>
391 ...
392 exclude_hf_value("Supported", "100rel");
393 ...
394             </programlisting>
395         </example>
396     </section>
397
398     <section id="hf_value_exists">
399         <title>
400             <function>hf_value_exists(hf, hvalue)</function>
401         </title>
402         <para>
403                 Check if value exists in set. Alternate select <emphasis>@hf_value_exists.HF.VALUE</emphasis>
404                 may be used. It returns one or zero.
405         </para>
406         <para>Meaning of the parameters is as follows:</para>
407         <itemizedlist>
408             <listitem>
409                 <para><emphasis>hf</emphasis> - Header field name to be affected. Underscores are treated as dashes.
410                 </para>
411             </listitem>
412             <listitem>
413                 <para><emphasis>hvalue</emphasis> - config var formatting supported.
414                 </para>
415             </listitem>
416         </itemizedlist>
417         <example>
418             <title><function>hf_value_exists</function> usage</title>
419             <programlisting>
420 ...
421 if (hf_value_exists("Supported", "100rel")) {
422
423 }
424
425 if (@hf_value_exists.supported.path == "1") {
426
427 }
428 ...
429             </programlisting>
430         </example>
431     </section>
432
433         <section>
434         <title>Selects</title>
435     <section id="sel.hf_value">
436         <title>@hf_value</title>
437         <para>
438                 Get value of required header-value or param. Note that functions called 'value2'
439                 works with Authorization-like headers where comma is not treated as value delimiter. Formats:
440                 @hf_value.HFNAME[IDX]    # idx value, negative value counts from bottom
441                 @hf_value.HFNAME.PARAM_NAME
442                 @hf_value.HFNAME[IDX].PARAM_NAME
443                 @hf_value.HFNAME.p.PARAM_NAME  # or .param., useful if requred called "uri", "p", "param"
444                 @hf_value.HFNAME[IDX].p.PARAM_NAME # dtto
445                 @hf_value.HFNAME[IDX].uri # (&lt; &amp; &gt; excluded)
446                 @hf_value.HFNAME[*]     # return comma delimited list of all values (combines headers)
447                 @hf_value.HFNAME        # the same as above [*] but may be parsed by cfg.y
448                 @hf_value.HFNAME[*].uri # return comma delimited list of uris (&lt; &amp; &gt; excluded)
449                 @hf_value.HFNAME.uri    # the same as above [*] but may be parsed by cfg.y
450                 @hf_value.HFNAME[IDX].name  # returns name part, quotes excluded
451                 @hf_value.HFNAME.name   # returns name part of the first value
452
453                 @hf_value2.HFNAME        # returns value of first header
454                 @hf_value2.HFNAME[IDX]   # returns value of idx's header
455                 @hf_value2.HFNAME.PARAM_NAME
456                 @hf_value2.HFNAME[IDX].PARAM_NAME
457
458                 @hf_value.HFNAME[IDX].uri  # return URI, quotes excluded
459                 @hf_value.HFNAME.p.uri  # returns param named uri, not URI itself
460                 @hf_value.HFNAME.p.name # returns param named name, not name itself
461                 @hf_value.HFNAME[IDX].uri.name #  any sel_any_uri nested features may be used
462                 @hf_value.HFNAME[IDX].nameaddr.name # select_any_nameaddr
463         </para>
464         <para>Meaning of the parameters is as follows:</para>
465         <itemizedlist>
466             <listitem>
467                 <para><emphasis>HFNAME</emphasis> - Header field name. Underscores are treated as dashes.
468                 </para>
469             </listitem>
470             <listitem>
471                 <para><emphasis>IDX</emphasis> - Value index, negative value counts from bottom
472                 </para>
473             </listitem>
474             <listitem>
475                 <para><emphasis>PARAM_NAME</emphasis> - name of parameter
476                 </para>
477             </listitem>
478         </itemizedlist>
479         <example>
480             <title><function>@hf_value select</function> usage</title>
481             <programlisting>
482 ...
483 $a = @hf_value.my_header[1].my_param;
484 xplog("L_ERR", "$sel(@hf_value.via[-1]), $sel(@hf_value.from.tag)\n");
485 $b = @hf_value.p_associated_uri;
486
487 xplog("L_ERR", "Route uris: '$sel(@hf_value.route[*].uri)'\n");
488 $rr = @hf_value.route.uri;
489
490 $prt = @hf_value2.authorization.integrity_protected;
491 ...
492             </programlisting>
493         </example>
494     </section>
495     <section id="sel.hf_value2">
496         <title>@hf_value2</title>
497         <para>
498                 TBA.
499         </para>
500     </section>
501     <section id="sel.hf_value_exists">
502         <title>@hf_value_exists</title>
503         <para>
504                 TBA.
505         </para>
506     </section>
507
508     </section>
509
510 </section>