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