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