06c28b5bceea2d6bb85f7b5eab1f68ccc6f9d397
[sip-router] / modules / textops / README
1 textops Module
2
3 Andrei Pelinescu-Onciul
4
5    FhG FOKUS
6    <pelinescu-onciul@fokus.fraunhofer.de>
7
8 Edited by
9
10 Andrei Pelinescu-Onciul
11
12    <pelinescu-onciul@fokus.fraunhofer.de>
13
14 Edited by
15
16 Daniel-Constantin Mierla
17
18    <miconda@gmail.com>
19
20 Edited by
21
22 Juha Heinanen
23
24    <jh@tutpro.com>
25
26    Copyright © 2003 FhG FOKUS
27      __________________________________________________________________
28
29    Table of Contents
30
31    1. Admin Guide
32
33         1. Overview
34
35               1.1. Known Limitations
36
37         2. Dependencies
38
39               2.1. Kamailio Modules
40               2.2. External Libraries or Applications
41
42         3. Functions
43
44               3.1. search(re)
45               3.2. search_body(re)
46               3.3. search_hf(hf, re, flags)
47               3.4. search_append(re, txt)
48               3.5. search_append_body(re, txt)
49               3.6. replace(re, txt)
50               3.7. replace_body(re, txt)
51               3.8. replace_all(re, txt)
52               3.9. replace_body_all(re, txt)
53               3.10. replace_body_atonce(re, txt)
54               3.11. subst('/re/repl/flags')
55               3.12. subst_uri('/re/repl/flags')
56               3.13. subst_user('/re/repl/flags')
57               3.14. subst_body('/re/repl/flags')
58               3.15. subst_hf(hf, subexp, flags)
59               3.16. set_body(txt,content_type)
60               3.17. set_reply_body(txt,content_type)
61               3.18. filter_body(content_type)
62               3.19. append_to_reply(txt)
63               3.20. append_hf(txt)
64               3.21. append_hf(txt, hdr)
65               3.22. insert_hf(txt)
66               3.23. insert_hf(txt, hdr)
67               3.24. append_urihf(prefix, suffix)
68               3.25. is_present_hf(hf_name)
69               3.26. is_present_hf_re(hf_name_re)
70               3.27. append_time()
71               3.28. append_time_to_request()
72               3.29. is_method(name)
73               3.30. remove_hf(hname)
74               3.31. remove_hf_re(re)
75               3.32. has_body(), has_body(mime)
76               3.33. is_audio_on_hold()
77               3.34. is_privacy(privacy_type)
78               3.35. in_list(subject, list, separator)
79               3.36. cmp_str(str1, str2)
80               3.37. cmp_istr(str1, str2)
81               3.38. starts_with(str1, str2)
82
83         4. Known Limitations
84
85    2. Developer Guide
86
87         1. Functions
88
89               1.1. load_textops(*import_structure)
90
91    List of Examples
92
93    1.1. search usage
94    1.2. search_body usage
95    1.3. search_body usage
96    1.4. search_append usage
97    1.5. search_append_body usage
98    1.6. replace usage
99    1.7. replace_body usage
100    1.8. replace_all usage
101    1.9. replace_body_all usage
102    1.10. replace_body_atonce usage
103    1.11. subst usage
104    1.12. subst_uri usage
105    1.13. subst usage
106    1.14. subst_body usage
107    1.15. search_body usage
108    1.16. set_body usage
109    1.17. set_reply_body usage
110    1.18. filter_body usage
111    1.19. append_to_reply usage
112    1.20. append_hf usage
113    1.21. append_hf usage
114    1.22. insert_hf usage
115    1.23. insert_hf usage
116    1.24. append_urihf usage
117    1.25. is_present_hf usage
118    1.26. is_present_hf_re usage
119    1.27. append_time usage
120    1.28. append_time_to_request usage
121    1.29. is_method usage
122    1.30. remove_hf usage
123    1.31. remove_hf_re usage
124    1.32. has_body usage
125    1.33. is_audio_on_hold usage
126    1.34. is_privacy usage
127    1.35. in_list() usage
128    1.36. cmp_str usage
129    1.37. cmp_str usage
130    1.38. starts_with usage
131
132 Chapter 1. Admin Guide
133
134    Table of Contents
135
136    1. Overview
137
138         1.1. Known Limitations
139
140    2. Dependencies
141
142         2.1. Kamailio Modules
143         2.2. External Libraries or Applications
144
145    3. Functions
146
147         3.1. search(re)
148         3.2. search_body(re)
149         3.3. search_hf(hf, re, flags)
150         3.4. search_append(re, txt)
151         3.5. search_append_body(re, txt)
152         3.6. replace(re, txt)
153         3.7. replace_body(re, txt)
154         3.8. replace_all(re, txt)
155         3.9. replace_body_all(re, txt)
156         3.10. replace_body_atonce(re, txt)
157         3.11. subst('/re/repl/flags')
158         3.12. subst_uri('/re/repl/flags')
159         3.13. subst_user('/re/repl/flags')
160         3.14. subst_body('/re/repl/flags')
161         3.15. subst_hf(hf, subexp, flags)
162         3.16. set_body(txt,content_type)
163         3.17. set_reply_body(txt,content_type)
164         3.18. filter_body(content_type)
165         3.19. append_to_reply(txt)
166         3.20. append_hf(txt)
167         3.21. append_hf(txt, hdr)
168         3.22. insert_hf(txt)
169         3.23. insert_hf(txt, hdr)
170         3.24. append_urihf(prefix, suffix)
171         3.25. is_present_hf(hf_name)
172         3.26. is_present_hf_re(hf_name_re)
173         3.27. append_time()
174         3.28. append_time_to_request()
175         3.29. is_method(name)
176         3.30. remove_hf(hname)
177         3.31. remove_hf_re(re)
178         3.32. has_body(), has_body(mime)
179         3.33. is_audio_on_hold()
180         3.34. is_privacy(privacy_type)
181         3.35. in_list(subject, list, separator)
182         3.36. cmp_str(str1, str2)
183         3.37. cmp_istr(str1, str2)
184         3.38. starts_with(str1, str2)
185
186    4. Known Limitations
187
188 1. Overview
189
190    1.1. Known Limitations
191
192    The module implements text based operations over the SIP message
193    processed by Kamailio. SIP is a text based protocol and the module
194    provides a large set of very useful functions to manipulate the message
195    at text level, e.g., regular expression search and replace, Perl-like
196    substitutions, checks for method type, header presence, insert of new
197    header and date, etc.
198
199 1.1. Known Limitations
200
201    search ignores folded lines. For example, search("(From|f):.*@foo.bar")
202    doesn't match the following From header field:
203 From: medabeda
204  <sip:medameda@foo.bar>;tag=1234
205
206 2. Dependencies
207
208    2.1. Kamailio Modules
209    2.2. External Libraries or Applications
210
211 2.1. Kamailio Modules
212
213    The following modules must be loaded before this module:
214      * No dependencies on other Kamailio modules.
215
216 2.2. External Libraries or Applications
217
218    The following libraries or applications must be installed before
219    running Kamailio with this module loaded:
220      * None.
221
222 3. Functions
223
224    3.1. search(re)
225    3.2. search_body(re)
226    3.3. search_hf(hf, re, flags)
227    3.4. search_append(re, txt)
228    3.5. search_append_body(re, txt)
229    3.6. replace(re, txt)
230    3.7. replace_body(re, txt)
231    3.8. replace_all(re, txt)
232    3.9. replace_body_all(re, txt)
233    3.10. replace_body_atonce(re, txt)
234    3.11. subst('/re/repl/flags')
235    3.12. subst_uri('/re/repl/flags')
236    3.13. subst_user('/re/repl/flags')
237    3.14. subst_body('/re/repl/flags')
238    3.15. subst_hf(hf, subexp, flags)
239    3.16. set_body(txt,content_type)
240    3.17. set_reply_body(txt,content_type)
241    3.18. filter_body(content_type)
242    3.19. append_to_reply(txt)
243    3.20. append_hf(txt)
244    3.21. append_hf(txt, hdr)
245    3.22. insert_hf(txt)
246    3.23. insert_hf(txt, hdr)
247    3.24. append_urihf(prefix, suffix)
248    3.25. is_present_hf(hf_name)
249    3.26. is_present_hf_re(hf_name_re)
250    3.27. append_time()
251    3.28. append_time_to_request()
252    3.29. is_method(name)
253    3.30. remove_hf(hname)
254    3.31. remove_hf_re(re)
255    3.32. has_body(), has_body(mime)
256    3.33. is_audio_on_hold()
257    3.34. is_privacy(privacy_type)
258    3.35. in_list(subject, list, separator)
259    3.36. cmp_str(str1, str2)
260    3.37. cmp_istr(str1, str2)
261    3.38. starts_with(str1, str2)
262
263 3.1. search(re)
264
265    Searches for the re in the message.
266
267    Meaning of the parameters is as follows:
268      * re - Regular expression.
269
270    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
271    FAILURE_ROUTE, BRANCH_ROUTE.
272
273    Example 1.1. search usage
274 ...
275 if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
276 ...
277
278 3.2. search_body(re)
279
280    Searches for the re in the body of the message.
281
282    Meaning of the parameters is as follows:
283      * re - Regular expression.
284
285    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
286    FAILURE_ROUTE, BRANCH_ROUTE.
287
288    Example 1.2. search_body usage
289 ...
290 if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
291 ...
292
293 3.3. search_hf(hf, re, flags)
294
295    Searches for the re in the body of a header field.
296
297    Meaning of the parameters is as follows:
298      * hf - header field name.
299      * re - regular expression.
300      * flags - control flags - it has to be one of: a - all headers
301        matching the name; f - only first header matching the name; l -
302        only the last header matching the name.
303
304    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
305    FAILURE_ROUTE, BRANCH_ROUTE.
306
307    Example 1.3. search_body usage
308 ...
309 if ( search_hf("From", ":test@", "a") ) { /*....*/ };
310 ...
311
312 3.4. search_append(re, txt)
313
314    Searches for the first match of re and appends txt after it.
315
316    Meaning of the parameters is as follows:
317      * re - Regular expression.
318      * txt - String to be appended.
319
320    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
321    FAILURE_ROUTE, BRANCH_ROUTE.
322
323    Example 1.4. search_append usage
324 ...
325 search_append("[Oo]pen[Ss]er", " SIP Proxy");
326 ...
327
328 3.5. search_append_body(re, txt)
329
330    Searches for the first match of re in the body of the message and
331    appends txt after it.
332
333    Meaning of the parameters is as follows:
334      * re - Regular expression.
335      * txt - String to be appended.
336
337    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
338    FAILURE_ROUTE, BRANCH_ROUTE.
339
340    Example 1.5. search_append_body usage
341 ...
342 search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
343 ...
344
345 3.6. replace(re, txt)
346
347    Replaces the first occurrence of re with txt.
348
349    Meaning of the parameters is as follows:
350      * re - Regular expression.
351      * txt - String.
352
353    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
354    FAILURE_ROUTE, BRANCH_ROUTE.
355
356    Example 1.6. replace usage
357 ...
358 replace("openser", "Kamailio SIP Proxy");
359 ...
360
361 3.7. replace_body(re, txt)
362
363    Replaces the first occurrence of re in the body of the message with
364    txt.
365
366    Meaning of the parameters is as follows:
367      * re - Regular expression.
368      * txt - String.
369
370    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
371    FAILURE_ROUTE, BRANCH_ROUTE.
372
373    Example 1.7. replace_body usage
374 ...
375 replace_body("openser", "Kamailio SIP Proxy");
376 ...
377
378 3.8. replace_all(re, txt)
379
380    Replaces all occurrence of re with txt.
381
382    Meaning of the parameters is as follows:
383      * re - Regular expression.
384      * txt - String.
385
386    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
387    FAILURE_ROUTE, BRANCH_ROUTE.
388
389    Example 1.8. replace_all usage
390 ...
391 replace_all("openser", "Kamailio SIP Proxy");
392 ...
393
394 3.9. replace_body_all(re, txt)
395
396    Replaces all occurrence of re in the body of the message with txt.
397    Matching is done on a per-line basis.
398
399    Meaning of the parameters is as follows:
400      * re - Regular expression.
401      * txt - String.
402
403    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
404    FAILURE_ROUTE, BRANCH_ROUTE.
405
406    Example 1.9. replace_body_all usage
407 ...
408 replace_body_all("openser", "Kamailio SIP Proxy");
409 ...
410
411 3.10. replace_body_atonce(re, txt)
412
413    Replaces all occurrence of re in the body of the message with txt.
414    Matching is done over the whole body.
415
416    Meaning of the parameters is as follows:
417      * re - Regular expression.
418      * txt - String.
419
420    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
421    FAILURE_ROUTE, BRANCH_ROUTE.
422
423    Example 1.10. replace_body_atonce usage
424 ...
425 # strip the whole body from the message:
426 if(has_body() && replace_body_atonce("^.+$", ""))
427         remove_hf("Content-Type");
428 ...
429
430 3.11. subst('/re/repl/flags')
431
432    Replaces re with repl (sed or perl like).
433
434    Meaning of the parameters is as follows:
435      * '/re/repl/flags' - sed like regular expression. flags can be a
436        combination of i (case insensitive), g (global) or s (match newline
437        don't treat it as end of line).
438        're' - is regular expresion
439        'repl' - is replacement string - may contain pseudo-varibales
440        'flags' - substitution flags (i - ignore case, g - global)
441
442    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
443    FAILURE_ROUTE, BRANCH_ROUTE.
444
445    Example 1.11. subst usage
446 ...
447 # replace the uri in to: with the message uri (just an example)
448 if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};
449
450 # replace the uri in to: with the value of avp sip_address (just an example)
451 if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') )
452  {};
453
454 ...
455
456 3.12. subst_uri('/re/repl/flags')
457
458    Runs the re substitution on the message uri (like subst but works only
459    on the uri)
460
461    Meaning of the parameters is as follows:
462      * '/re/repl/flags' - sed like regular expression. flags can be a
463        combination of i (case insensitive), g (global) or s (match newline
464        don't treat it as end of line).
465        're' - is regular expresion
466        'repl' - is replacement string - may contain pseudo-varibales
467        'flags' - substitution flags (i - ignore case, g - global)
468
469    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
470    FAILURE_ROUTE, BRANCH_ROUTE.
471
472    Example 1.12. subst_uri usage
473 ...
474 # adds 3463 prefix to numeric uris, and save the original uri (\0 match)
475 # as a parameter: orig_uri (just an example)
476 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$
477
478 # adds the avp 'uri_prefix' as prefix to numeric uris, and save the original
479 # uri (\0 match) as a parameter: orig_uri (just an example)
480 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$
481
482 ...
483
484 3.13. subst_user('/re/repl/flags')
485
486    Runs the re substitution on the message uri (like subst_uri but works
487    only on the user portion of the uri)
488
489    Meaning of the parameters is as follows:
490      * '/re/repl/flags' - sed like regular expression. flags can be a
491        combination of i (case insensitive), g (global) or s (match newline
492        don't treat it as end of line).
493        're' - is regular expresion
494        'repl' - is replacement string - may contain pseudo-varibales
495        'flags' - substitution flags (i - ignore case, g - global)
496
497    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
498    FAILURE_ROUTE, BRANCH_ROUTE.
499
500    Example 1.13. subst usage
501 ...
502 # adds 3463 prefix to uris ending with 3642 (just an example)
503 if (subst_user('/3642$/36423463/')){$
504
505 ...
506 # adds avp 'user_prefix' as prefix to username in r-uri ending with 3642
507 if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
508
509 ...
510
511 3.14. subst_body('/re/repl/flags')
512
513    Replaces re with repl (sed or perl like) in the body of the message.
514
515    Meaning of the parameters is as follows:
516      * '/re/repl/flags' - sed like regular expression. flags can be a
517        combination of i (case insensitive), g (global) or s (match newline
518        don't treat it as end of line).
519        're' - is regular expresion
520        'repl' - is replacement string - may contain pseudo-varibales
521        'flags' - substitution flags (i - ignore case, g - global)
522
523    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
524    FAILURE_ROUTE, BRANCH_ROUTE.
525
526    Example 1.14. subst_body usage
527 ...
528 if ( subst_body('/^o=(.*) /o=$fU /') ) {};
529
530 ...
531
532 3.15. subst_hf(hf, subexp, flags)
533
534    Perl-like substitutions in the body of a header field.
535
536    Meaning of the parameters is as follows:
537      * hf - header field name.
538      * subexp - substitution expression in the same format as of the
539        'subst' function parameter.
540      * flags - control flags - it has to be one of: a - all headers
541        matching the name; f - only first header matching the name; l -
542        only the last header matching the name.
543
544    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
545    FAILURE_ROUTE, BRANCH_ROUTE.
546
547    Example 1.15. search_body usage
548 ...
549 if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
550 ...
551
552 3.16. set_body(txt,content_type)
553
554    Set body to a SIP message.
555
556    Meaning of the parameters is as follows:
557      * txt - text for the body, can include pseudo-variables.
558      * content_type - value of Content-Type header, can include
559        pseudo-variables.
560
561    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
562    FAILURE_ROUTE, BRANCH_ROUTE.
563
564    Example 1.16. set_body usage
565 ...
566 set_body("test", "text/plain");
567 ...
568
569 3.17. set_reply_body(txt,content_type)
570
571    Set body to a SIP reply to be generated by Kamailio.
572
573    Meaning of the parameters is as follows:
574      * txt - text for the body, can include pseudo-variables.
575      * content_type - value of Content-Type header, can include
576        pseudo-variables.
577
578    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
579    BRANCH_ROUTE.
580
581    Example 1.17. set_reply_body usage
582 ...
583 set_reply_body("test", "text/plain");
584 ...
585
586 3.18. filter_body(content_type)
587
588    Filters multipart/mixed body by leaving out all other body parts except
589    the first body part of given type.
590
591    Meaning of the parameters is as follows:
592      * content_type - Content type to be left in the body.
593
594    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
595    FAILURE_ROUTE, BRANCH_ROUTE.
596
597    Example 1.18. filter_body usage
598 ...
599 if (has_body("multipart/mixed")) {
600     if (filter_body("application/sdp") {
601         remove_hf("Content-Type");
602         append_hf("Content-Type: application/sdp\r\n");
603     } else {
604         xlog("Body part application/sdp not found\n");
605     }
606 }
607 ...
608
609 3.19. append_to_reply(txt)
610
611    Append txt as header to the reply.
612
613    Meaning of the parameters is as follows:
614      * txt - String which may contains pseudo-variables.
615
616    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
617    FAILURE_ROUTE, ERROR_ROUTE.
618
619    Example 1.19. append_to_reply usage
620 ...
621 append_to_reply("Foo: bar\r\n");
622 append_to_reply("Foo: $rm at $Ts\r\n");
623 ...
624
625 3.20. append_hf(txt)
626
627    Appends 'txt' as header after the last header field.
628
629    Meaning of the parameters is as follows:
630      * txt - Header field to be appended. The value can contain
631        pseudo-variables which will be replaced at run time.
632
633    Note: Headers which are added in main route cannot be removed in
634    further routes (e.g. failure routes). So, the idea is not to add there
635    any headers that you might want to remove later. To add headers
636    temporarely use the branch route because the changes you do there are
637    per-branch.
638
639    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
640    FAILURE_ROUTE, BRANCH_ROUTE.
641
642    Example 1.20. append_hf usage
643 ...
644 append_hf("P-hint: VOICEMAIL\r\n");
645 append_hf("From-username: $fU\r\n");
646 ...
647
648 3.21. append_hf(txt, hdr)
649
650    Appends 'txt' as header after first 'hdr' header field.
651
652    Meaning of the parameters is as follows:
653      * txt - Header field to be appended. The value can contain
654        pseudo-variables which will be replaced at run time.
655      * hdr - Header name after which the 'txt' is appended.
656
657    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
658    FAILURE_ROUTE, BRANCH_ROUTE.
659
660    Example 1.21. append_hf usage
661 ...
662 append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
663 append_hf("From-username: $fU\r\n", "Call-ID");
664 ...
665
666 3.22. insert_hf(txt)
667
668    Inserts 'txt' as header before the first header field.
669
670    Meaning of the parameters is as follows:
671      * txt - Header field to be inserted. The value can contain
672        pseudo-variables which will be replaced at run time.
673
674    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
675    FAILURE_ROUTE, BRANCH_ROUTE.
676
677    Example 1.22. insert_hf usage
678 ...
679 insert_hf("P-hint: VOICEMAIL\r\n");
680 insert_hf("To-username: $tU\r\n");
681 ...
682
683 3.23. insert_hf(txt, hdr)
684
685    Inserts 'txt' as header before first 'hdr' header field.
686
687    Meaning of the parameters is as follows:
688      * txt - Header field to be inserted. The value can contain
689        pseudo-variables which will be replaced at run time.
690      * hdr - Header name before which the 'txt' is inserted.
691
692    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
693    FAILURE_ROUTE, BRANCH_ROUTE.
694
695    Example 1.23. insert_hf usage
696 ...
697 insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
698 insert_hf("To-username: $tU\r\n", "Call-ID");
699 ...
700
701 3.24. append_urihf(prefix, suffix)
702
703    Append header field name with original Request-URI in middle.
704
705    Meaning of the parameters is as follows:
706      * prefix - string (usually at least header field name).
707      * suffix - string (usually at least line terminator).
708
709    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
710    BRANCH_ROUTE.
711
712    Example 1.24. append_urihf usage
713 ...
714 append_urihf("CC-Diversion: ", "\r\n");
715 ...
716
717 3.25. is_present_hf(hf_name)
718
719    Return true if a header field is present in message.
720
721 Note
722
723    The function is also able to distinguish the compact names. For exmaple
724    "From" will match with "f"
725
726    Meaning of the parameters is as follows:
727      * hf_name - Header field name.(long or compact form)
728
729    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
730    FAILURE_ROUTE, BRANCH_ROUTE.
731
732    Example 1.25. is_present_hf usage
733 ...
734 if (is_present_hf("From")) log(1, "From HF Present");
735 ...
736
737 3.26. is_present_hf_re(hf_name_re)
738
739    Return true if a header field whose name matches regular expression
740    'hf_name_re' is present in message.
741
742    Meaning of the parameters is as follows:
743      * hf_name_re - Regular expression to match header field name.
744
745    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
746    FAILURE_ROUTE, BRANCH_ROUTE.
747
748    Example 1.26. is_present_hf_re usage
749 ...
750 if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
751 ...
752
753 3.27. append_time()
754
755    Adds a time header to the reply of the request. You must use it before
756    functions that are likely to send a reply, e.g., save() from
757    'registrar' module. Header format is: "Date: %a, %d %b %Y %H:%M:%S
758    GMT", with the legend:
759      * %a abbreviated week of day name (locale)
760      * %d day of month as decimal number
761      * %b abbreviated month name (locale)
762      * %Y year with century
763      * %H hour
764      * %M minutes
765      * %S seconds
766
767    Return true if a header was succesfully appended.
768
769    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
770    BRANCH_ROUTE.
771
772    Example 1.27. append_time usage
773 ...
774 append_time();
775 ...
776
777 3.28. append_time_to_request()
778
779    Adds a time header to the request. Header format is: "Date: %a, %d %b
780    %Y %H:%M:%S GMT", with the legend:
781      * %a abbreviated week of day name (locale)
782      * %d day of month as decimal number
783      * %b abbreviated month name (locale)
784      * %Y year with century
785      * %H hour
786      * %M minutes
787      * %S seconds
788
789    Return true if a header was succesfully appended.
790
791    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
792    FAILURE_ROUTE, BRANCH_ROUTE.
793
794    Example 1.28. append_time_to_request usage
795 ...
796 if(!is_present_hf("Date"))
797     append_time_to_request();
798 ...
799
800 3.29. is_method(name)
801
802    Check if the method of the message matches the name. If name is a known
803    method (invite, cancel, ack, bye, options, info, update, register,
804    message, subscribe, notify, refer, prack), the function performs method
805    ID testing (integer comparison) instead of ignore case string
806    comparison.
807
808    The 'name' can be a list of methods in the form of
809    'method1|method2|...'. In this case, the function returns true if the
810    SIP message's method is one from the list. IMPORTANT NOTE: in the list
811    must be only methods defined in Kamailio with ID (invite, cancel, ack,
812    bye, options, info, update, register, message, subscribe, notify,
813    refer, prack, publish; for more see:
814    http://www.iana.org/assignments/sip-parameters).
815
816    If used for replies, the function tests the value of method field from
817    CSeq header.
818
819    Meaning of the parameters is as follows:
820      * name - SIP method name
821
822    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
823    FAILURE_ROUTE, and BRANCH_ROUTE.
824
825    Example 1.29. is_method usage
826 ...
827 if(is_method("INVITE"))
828 {
829     # process INVITEs here
830 }
831 if(is_method("OPTION|UPDATE"))
832 {
833     # process OPTIONs and UPDATEs here
834 }
835 ...
836
837 3.30. remove_hf(hname)
838
839    Remove from message all headers with name "hname". Header matching is
840    case-insensitive. Matches and removes also the compact header forms.
841
842    Returns true if at least one header is found and removed.
843
844    Meaning of the parameters is as follows:
845      * hname - header name to be removed.
846
847    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
848    FAILURE_ROUTE and BRANCH_ROUTE.
849
850    Example 1.30. remove_hf usage
851 ...
852 if(remove_hf("User-Agent"))
853 {
854     # User Agent header removed
855 }
856 # compact form: remove "Contact" or "m" header
857 remove_hf("Contact")
858 # compact form: remove "Contact" or "m" header
859 remove_hf("m")
860 ...
861
862 3.31. remove_hf_re(re)
863
864    Remove from message all headers with name matching regular expression
865    "re"
866
867    Returns true if at least one header is found and removed.
868
869    Meaning of the parameters is as follows:
870      * re - regular expression to match the header name to be removed.
871
872    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
873    FAILURE_ROUTE and BRANCH_ROUTE.
874
875    Example 1.31. remove_hf_re usage
876 ...
877 if(remove_hf_re("^P-"))
878 {
879     # All headers starting with "P-" removed
880 }
881 ...
882
883 3.32. has_body(), has_body(mime)
884
885    The function returns true if the SIP message has a body attached. The
886    checked includes also the "Content-Lenght" header presence and value.
887
888    If a parameter is given, the mime described will be also checked
889    against the "Content-Type" header.
890
891    Meaning of the parameters is as follows:
892      * mime - mime to be checked against the "Content-Type" header. If not
893        present or 0, this check will be disabled.
894
895    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
896    FAILURE_ROUTE and BRANCH_ROUTE.
897
898    Example 1.32. has_body usage
899 ...
900 if(has_body("application/sdp"))
901 {
902     # do interesting stuff here
903 }
904 ...
905
906 3.33. is_audio_on_hold()
907
908    The function returns true if the SIP message has a body attached and at
909    least one audio stream in on hold.
910
911    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
912    FAILURE_ROUTE and BRANCH_ROUTE.
913
914    Example 1.33. is_audio_on_hold usage
915 ...
916 if(is_audio_on_hold())
917 {
918     # do interesting stuff here
919 }
920 ...
921
922 3.34. is_privacy(privacy_type)
923
924    The function returns true if the SIP message has a Privacy header field
925    that includes the given privacy_type among its privacy values. See
926    http://www.iana.org/assignments/sip-priv-values for possible privacy
927    type values.
928
929    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
930    FAILURE_ROUTE and BRANCH_ROUTE.
931
932    Example 1.34. is_privacy usage
933 ...
934 if(is_privacy("id"))
935 {
936     # do interesting stuff here
937 }
938 ...
939
940 3.35. in_list(subject, list, separator)
941
942    Function checks if subject string is found in list string where list
943    items are separated by separator string. Subject and list strings may
944    contain pseudo variables. Separator string needs to be one character
945    long. Returns 1 if subject is found and -1 otherwise.
946
947    Function can be used from all kinds of routes.
948
949    Example 1.35. in_list() usage
950 ...
951 $var(subject) = "fi";
952 $var(list) = "dk,fi,no,se";
953 if (in_list("$var(subject)", "$var(list)", ",") {
954     xlog("L_INFO", "subject is found in list\n");
955 }
956 ...
957
958 3.36. cmp_str(str1, str2)
959
960    The function returns true if the two parameters matches as string case
961    sensitive comparison.
962
963    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
964    FAILURE_ROUTE and BRANCH_ROUTE.
965
966    Example 1.36. cmp_str usage
967 ...
968 if(cmp_str("$rU", "kamailio"))
969 {
970     # do interesting stuff here
971 }
972 ...
973
974 3.37. cmp_istr(str1, str2)
975
976    The function returns true if the two parameters matches as string case
977    insensitive comparison.
978
979    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
980    FAILURE_ROUTE and BRANCH_ROUTE.
981
982    Example 1.37. cmp_str usage
983 ...
984 if(cmp_istr("$rU@you", "kamailio@YOU"))
985 {
986     # do interesting stuff here
987 }
988 ...
989
990 3.38. starts_with(str1, str2)
991
992    The function returns true if the first string starts with the second
993    string.
994
995    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
996    FAILURE_ROUTE and BRANCH_ROUTE.
997
998    Example 1.38. starts_with usage
999 ...
1000 if (starts_with("$rU", "+358"))
1001 {
1002     # do interesting stuff here
1003 }
1004 ...
1005
1006 4. Known Limitations
1007
1008    Search functions are applied to the original request, i.e., they ignore
1009    all changes resulting from message processing in Kamailio script.
1010
1011 Chapter 2. Developer Guide
1012
1013    Table of Contents
1014
1015    1. Functions
1016
1017         1.1. load_textops(*import_structure)
1018
1019 1. Functions
1020
1021    1.1. load_textops(*import_structure)
1022
1023 1.1. load_textops(*import_structure)
1024
1025    For programmatic use only--import the Textops API.
1026
1027    Meaning of the parameters is as follows:
1028      * import_structure - Pointer to the import structure - see "struct
1029        textops_binds" in modules/textops/api.h