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