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