a1001e6003bd87c9f3f0ea50e3783cd2f657a8c9
[sip-router] / modules / textops / doc / textops_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 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19                 The module implements text based operations over the SIP message
20                 processed by &kamailio;. SIP is a text based protocol and the module
21                 provides a large set of very useful functions to manipulate the
22                 message at text level, e.g., regular expression search and replace,
23                 Perl-like substitutions, checks for method type, header presence,
24                 insert of new header and date, etc.
25         </para>
26         <section>
27                 <title>Known Limitations</title>
28                 <para>
29                 search ignores folded lines. For example, 
30                 search(<quote>(From|f):.*@foo.bar</quote>)
31                 doesn't match the following From header field:
32                 </para>
33                 <programlisting format="linespecific">
34 From: medabeda 
35  &lt;sip:medameda@foo.bar&gt;;tag=1234
36 </programlisting>
37         </section>
38         </section>
39
40         <section>
41         <title>Dependencies</title>
42         <section>
43                 <title>&kamailio; Modules</title>
44                 <para>
45                 The following modules must be loaded before this module:
46                         <itemizedlist>
47                         <listitem>
48                         <para>
49                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
50                         </para>
51                         </listitem>
52                         </itemizedlist>
53                 </para>
54         </section>
55         <section>
56                 <title>External Libraries or Applications</title>
57                 <para>
58                 The following libraries or applications must be installed before 
59                 running &kamailio; with this module loaded:
60                         <itemizedlist>
61                         <listitem>
62                         <para>
63                                 <emphasis>None</emphasis>.
64                         </para>
65                         </listitem>
66                         </itemizedlist>
67                 </para>
68         </section>
69         </section>
70
71
72         <section>
73         <title>Functions</title>
74         <section>
75                 <title>
76                 <function moreinfo="none">search(re)</function>
77                 </title>
78                 <para>
79                 Searches for the re in the message.
80                 </para>
81                 <para>Meaning of the parameters is as follows:</para>
82                 <itemizedlist>
83                 <listitem>
84                         <para><emphasis>re</emphasis> - Regular expression.
85                         </para>
86                 </listitem>
87                 </itemizedlist>
88                 <para>
89                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
90                 FAILURE_ROUTE, BRANCH_ROUTE.
91                 </para>
92                 <example>
93                 <title><function>search</function> usage</title>
94                 <programlisting format="linespecific">
95 ...
96 if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
97 ...
98 </programlisting>
99                 </example>
100         </section>
101
102         <section>
103                 <title>
104                 <function moreinfo="none">search_body(re)</function>
105                 </title>
106                 <para>
107                 Searches for the re in the body of the message.
108                 </para>
109                 <para>Meaning of the parameters is as follows:</para>
110                 <itemizedlist>
111                 <listitem>
112                         <para><emphasis>re</emphasis> - Regular expression.
113                         </para>
114                 </listitem>
115                 </itemizedlist>
116                 <para>
117                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
118                 FAILURE_ROUTE, BRANCH_ROUTE.
119                 </para>
120                 <example>
121                 <title><function>search_body</function> usage</title>
122                 <programlisting format="linespecific">
123 ...
124 if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
125 ...
126 </programlisting>
127                 </example>
128         </section>
129
130                 <section>
131                 <title>
132                 <function moreinfo="none">search_hf(hf, re, flags)</function>
133                 </title>
134                 <para>
135                 Searches for the re in the body of a header field.
136                 </para>
137                 <para>Meaning of the parameters is as follows:</para>
138                 <itemizedlist>
139                 <listitem>
140                         <para><emphasis>hf</emphasis> - header field name.
141                         </para>
142                 </listitem>
143                 <listitem>
144                         <para><emphasis>re</emphasis> - regular expression.
145                         </para>
146                 </listitem>
147                 <listitem>
148                         <para><emphasis>flags</emphasis> - control flags - it
149                                 has to be one of: a - all headers matching the
150                                 name; f - only first header matching the name;
151                                 l - only the last header matching the name.
152                         </para>
153                 </listitem>
154                 </itemizedlist>
155                 <para>
156                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
157                 FAILURE_ROUTE, BRANCH_ROUTE.
158                 </para>
159                 <example>
160                 <title><function>search_body</function> usage</title>
161                 <programlisting format="linespecific">
162 ...
163 if ( search_hf("From", ":test@", "a") ) { /*....*/ };
164 ...
165 </programlisting>
166                 </example>
167         </section>
168
169         <section>
170                 <title>
171                 <function moreinfo="none">search_append(re, txt)</function>
172                 </title>
173                 <para>
174                 Searches for the first match of re and appends txt after it.
175                 </para>
176                 <para>Meaning of the parameters is as follows:</para>
177                 <itemizedlist>
178                 <listitem>
179                         <para><emphasis>re</emphasis> - Regular expression.
180                         </para>
181                 </listitem>
182                 <listitem>
183                         <para><emphasis>txt</emphasis> - String to be appended.
184                         </para>
185                 </listitem>
186                 </itemizedlist>
187                 <para>
188                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
189                 FAILURE_ROUTE, BRANCH_ROUTE.
190                 </para>
191                 <example>
192                 <title><function>search_append</function> usage</title>
193                 <programlisting format="linespecific">
194 ...
195 search_append("[Oo]pen[Ss]er", " SIP Proxy");
196 ...
197 </programlisting>
198                 </example>
199         </section>
200
201         <section>
202                 <title>
203                 <function moreinfo="none">search_append_body(re, txt)</function>
204                 </title>
205                 <para>
206                 Searches for the first match of re in the body of the message
207                 and appends txt after it.
208                 </para>
209                 <para>Meaning of the parameters is as follows:</para>
210                 <itemizedlist>
211                 <listitem>
212                         <para><emphasis>re</emphasis> - Regular expression.
213                         </para>
214                 </listitem>
215                 <listitem>
216                         <para><emphasis>txt</emphasis> - String to be appended.
217                         </para>
218                 </listitem>
219                 </itemizedlist>
220                 <para>
221                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
222                 FAILURE_ROUTE, BRANCH_ROUTE.
223                 </para>
224                 <example>
225                 <title><function>search_append_body</function> usage</title>
226                 <programlisting format="linespecific">
227 ...
228 search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
229 ...
230 </programlisting>
231                 </example>
232         </section>
233
234         <section>
235                 <title>
236                 <function moreinfo="none">replace(re, txt)</function>
237                 </title>
238                 <para>
239                 Replaces the first occurrence of re with txt.
240                 </para>
241                 <para>Meaning of the parameters is as follows:</para>
242                 <itemizedlist>
243                 <listitem>
244                         <para><emphasis>re</emphasis> - Regular expression.
245                         </para>
246                 </listitem>
247                 <listitem>
248                         <para><emphasis>txt</emphasis> - String.
249                         </para>
250                 </listitem>
251                 </itemizedlist>
252                 <para>
253                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
254                 FAILURE_ROUTE, BRANCH_ROUTE.
255                 </para>
256                 <example>
257                 <title><function>replace</function> usage</title>
258                 <programlisting format="linespecific">
259 ...
260 replace("openser", "&kamailio; SIP Proxy");
261 ...
262 </programlisting>
263                 </example>
264         </section>
265
266         <section>
267                 <title>
268                 <function moreinfo="none">replace_body(re, txt)</function>
269                 </title>
270                 <para>
271                 Replaces the first occurrence of re in the body of the message
272                 with txt.
273                 </para>
274                 <para>Meaning of the parameters is as follows:</para>
275                 <itemizedlist>
276                 <listitem>
277                         <para><emphasis>re</emphasis> - Regular expression.
278                         </para>
279                 </listitem>
280                 <listitem>
281                         <para><emphasis>txt</emphasis> - String.
282                         </para>
283                 </listitem>
284                 </itemizedlist>
285                 <para>
286                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
287                 FAILURE_ROUTE, BRANCH_ROUTE.
288                 </para>
289                 <example>
290                 <title><function>replace_body</function> usage</title>
291                 <programlisting format="linespecific">
292 ...
293 replace_body("openser", "&kamailio; SIP Proxy");
294 ...
295 </programlisting>
296                 </example>
297         </section>
298
299         <section>
300                 <title>
301                 <function moreinfo="none">replace_all(re, txt)</function>
302                 </title>
303                 <para>
304                 Replaces all occurrence of re with txt.
305                 </para>
306                 <para>Meaning of the parameters is as follows:</para>
307                 <itemizedlist>
308                 <listitem>
309                         <para><emphasis>re</emphasis> - Regular expression.
310                         </para>
311                 </listitem>
312                 <listitem>
313                         <para><emphasis>txt</emphasis> - String.
314                         </para>
315                 </listitem>
316                 </itemizedlist>
317                 <para>
318                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
319                 FAILURE_ROUTE, BRANCH_ROUTE.
320                 </para>
321                 <example>
322                 <title><function>replace_all</function> usage</title>
323                 <programlisting format="linespecific">
324 ...
325 replace_all("openser", "&kamailio; SIP Proxy");
326 ...
327 </programlisting>
328                 </example>
329         </section>
330
331         <section>
332                 <title>
333                 <function moreinfo="none">replace_body_all(re, txt)</function>
334                 </title>
335                 <para>
336                 Replaces all occurrence of re in the body of the message
337                 with txt. Matching is done on a per-line basis.
338                 </para>
339                 <para>Meaning of the parameters is as follows:</para>
340                 <itemizedlist>
341                 <listitem>
342                         <para><emphasis>re</emphasis> - Regular expression.
343                         </para>
344                 </listitem>
345                 <listitem>
346                         <para><emphasis>txt</emphasis> - String.
347                         </para>
348                 </listitem>
349                 </itemizedlist>
350                 <para>
351                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
352                 FAILURE_ROUTE, BRANCH_ROUTE.
353                 </para>
354                 <example>
355                 <title><function>replace_body_all</function> usage</title>
356                 <programlisting format="linespecific">
357 ...
358 replace_body_all("openser", "&kamailio; SIP Proxy");
359 ...
360 </programlisting>
361                 </example>
362         </section>
363
364         <section>
365                 <title>
366                 <function moreinfo="none">replace_body_atonce(re, txt)</function>
367                 </title>
368                 <para>
369                 Replaces all occurrence of re in the body of the message
370                 with txt. Matching is done over the whole body.
371                 </para>
372                 <para>Meaning of the parameters is as follows:</para>
373                 <itemizedlist>
374                 <listitem>
375                         <para><emphasis>re</emphasis> - Regular expression.
376                         </para>
377                 </listitem>
378                 <listitem>
379                         <para><emphasis>txt</emphasis> - String.
380                         </para>
381                 </listitem>
382                 </itemizedlist>
383                 <para>
384                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
385                 FAILURE_ROUTE, BRANCH_ROUTE.
386                 </para>
387                 <example>
388                 <title><function>replace_body_atonce</function> usage</title>
389                 <programlisting format="linespecific">
390 ...
391 # strip the whole body from the message:
392 if(has_body() &amp;&amp; replace_body_atonce("^.+$", ""))
393         remove_hf("Content-Type"); 
394 ...
395 </programlisting>
396                 </example>
397         </section>
398
399         <section>
400                 <title>
401                 <function moreinfo="none">subst('/re/repl/flags')</function>
402                 </title>
403                 <para>
404                 Replaces re with repl (sed or perl like).
405                 </para>
406                 <para>Meaning of the parameters is as follows:</para>
407                 <itemizedlist>
408                 <listitem>
409                         <para><emphasis>'/re/repl/flags'</emphasis> - sed like regular 
410                                 expression. flags can be a combination of i (case insensitive),
411                                 g (global) or s (match newline don't treat it as end of line).
412                         </para>
413                         <para>
414                         're' - is regular expresion
415                         </para>
416                         <para>
417                         'repl' - is replacement string - may contain pseudo-varibales
418                         </para>
419                         <para>
420                         'flags' - substitution flags (i - ignore case, g - global)
421                         </para>
422                 </listitem>
423                 </itemizedlist>
424                 <para>
425                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
426                 FAILURE_ROUTE, BRANCH_ROUTE.
427                 </para>
428                 <example>
429                 <title><function>subst</function> usage</title>
430                 <programlisting format="linespecific">
431 ...
432 # replace the uri in to: with the message uri (just an example)
433 if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};
434
435 # replace the uri in to: with the value of avp sip_address (just an example)
436 if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') ) {};
437
438 ...
439 </programlisting>
440                 </example>
441         </section>
442
443         <section>
444                 <title>
445                 <function moreinfo="none">subst_uri('/re/repl/flags')</function>
446                 </title>
447                 <para>
448                 Runs the re substitution on the message uri (like subst but works
449                  only on the uri)
450                 </para>
451                 <para>Meaning of the parameters is as follows:</para>
452                 <itemizedlist>
453                 <listitem>
454                         <para><emphasis>'/re/repl/flags'</emphasis> - sed like regular 
455                                 expression. flags can be a combination of i (case insensitive),
456                                 g (global) or s (match newline don't treat it as end of line).
457                         </para>
458                         <para>
459                         're' - is regular expresion
460                         </para>
461                         <para>
462                         'repl' - is replacement string - may contain pseudo-varibales
463                         </para>
464                         <para>
465                         'flags' - substitution flags (i - ignore case, g - global)
466                         </para>
467                 </listitem>
468                 </itemizedlist>
469                 <para>
470                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
471                 FAILURE_ROUTE, BRANCH_ROUTE.
472                 </para>
473                 <example>
474                 <title><function>subst_uri</function> usage</title>
475                 <programlisting format="linespecific">
476 ...
477 # adds 3463 prefix to numeric uris, and save the original uri (\0 match)
478 # as a parameter: orig_uri (just an example)
479 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$
480
481 # adds the avp 'uri_prefix' as prefix to numeric uris, and save the original
482 # uri (\0 match) as a parameter: orig_uri (just an example)
483 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$
484
485 ...
486 </programlisting>
487                 </example>
488         </section>
489
490         <section>
491                 <title>
492                 <function moreinfo="none">subst_user('/re/repl/flags')</function>
493                 </title>
494                 <para>
495                 Runs the re substitution on the message uri (like subst_uri but works
496                  only on the user portion of the uri)
497                 </para>
498                 <para>Meaning of the parameters is as follows:</para>
499                 <itemizedlist>
500                 <listitem>
501                         <para><emphasis>'/re/repl/flags'</emphasis> - sed like regular
502                                 expression. flags can be a combination of i (case insensitive),
503                                 g (global) or s (match newline don't treat it as end of line).
504                         </para>
505                         <para>
506                         're' - is regular expresion
507                         </para>
508                         <para>
509                         'repl' - is replacement string - may contain pseudo-varibales
510                         </para>
511                         <para>
512                         'flags' - substitution flags (i - ignore case, g - global)
513                         </para>
514                 </listitem>
515                 </itemizedlist>
516                 <para>
517                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
518                 FAILURE_ROUTE, BRANCH_ROUTE.
519                 </para>
520                 <example>
521                 <title><function>subst</function> usage</title>
522                 <programlisting format="linespecific">
523 ...
524 # adds 3463 prefix to uris ending with 3642 (just an example)
525 if (subst_user('/3642$/36423463/')){$
526
527 ...
528 # adds avp 'user_prefix' as prefix to username in r-uri ending with 3642
529 if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
530
531 ...
532 </programlisting>
533                 </example>
534         </section>
535
536         <section>
537                 <title>
538                 <function moreinfo="none">subst_body('/re/repl/flags')</function>
539                 </title>
540                 <para>
541                 Replaces re with repl (sed or perl like) in the body of the message.
542                 </para>
543                 <para>Meaning of the parameters is as follows:</para>
544                 <itemizedlist>
545                 <listitem>
546                         <para><emphasis>'/re/repl/flags'</emphasis> - sed like regular 
547                                 expression. flags can be a combination of i (case insensitive),
548                                 g (global) or s (match newline don't treat it as end of line).
549                         </para>
550                         <para>
551                         're' - is regular expresion
552                         </para>
553                         <para>
554                         'repl' - is replacement string - may contain pseudo-varibales
555                         </para>
556                         <para>
557                         'flags' - substitution flags (i - ignore case, g - global)
558                         </para>
559                 </listitem>
560                 </itemizedlist>
561                 <para>
562                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
563                 FAILURE_ROUTE, BRANCH_ROUTE.
564                 </para>
565                 <example>
566                 <title><function>subst_body</function> usage</title>
567                 <programlisting format="linespecific">
568 ...
569 if ( subst_body('/^o=(.*) /o=$fU /') ) {};
570
571 ...
572 </programlisting>
573                 </example>
574         </section>
575
576         <section>
577                 <title>
578                 <function moreinfo="none">subst_hf(hf, subexp, flags)</function>
579                 </title>
580                 <para>
581                 Perl-like substitutions in the body of a header field.
582                 </para>
583                 <para>Meaning of the parameters is as follows:</para>
584                 <itemizedlist>
585                 <listitem>
586                         <para><emphasis>hf</emphasis> - header field name.
587                         </para>
588                 </listitem>
589                 <listitem>
590                         <para><emphasis>subexp</emphasis> - substitution expression
591                                 in the same format as of the 'subst' function parameter.
592                         </para>
593                 </listitem>
594                 <listitem>
595                         <para><emphasis>flags</emphasis> - control flags - it
596                                 has to be one of: a - all headers matching the
597                                 name; f - only first header matching the name;
598                                 l - only the last header matching the name.
599                         </para>
600                 </listitem>
601                 </itemizedlist>
602                 <para>
603                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
604                 FAILURE_ROUTE, BRANCH_ROUTE.
605                 </para>
606                 <example>
607                 <title><function>search_body</function> usage</title>
608                 <programlisting format="linespecific">
609 ...
610 if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
611 ...
612 </programlisting>
613                 </example>
614         </section>
615
616         <section>
617                 <title>
618                 <function moreinfo="none">set_body(txt,content_type)</function>
619                 </title>
620                 <para>
621                 Set body to a SIP message.
622                 </para>
623                 <para>Meaning of the parameters is as follows:</para>
624                 <itemizedlist>
625                 <listitem>
626                         <para><emphasis>txt</emphasis> - text for the body, can include
627                                 pseudo-variables.
628                         </para>
629                 </listitem>
630                 <listitem>
631                         <para><emphasis>content_type</emphasis> - value of Content-Type header,
632                                 can include pseudo-variables.
633                         </para>
634                 </listitem>
635                 </itemizedlist>
636                 <para>
637                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
638                 FAILURE_ROUTE, BRANCH_ROUTE.
639                 </para>
640                 <example>
641                 <title><function>set_body</function> usage</title>
642                 <programlisting format="linespecific">
643 ...
644 set_body("test", "text/plain");
645 ...
646 </programlisting>
647                 </example>
648         </section>
649
650         <section>
651                 <title>
652                 <function moreinfo="none">set_reply_body(txt,content_type)</function>
653                 </title>
654                 <para>
655                 Set body to a SIP reply to be generated by &kamailio;.
656                 </para>
657                 <para>Meaning of the parameters is as follows:</para>
658                 <itemizedlist>
659                 <listitem>
660                         <para><emphasis>txt</emphasis> - text for the body, can include
661                                 pseudo-variables.
662                         </para>
663                 </listitem>
664                 <listitem>
665                         <para><emphasis>content_type</emphasis> - value of Content-Type header,
666                                 can include pseudo-variables.
667                         </para>
668                 </listitem>
669                 </itemizedlist>
670                 <para>
671                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
672                 </para>
673                 <example>
674                 <title><function>set_reply_body</function> usage</title>
675                 <programlisting format="linespecific">
676 ...
677 set_reply_body("test", "text/plain");
678 ...
679 </programlisting>
680                 </example>
681         </section>
682
683         <section>
684                 <title>
685                 <function moreinfo="none">filter_body(content_type)</function>
686                 </title>
687                 <para>
688                 Filters multipart/mixed body by leaving out all other body
689                 parts except the first body part of given type.
690                 </para>
691                 <para>Meaning of the parameters is as follows:</para>
692                 <itemizedlist>
693                 <listitem>
694                         <para><emphasis>content_type</emphasis> -
695                                 Content type to be left in the body.
696                         </para>
697                 </listitem>
698                 </itemizedlist>
699                 <para>
700                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
701                 FAILURE_ROUTE, BRANCH_ROUTE.
702                 </para>
703                 <example>
704                 <title><function>filter_body</function> usage</title>
705                 <programlisting format="linespecific">
706 ...
707 if (has_body("multipart/mixed")) {
708     if (filter_body("application/sdp") {
709         remove_hf("Content-Type");
710         append_hf("Content-Type: application/sdp\r\n");
711     } else {
712         xlog("Body part application/sdp not found\n");
713     }
714 }
715 ...
716 </programlisting>
717                 </example>
718         </section>
719
720         <section>
721                 <title>
722                 <function moreinfo="none">append_to_reply(txt)</function>
723                 </title>
724                 <para>
725                 Append txt as header to the reply.
726                 </para>
727                 <para>Meaning of the parameters is as follows:</para>
728                 <itemizedlist>
729                 <listitem>
730                         <para><emphasis>txt</emphasis> - String which may contains
731                         pseudo-variables.
732                         </para>
733                 </listitem>
734                 </itemizedlist>
735                 <para>
736                 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
737                 FAILURE_ROUTE, ERROR_ROUTE.
738                 </para>
739                 <example>
740                 <title><function>append_to_reply</function> usage</title>
741                 <programlisting format="linespecific">
742 ...
743 append_to_reply("Foo: bar\r\n");
744 append_to_reply("Foo: $rm at $Ts\r\n");
745 ...
746 </programlisting>
747                 </example>
748         </section>
749
750         <section>
751                 <title>
752                 <function moreinfo="none">append_hf(txt)</function>
753                 </title>
754                 <para>
755                         Appends 'txt' as header after the last header field. 
756                 </para>
757                 <para>Meaning of the parameters is as follows:</para>
758                 <itemizedlist>
759                 <listitem>
760                         <para><emphasis>txt</emphasis> - Header field to be appended. The
761                         value can contain pseudo-variables which will be replaced at run
762                         time.
763                         </para>
764                 </listitem>
765                 </itemizedlist>
766                 <para>
767                 Note: Headers which are added in main route cannot be removed in further routes
768                 (e.g. failure routes). So, the idea is not to add there any headers that you 
769                 might want to remove later. To add headers temporarely use the branch route 
770                 because the changes you do there are per-branch.
771                 </para>
772                 <para>
773                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
774                 FAILURE_ROUTE, BRANCH_ROUTE.
775                 </para>
776                 <example>
777                 <title><function>append_hf</function> usage</title>
778                 <programlisting format="linespecific">
779 ...
780 append_hf("P-hint: VOICEMAIL\r\n");
781 append_hf("From-username: $fU\r\n");
782 ...
783 </programlisting>
784                 </example>
785         </section>
786
787         <section>
788                 <title>
789                 <function moreinfo="none">append_hf(txt, hdr)</function>
790                 </title>
791                 <para>
792                 Appends 'txt' as header after first 'hdr' header field.
793                 </para>
794                 <para>Meaning of the parameters is as follows:</para>
795                 <itemizedlist>
796                 <listitem>
797                         <para><emphasis>txt</emphasis> - Header field to be appended. The
798                         value can contain pseudo-variables which will be replaced at run
799                         time.
800                         </para>
801                 </listitem>
802                 <listitem>
803                         <para><emphasis>hdr</emphasis> - Header name after which the 'txt'
804                         is appended.
805                         </para>
806                 </listitem>
807                 </itemizedlist>
808                 <para>
809                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
810                 FAILURE_ROUTE, BRANCH_ROUTE.
811                 </para>
812                 <example>
813                 <title><function>append_hf</function> usage</title>
814                 <programlisting format="linespecific">
815 ...
816 append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
817 append_hf("From-username: $fU\r\n", "Call-ID");
818 ...
819 </programlisting>
820                 </example>
821         </section>
822
823         <section>
824                 <title>
825                 <function moreinfo="none">insert_hf(txt)</function>
826                 </title>
827                 <para>
828                 Inserts 'txt' as header before the first header field.
829                 </para>
830                 <para>Meaning of the parameters is as follows:</para>
831                 <itemizedlist>
832                 <listitem>
833                         <para><emphasis>txt</emphasis> - Header field to be inserted. The
834                         value can contain pseudo-variables which will be replaced at run
835                         time.
836                         </para>
837                 </listitem>
838                 </itemizedlist>
839                 <para>
840                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
841                 FAILURE_ROUTE, BRANCH_ROUTE.
842                 </para>
843                 <example>
844                 <title><function>insert_hf</function> usage</title>
845                 <programlisting format="linespecific">
846 ...
847 insert_hf("P-hint: VOICEMAIL\r\n");
848 insert_hf("To-username: $tU\r\n");
849 ...
850 </programlisting>
851                 </example>
852         </section>
853
854
855         <section>
856                 <title>
857                 <function moreinfo="none">insert_hf(txt, hdr)</function>
858                 </title>
859                 <para>
860                 Inserts 'txt' as header before first 'hdr' header field.
861                 </para>
862                 <para>Meaning of the parameters is as follows:</para>
863                 <itemizedlist>
864                 <listitem>
865                         <para><emphasis>txt</emphasis> - Header field to be inserted. The
866                         value can contain pseudo-variables which will be replaced at run
867                         time.
868                         </para>
869                 </listitem>
870                 <listitem>
871                         <para><emphasis>hdr</emphasis> - Header name before which the 'txt'
872                         is inserted.
873                         </para>
874                 </listitem>
875                 </itemizedlist>
876                 <para>
877                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
878                 FAILURE_ROUTE, BRANCH_ROUTE.
879                 </para>
880                 <example>
881                 <title><function>insert_hf</function> usage</title>
882                 <programlisting format="linespecific">
883 ...
884 insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
885 insert_hf("To-username: $tU\r\n", "Call-ID");
886 ...
887 </programlisting>
888                 </example>
889         </section>
890
891         <section>
892                 <title>
893                 <function moreinfo="none">append_urihf(prefix, suffix)</function>
894                 </title>
895                 <para>
896                 Append header field name with original <acronym>Request-URI</acronym> 
897                 in middle.
898                 </para>
899                 <para>Meaning of the parameters is as follows:</para>
900                 <itemizedlist>
901                 <listitem>
902                         <para><emphasis>prefix</emphasis> - string (usually at least 
903                         header field name).
904                         </para>
905                 </listitem>
906                 <listitem>
907                         <para><emphasis>suffix</emphasis> - string (usually at least 
908                         line terminator).
909                         </para>
910                 </listitem>
911                 </itemizedlist>
912                 <para>
913                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
914                 BRANCH_ROUTE.
915                 </para>
916                 <example>
917                 <title><function>append_urihf</function> usage</title>
918                 <programlisting format="linespecific">
919 ...
920 append_urihf("CC-Diversion: ", "\r\n");
921 ...
922 </programlisting>
923                 </example>
924         </section>
925
926         <section>
927                 <title>
928                 <function moreinfo="none">is_present_hf(hf_name)</function>
929                 </title>
930                 <para>
931                 Return true if a header field is present in message.
932                 </para>
933                 <note>
934                 <para>
935                         The function is also able to distinguish the compact names. For
936                         exmaple <quote>From</quote> will match with <quote>f</quote>
937                 </para>
938                 </note>
939                 <para>Meaning of the parameters is as follows:</para>
940                 <itemizedlist>
941                 <listitem>
942                         <para><emphasis>hf_name</emphasis> - Header field name.(long or 
943                         compact form)
944                         </para>
945                 </listitem>
946                 </itemizedlist>
947                 <para>
948                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
949                 FAILURE_ROUTE, BRANCH_ROUTE.
950                 </para>
951                 <example>
952                 <title><function>is_present_hf</function> usage</title>
953                 <programlisting format="linespecific">
954 ...
955 if (is_present_hf("From")) log(1, "From HF Present");
956 ...
957 </programlisting>
958                 </example>
959         </section>
960
961         <section>
962                 <title>
963                 <function moreinfo="none">is_present_hf_re(hf_name_re)</function>
964                 </title>
965                 <para>
966                 Return true if a header field whose name matches regular expression
967                 'hf_name_re' is present in message.
968                 </para>
969                 <para>Meaning of the parameters is as follows:</para>
970                 <itemizedlist>
971                 <listitem>
972                         <para><emphasis>hf_name_re</emphasis> - Regular expression to
973                                 match header field name.
974                         </para>
975                 </listitem>
976                 </itemizedlist>
977                 <para>
978                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
979                 FAILURE_ROUTE, BRANCH_ROUTE.
980                 </para>
981                 <example>
982                 <title><function>is_present_hf_re</function> usage</title>
983                 <programlisting format="linespecific">
984 ...
985 if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
986 ...
987 </programlisting>
988                 </example>
989         </section>
990
991         <section>
992                 <title>
993                 <function moreinfo="none">append_time()</function>
994                 </title>
995                 <para>
996                 Adds a time header to the reply of the request. You must use it
997                 before functions that are likely to send a reply, e.g., save()
998                 from 'registrar' module. Header format is: 
999                 <quote>Date: %a, %d %b %Y %H:%M:%S GMT</quote>, with the legend:
1000                 <itemizedlist>
1001                 <listitem>
1002                         <para><emphasis>%a</emphasis> abbreviated week of day name (locale)
1003                         </para>
1004                 </listitem>
1005                 <listitem>
1006                         <para><emphasis>%d</emphasis> day of month as decimal number
1007                         </para>
1008                 </listitem>
1009                 <listitem>
1010                         <para><emphasis>%b</emphasis> abbreviated month name (locale)
1011                         </para>
1012                 </listitem>
1013                 <listitem>
1014                         <para><emphasis>%Y</emphasis> year with century
1015                         </para>
1016                 </listitem>
1017                 <listitem>
1018                         <para><emphasis>%H</emphasis> hour
1019                         </para>
1020                 </listitem>
1021                 <listitem>
1022                         <para><emphasis>%M</emphasis> minutes
1023                         </para>
1024                 </listitem>
1025                 <listitem>
1026                         <para><emphasis>%S</emphasis> seconds
1027                         </para>
1028                 </listitem>
1029                 </itemizedlist>
1030                 </para>
1031                 <para>
1032                 Return true if a header was succesfully appended.
1033                 </para>
1034                 <para>
1035                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
1036                 BRANCH_ROUTE.
1037                 </para>
1038                 <example>
1039                 <title><function>append_time</function> usage</title>
1040                 <programlisting format="linespecific">
1041 ...
1042 append_time();
1043 ...
1044 </programlisting>
1045                 </example>
1046         </section>
1047
1048         <section>
1049                 <title>
1050                 <function moreinfo="none">append_time_to_request()</function>
1051                 </title>
1052                 <para>
1053                 Adds a time header to the request. Header format is: 
1054                 <quote>Date: %a, %d %b %Y %H:%M:%S GMT</quote>, with the legend:
1055                 <itemizedlist>
1056                 <listitem>
1057                         <para><emphasis>%a</emphasis> abbreviated week of day name (locale)
1058                         </para>
1059                 </listitem>
1060                 <listitem>
1061                         <para><emphasis>%d</emphasis> day of month as decimal number
1062                         </para>
1063                 </listitem>
1064                 <listitem>
1065                         <para><emphasis>%b</emphasis> abbreviated month name (locale)
1066                         </para>
1067                 </listitem>
1068                 <listitem>
1069                         <para><emphasis>%Y</emphasis> year with century
1070                         </para>
1071                 </listitem>
1072                 <listitem>
1073                         <para><emphasis>%H</emphasis> hour
1074                         </para>
1075                 </listitem>
1076                 <listitem>
1077                         <para><emphasis>%M</emphasis> minutes
1078                         </para>
1079                 </listitem>
1080                 <listitem>
1081                         <para><emphasis>%S</emphasis> seconds
1082                         </para>
1083                 </listitem>
1084                 </itemizedlist>
1085                 </para>
1086                 <para>
1087                 Return true if a header was succesfully appended.
1088                 </para>
1089                 <para>
1090                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
1091                 FAILURE_ROUTE, BRANCH_ROUTE.
1092                 </para>
1093                 <example>
1094                 <title><function>append_time_to_request</function> usage</title>
1095                 <programlisting format="linespecific">
1096 ...
1097 if(!is_present_hf("Date"))
1098     append_time_to_request();
1099 ...
1100 </programlisting>
1101                 </example>
1102         </section>
1103
1104         <section>
1105                 <title>
1106                 <function moreinfo="none">is_method(name)</function>
1107                 </title>
1108                 <para>
1109                 Check if the method of the message matches the name. If name is a
1110                 known method (invite, cancel, ack, bye, options, info, update, register,
1111                 message, subscribe, notify, refer, prack), the function performs method
1112                 ID testing (integer comparison) instead of ignore case string
1113                 comparison.
1114                 </para>
1115                 <para>
1116                 The 'name' can be a list of methods in the form of
1117                 'method1|method2|...'. In this case, the function returns true if the
1118                 SIP message's method is one from the list. IMPORTANT NOTE: in the list
1119                 must be only methods defined in &kamailio; with ID (invite, cancel, ack,
1120                 bye, options, info, update, register, message, subscribe, notify,
1121                 refer, prack, publish; for more see:
1122                 <ulink url="http://www.iana.org/assignments/sip-parameters">
1123                         http://www.iana.org/assignments/sip-parameters</ulink>).
1124                 </para>
1125                 <para>
1126                 If used for replies, the function tests the value of method field from
1127                 CSeq header.
1128                 </para>
1129                 <para>Meaning of the parameters is as follows:</para>
1130                 <itemizedlist>
1131                 <listitem>
1132                         <para><emphasis>name</emphasis> - SIP method name
1133                         </para>
1134                 </listitem>
1135                 </itemizedlist>
1136                 <para>
1137                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1138                 FAILURE_ROUTE, and BRANCH_ROUTE.
1139                 </para>
1140                 <example>
1141                 <title><function>is_method</function> usage</title>
1142                 <programlisting format="linespecific">
1143 ...
1144 if(is_method("INVITE"))
1145 {
1146     # process INVITEs here
1147 }
1148 if(is_method("OPTION|UPDATE"))
1149 {
1150     # process OPTIONs and UPDATEs here
1151 }
1152 ...
1153 </programlisting>
1154                 </example>
1155         </section>
1156
1157         <section>
1158                 <title>
1159                 <function moreinfo="none">remove_hf(hname)</function>
1160                 </title>
1161                 <para>
1162                 Remove from message all headers with name <quote>hname</quote>. 
1163                 Header matching is case-insensitive. Matches and removes also
1164                 the compact header forms.
1165                 </para>
1166                 <para>
1167                 Returns true if at least one header is found and removed.
1168                 </para>
1169                 <para>Meaning of the parameters is as follows:</para>
1170                 <itemizedlist>
1171                 <listitem>
1172                         <para><emphasis>hname</emphasis> - header name to be removed.
1173                         </para>
1174                 </listitem>
1175                 </itemizedlist>
1176                 <para>
1177                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1178                 FAILURE_ROUTE and BRANCH_ROUTE.
1179                 </para>
1180                 <example>
1181                 <title><function>remove_hf</function> usage</title>
1182                 <programlisting format="linespecific">
1183 ...
1184 if(remove_hf("User-Agent"))
1185 {
1186     # User Agent header removed
1187 }
1188 # compact form: remove "Contact" or "m" header
1189 remove_hf("Contact")
1190 # compact form: remove "Contact" or "m" header
1191 remove_hf("m")
1192 ...
1193 </programlisting>
1194                 </example>
1195         </section>
1196
1197         <section>
1198                 <title>
1199                 <function moreinfo="none">remove_hf_re(re)</function>
1200                 </title>
1201                 <para>
1202                         Remove from message all headers with name matching regular
1203                         expression <quote>re</quote>
1204                 </para>
1205                 <para>
1206                 Returns true if at least one header is found and removed.
1207                 </para>
1208                 <para>Meaning of the parameters is as follows:</para>
1209                 <itemizedlist>
1210                 <listitem>
1211                         <para><emphasis>re</emphasis> - regular expression to match
1212                                 the header name to be removed.
1213                         </para>
1214                 </listitem>
1215                 </itemizedlist>
1216                 <para>
1217                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1218                 FAILURE_ROUTE and BRANCH_ROUTE.
1219                 </para>
1220                 <example>
1221                 <title><function>remove_hf_re</function> usage</title>
1222                 <programlisting format="linespecific">
1223 ...
1224 if(remove_hf_re("^P-"))
1225 {
1226     # All headers starting with "P-" removed
1227 }
1228 ...
1229 </programlisting>
1230                 </example>
1231         </section>
1232
1233         <section>
1234                 <title>
1235                 <function moreinfo="none">has_body()</function>,
1236                 <function moreinfo="none">has_body(mime)</function>
1237                 </title>
1238                 <para>
1239                 The function returns <emphasis>true</emphasis> if the SIP message
1240                 has a body attached. The checked includes also the 
1241                 <quote>Content-Lenght</quote> header presence and value.
1242                 </para>
1243                 <para>
1244                 If a parameter is given, the mime described will be also checked against
1245                 the <quote>Content-Type</quote> header.
1246                 </para>
1247                 <para>Meaning of the parameters is as follows:</para>
1248                 <itemizedlist>
1249                 <listitem>
1250                         <para><emphasis>mime</emphasis> - mime to be checked against the 
1251                                 <quote>Content-Type</quote> header. If not present or 0, this
1252                                 check will be disabled.
1253                         </para>
1254                 </listitem>
1255                 </itemizedlist>
1256                 <para>
1257                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1258                 FAILURE_ROUTE and BRANCH_ROUTE.
1259                 </para>
1260                 <example>
1261                 <title><function>has_body</function> usage</title>
1262                 <programlisting format="linespecific">
1263 ...
1264 if(has_body("application/sdp"))
1265 {
1266     # do interesting stuff here
1267 }
1268 ...
1269 </programlisting>
1270                 </example>
1271         </section>
1272
1273         <section>
1274                 <title>
1275                 <function moreinfo="none">is_audio_on_hold()</function>
1276                 </title>
1277                 <para>
1278                 The function returns <emphasis>true</emphasis> if the SIP message
1279                 has a body attached and at least one audio stream in on hold.
1280                 </para>
1281                 <para>
1282                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1283                 FAILURE_ROUTE and BRANCH_ROUTE.
1284                 </para>
1285                 <example>
1286                 <title><function>is_audio_on_hold</function> usage</title>
1287                 <programlisting format="linespecific">
1288 ...
1289 if(is_audio_on_hold())
1290 {
1291     # do interesting stuff here
1292 }
1293 ...
1294 </programlisting>
1295                 </example>
1296         </section>
1297
1298         <section>
1299                 <title>
1300                 <function moreinfo="none">is_privacy(privacy_type)</function>
1301                 </title>
1302                 <para>
1303                 The function returns <emphasis>true</emphasis> if 
1304                 the SIP message has a Privacy header field that includes
1305                 the given privacy_type among its privacy values.  See
1306                                 <ulink url="http://www.iana.org/assignments/sip-priv-values">
1307                 http://www.iana.org/assignments/sip-priv-values</ulink>
1308                 for possible privacy type values.
1309                 </para>
1310                 <para>
1311                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1312                 FAILURE_ROUTE and BRANCH_ROUTE.
1313                 </para>
1314                 <example>
1315                 <title><function>is_privacy</function> usage</title>
1316                 <programlisting format="linespecific">
1317 ...
1318 if(is_privacy("id"))
1319 {
1320     # do interesting stuff here
1321 }
1322 ...
1323 </programlisting>
1324                 </example>
1325         </section>
1326
1327         <section>
1328                 <title>
1329                         <function moreinfo="none">in_list(subject, list, separator)</function>
1330                 </title>
1331                 <para>
1332                 Function checks if subject string is found in list string where list items are separated by separator string.  Subject and list strings may contain pseudo variables.  Separator string needs to be one character long.  Returns 1 if subject is found and -1 otherwise.
1333                 </para>
1334                 <para>
1335                 Function can be used from all kinds of routes.
1336                 </para>
1337                 <example>
1338                         <title><function>in_list()</function> usage</title>
1339                         <programlisting format="linespecific">
1340 ...
1341 $var(subject) = "fi";
1342 $var(list) = "dk,fi,no,se";
1343 if (in_list("$var(subject)", "$var(list)", ",") {
1344     xlog("L_INFO", "subject is found in list\n");
1345 }
1346 ...
1347                         </programlisting>
1348                 </example>
1349         </section>
1350
1351         <section>
1352                 <title>
1353                 <function moreinfo="none">cmp_str(str1, str2)</function>
1354                 </title>
1355                 <para>
1356                 The function returns <emphasis>true</emphasis> if 
1357                 the two parameters matches as string case sensitive comparison.
1358                 </para>
1359                 <para>
1360                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1361                 FAILURE_ROUTE and BRANCH_ROUTE.
1362                 </para>
1363                 <example>
1364                 <title><function>cmp_str</function> usage</title>
1365                 <programlisting format="linespecific">
1366 ...
1367 if(cmp_str("$rU", "kamailio"))
1368 {
1369     # do interesting stuff here
1370 }
1371 ...
1372 </programlisting>
1373                 </example>
1374         </section>
1375
1376         <section>
1377                 <title>
1378                 <function moreinfo="none">cmp_istr(str1, str2)</function>
1379                 </title>
1380                 <para>
1381                 The function returns <emphasis>true</emphasis> if 
1382                 the two parameters matches as string case insensitive comparison.
1383                 </para>
1384                 <para>
1385                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1386                 FAILURE_ROUTE and BRANCH_ROUTE.
1387                 </para>
1388                 <example>
1389                 <title><function>cmp_str</function> usage</title>
1390                 <programlisting format="linespecific">
1391 ...
1392 if(cmp_istr("$rU@you", "kamailio@YOU"))
1393 {
1394     # do interesting stuff here
1395 }
1396 ...
1397 </programlisting>
1398                 </example>
1399         </section>
1400
1401         <section>
1402                 <title>
1403                 <function moreinfo="none">starts_with(str1, str2)</function>
1404                 </title>
1405                 <para>
1406                 The function returns <emphasis>true</emphasis> if 
1407                 the first string starts with the second string.
1408                 </para>
1409                 <para>
1410                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
1411                 FAILURE_ROUTE and BRANCH_ROUTE.
1412                 </para>
1413                 <example>
1414                 <title><function>starts_with</function> usage</title>
1415                 <programlisting format="linespecific">
1416 ...
1417 if (starts_with("$rU", "+358"))
1418 {
1419     # do interesting stuff here
1420 }
1421 ...
1422 </programlisting>
1423                 </example>
1424         </section>
1425
1426         </section>
1427         <section>
1428                 <title>Known Limitations</title>
1429                 <para>
1430                         Search functions are applied to the original request,
1431                         i.e., they ignore all changes resulting from message
1432                         processing in &kamailio; script.
1433                 </para>
1434         </section>
1435 </chapter>
1436