modules: readme files regenerated - siputils ... [skip ci]
[sip-router] / src / modules / siputils / README
1 siputils
2
3 Hardy Kahl
4
5    1&1 Internet AG
6
7 Henning Westerholt
8
9    1&1 Internet AG
10
11 Nils Ohlmeier
12
13    FhG Fokus
14
15 Jan Janak
16
17    FhG FOKUS
18
19 Daniel-Constantin Mierla
20
21    asipto.com
22
23 Gabriel Vasile
24
25    FhG FOKUS
26
27 Juha Heinanen
28
29    TutPro Inc.
30
31 Edited by
32
33 Jan Janak
34
35 Edited by
36
37 Bogdan-Andrei Iancu
38
39 Edited by
40
41 Gabriel Vasile
42
43    Copyright © 2008, 2005, 2003 1&1 Internet AG, FhG Fokus, Voice Sistem
44    SRL
45      __________________________________________________________________
46
47    Table of Contents
48
49    1. Admin Guide
50
51         1. Overview
52         2. Dependencies
53
54               2.1. Kamailio Modules
55               2.2. External Libraries or Applications
56
57         3. Parameters
58
59               3.1. ring_timeout (int)
60               3.2. options_accept (string)
61               3.3. options_accept_encoding (string)
62               3.4. contact_flds_separator (string)
63               3.5. options_accept_language (string)
64               3.6. options_support (string)
65               3.7. rpid_prefix (string)
66               3.8. rpid_suffix (string)
67               3.9. rpid_avp (string)
68
69         4. Functions
70
71               4.1. ring_insert_callid()
72               4.2. options_reply()
73               4.3. is_user(username)
74               4.4. has_totag()
75               4.5. uri_param(param)
76               4.6. uri_param(param,value)
77               4.7. add_uri_param(param)
78               4.8. get_uri_param(name, var)
79               4.9. tel2sip(uri, hostpart, result)
80               4.10. is_e164(pseudo-variable)
81               4.11. is_uri_user_e164(pseudo-variable)
82               4.12. is_tel_number(tval)
83               4.13. is_numeric(tval)
84               4.14. is_alphanum(tval)
85               4.15. is_alphanumex(tval, eset)
86               4.16. encode_contact(encoding_prefix,hostpart)
87               4.17. decode_contact()
88               4.18. decode_contact_header()
89               4.19. cmp_uri(str1, str2)
90               4.20. cmp_aor(str1, str2)
91               4.21. append_rpid_hf()
92               4.22. append_rpid_hf(prefix, suffix)
93               4.23. is_rpid_user_e164()
94               4.24. set_uri_user(uri, user)
95               4.25. set_uri_host(uri, host)
96               4.26. is_request()
97               4.27. is_reply()
98               4.28. is_gruu([uri])
99               4.29. is_supported(option)
100               4.30. is_first_hop()
101               4.31. sip_p_charging_vector(flags)
102
103         5. Exported pseudo-variables
104
105               5.1. $pcv(all)
106               5.2. $pcv(value)
107               5.3. $pcv(genaddr)
108               5.4. $pcv(orig)
109               5.5. $pcv(term)
110
111    List of Examples
112
113    1.1. Set ring_timeout parameter
114    1.2. Set options_accept parameter
115    1.3. Set options_accept_encoding parameter
116    1.4. Set contact_flds_separator parameter
117    1.5. Set options_accept_language parameter
118    1.6. Set options_support parameter
119    1.7. rpid_prefix parameter example
120    1.8. rpid_suffix parameter example
121    1.9. rpid_avp parameter example
122    1.10. ring_insert_callid() usage
123    1.11. options_reply usage
124    1.12. is_user usage
125    1.13. has_totag usage
126    1.14. uri_param usage
127    1.15. uri_param usage
128    1.16. add_uri_param usage
129    1.17. add_uri_param usage
130    1.18. tel2sip usage
131    1.19. is_e164 usage
132    1.20. is_uri_user_e164 usage
133    1.21. is_tel_number usage
134    1.22. is_numeric usage
135    1.23. is_alphanum usage
136    1.24. is_alphanumex usage
137    1.25. encode_contact usage
138    1.26. decode_contact usage
139    1.27. decode_contact_header usage
140    1.28. cmp_uri usage
141    1.29. cmp_aor usage
142    1.30. append_rpid_hf usage
143    1.31. append_rpid_hf(prefix, suffix) usage
144    1.32. is_rpid_user_e164 usage
145    1.33. set_uri_user usage
146    1.34. set_uri_host usage
147    1.35. is_request usage
148    1.36. is_reply usage
149    1.37. is_gruu() usage
150    1.38. is_supported() usage
151    1.39. is_first_hop() usage
152    1.40. sip_p_charging_vector() usage
153
154 Chapter 1. Admin Guide
155
156    Table of Contents
157
158    1. Overview
159    2. Dependencies
160
161         2.1. Kamailio Modules
162         2.2. External Libraries or Applications
163
164    3. Parameters
165
166         3.1. ring_timeout (int)
167         3.2. options_accept (string)
168         3.3. options_accept_encoding (string)
169         3.4. contact_flds_separator (string)
170         3.5. options_accept_language (string)
171         3.6. options_support (string)
172         3.7. rpid_prefix (string)
173         3.8. rpid_suffix (string)
174         3.9. rpid_avp (string)
175
176    4. Functions
177
178         4.1. ring_insert_callid()
179         4.2. options_reply()
180         4.3. is_user(username)
181         4.4. has_totag()
182         4.5. uri_param(param)
183         4.6. uri_param(param,value)
184         4.7. add_uri_param(param)
185         4.8. get_uri_param(name, var)
186         4.9. tel2sip(uri, hostpart, result)
187         4.10. is_e164(pseudo-variable)
188         4.11. is_uri_user_e164(pseudo-variable)
189         4.12. is_tel_number(tval)
190         4.13. is_numeric(tval)
191         4.14. is_alphanum(tval)
192         4.15. is_alphanumex(tval, eset)
193         4.16. encode_contact(encoding_prefix,hostpart)
194         4.17. decode_contact()
195         4.18. decode_contact_header()
196         4.19. cmp_uri(str1, str2)
197         4.20. cmp_aor(str1, str2)
198         4.21. append_rpid_hf()
199         4.22. append_rpid_hf(prefix, suffix)
200         4.23. is_rpid_user_e164()
201         4.24. set_uri_user(uri, user)
202         4.25. set_uri_host(uri, host)
203         4.26. is_request()
204         4.27. is_reply()
205         4.28. is_gruu([uri])
206         4.29. is_supported(option)
207         4.30. is_first_hop()
208         4.31. sip_p_charging_vector(flags)
209
210    5. Exported pseudo-variables
211
212         5.1. $pcv(all)
213         5.2. $pcv(value)
214         5.3. $pcv(genaddr)
215         5.4. $pcv(orig)
216         5.5. $pcv(term)
217
218 1. Overview
219
220    This module implement various functions and checks related to SIP
221    message handling and URI handling.
222
223    It offers some functions related to handle ringing. In a parallel
224    forking scenario you get several 183s with SDP. You don't want that
225    your customers hear more than one ringtone or answer machine in
226    parallel on the phone. So its necessary to drop the 183 in this cases
227    and send a 180 instead.
228
229    This module also provides a function to answer OPTIONS requests which
230    are directed to the server itself. This means an OPTIONS request which
231    has the address of the server in the request URI, and no username in
232    the URI. The request will be answered with a 200 OK with the
233    capabilities of the server.
234
235    To answer OPTIONS request directed to your server is the easiest way
236    for is-alive-tests on the SIP (application) layer from remote (similar
237    to ICMP echo requests, also known as “ping”, on the network layer).
238
239 2. Dependencies
240
241    2.1. Kamailio Modules
242    2.2. External Libraries or Applications
243
244 2.1. Kamailio Modules
245
246    The following modules must be loaded before this module:
247      * sl -- Stateless replies.
248
249 2.2. External Libraries or Applications
250
251    The following libraries or applications must be installed before
252    running Kamailio with this module loaded:
253      * None.
254
255 3. Parameters
256
257    3.1. ring_timeout (int)
258    3.2. options_accept (string)
259    3.3. options_accept_encoding (string)
260    3.4. contact_flds_separator (string)
261    3.5. options_accept_language (string)
262    3.6. options_support (string)
263    3.7. rpid_prefix (string)
264    3.8. rpid_suffix (string)
265    3.9. rpid_avp (string)
266
267 3.1. ring_timeout (int)
268
269    Timeout value in seconds, define how long the call-id is stored in the
270    internal list kept for replacing 183 messages with 180. A reasonable
271    value is “30”.
272
273    Default value is “0”. This means functionality is disabled.
274
275    Example 1.1. Set ring_timeout parameter
276 ...
277 modparam("siputils", "ring_timeout", 30)
278 ...
279
280 3.2. options_accept (string)
281
282    This parameter is the content of the Accept header field. Note: it is
283    not clearly written in RFC3261 if a proxy should accept any content
284    (the default “*/*”) because it does not care about content. Or if it
285    does not accept any content, which is “”.
286
287    Default value is “*/*”.
288
289    Example 1.2. Set options_accept parameter
290 ...
291 modparam("siputils", "options_accept", "application/*")
292 ...
293
294 3.3. options_accept_encoding (string)
295
296    This parameter is the content of the Accept-Encoding header field.
297    Please do not change the default value because Kamailio does not
298    support any encodings yet.
299
300    Default value is “”.
301
302    Example 1.3. Set options_accept_encoding parameter
303 ...
304 modparam("siputils", "options_accept_encoding", "gzip")
305 ...
306
307 3.4. contact_flds_separator (string)
308
309    First char of this parameter is used as separator for encoding/decoding
310    Contact header.
311
312 Warning
313
314    First char of this field must be set to a value which is not used
315    inside username,password or other fields of contact. Otherwise it is
316    possible for the decoding step to fail/produce wrong results.
317
318    Default value is “*”.
319
320    Example 1.4. Set contact_flds_separator parameter
321 ...
322 modparam("siputils", "contact_flds_separator", "-")
323 ...
324
325    then an encoded uri might look
326    sip:user-password-ip-port-protocol@PublicIP
327
328 3.5. options_accept_language (string)
329
330    This parameter is the content of the Accept-Language header field. You
331    can set any language code which you prefer for error descriptions from
332    other devices, but presumably there are not many devices around which
333    support other languages than the default English.
334
335    Default value is “en”.
336
337    Example 1.5. Set options_accept_language parameter
338 ...
339 modparam("siputils", "options_accept_language", "de")
340 ...
341
342 3.6. options_support (string)
343
344    This parameter is the content of the Support header field, indicating
345    SIP extensions. Please do not change the default value, because
346    Kamailio currently does not support any of the SIP extensions
347    registered at the IANA.
348
349    Default value is “”.
350
351    Example 1.6. Set options_support parameter
352 ...
353 modparam("siputils", "options_support", "100rel")
354 ...
355
356 3.7. rpid_prefix (string)
357
358    Prefix to be added to Remote-Party-ID header field just before the URI
359    returned from either radius or database.
360
361    Default value is “”.
362
363    Example 1.7. rpid_prefix parameter example
364 modparam("auth", "rpid_prefix", "Whatever <")
365
366 3.8. rpid_suffix (string)
367
368    Suffix to be added to Remote-Party-ID header field after the URI
369    returned from either radius or database.
370
371    Default value is “;party=calling;id-type=subscriber;screen=yes”.
372
373    Example 1.8. rpid_suffix parameter example
374 modparam("auth", "rpid_suffix", "@1.2.3.4>")
375
376 3.9. rpid_avp (string)
377
378    Full AVP specification for the AVP which stores the RPID value. It used
379    to transport the RPID value from authentication backend modules
380    (auth_db or auth_radius) or from script to the auth function
381    append_rpid_hf and is_rpid_user_e164.
382
383    If defined to NULL string, all RPID functions will fail at runtime.
384
385    Default value is “$avp(s:rpid)”.
386
387    Example 1.9. rpid_avp parameter example
388 modparam("auth", "rpid_avp", "$avp(myrpid)")
389
390 4. Functions
391
392    4.1. ring_insert_callid()
393    4.2. options_reply()
394    4.3. is_user(username)
395    4.4. has_totag()
396    4.5. uri_param(param)
397    4.6. uri_param(param,value)
398    4.7. add_uri_param(param)
399    4.8. get_uri_param(name, var)
400    4.9. tel2sip(uri, hostpart, result)
401    4.10. is_e164(pseudo-variable)
402    4.11. is_uri_user_e164(pseudo-variable)
403    4.12. is_tel_number(tval)
404    4.13. is_numeric(tval)
405    4.14. is_alphanum(tval)
406    4.15. is_alphanumex(tval, eset)
407    4.16. encode_contact(encoding_prefix,hostpart)
408    4.17. decode_contact()
409    4.18. decode_contact_header()
410    4.19. cmp_uri(str1, str2)
411    4.20. cmp_aor(str1, str2)
412    4.21. append_rpid_hf()
413    4.22. append_rpid_hf(prefix, suffix)
414    4.23. is_rpid_user_e164()
415    4.24. set_uri_user(uri, user)
416    4.25. set_uri_host(uri, host)
417    4.26. is_request()
418    4.27. is_reply()
419    4.28. is_gruu([uri])
420    4.29. is_supported(option)
421    4.30. is_first_hop()
422    4.31. sip_p_charging_vector(flags)
423
424 4.1.  ring_insert_callid()
425
426    Inserting the call-id in the internal list, which is checked when
427    further replies arrive. Any 183 reply that is received during the
428    timeout value will be converted to a 180 message. Please note that you
429    need to set a positive timeout value in order to use this function.
430
431    The function returns TRUE on success, and FALSE during processing
432    failures.
433
434    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
435
436    Example 1.10. ring_insert_callid() usage
437 ...
438 ring_insert_callid();
439 ...
440
441 4.2.  options_reply()
442
443    This function checks if the request method is OPTIONS and if the
444    request URI does not contain an username. If both is true the request
445    will be answered stateless with “200 OK” and the capabilities from the
446    modules parameters.
447
448    It sends “500 Server Internal Error” for some errors and returns false
449    if it is called for a wrong request.
450
451    The check for the request method and the missing username is optional
452    because it is also done by the function itself. But you should not call
453    this function outside the myself check because in this case the
454    function could answer OPTIONS requests which are sent to you as
455    outbound proxy but with an other destination then your proxy (this
456    check is currently missing in the function).
457
458    This function can be used from REQUEST_ROUTE.
459
460    Example 1.11. options_reply usage
461 ...
462 if (uri==myself) {
463         if ((method==OPTIONS) && (! uri=~"sip:.*[@]+.*")) {
464                 options_reply();
465         }
466 }
467 ...
468
469 4.3.  is_user(username)
470
471    Check if the username in credentials matches the given username.
472
473    Meaning of the parameters is as follows:
474      * username - Username string.
475
476    This function can be used from REQUEST_ROUTE.
477
478    Example 1.12. is_user usage
479 ...
480 if (is_user("john")) {
481         ...
482 };
483 ...
484
485 4.4.  has_totag()
486
487    Check if To header field uri contains tag parameter.
488
489    This function can be used from ANY_ROUTE.
490
491    Example 1.13. has_totag usage
492 ...
493 if (has_totag()) {
494         ...
495 };
496 ...
497
498 4.5.  uri_param(param)
499
500    Find if Request URI has a given parameter with no value
501
502    Meaning of the parameters is as follows:
503      * param - parameter name to look for.
504
505    This function can be used from REQUEST_ROUTE.
506
507    Example 1.14. uri_param usage
508 ...
509 if (uri_param("param1")) {
510         ...
511 };
512 ...
513
514 4.6.  uri_param(param,value)
515
516    Find if Request URI has a given parameter with matching value
517
518    Meaning of the parameters is as follows:
519      * param - parameter name to look for.
520      * value - parameter value to match.
521
522    This function can be used from REQUEST_ROUTE.
523
524    Example 1.15. uri_param usage
525 ...
526 if (uri_param("param1","value1")) {
527         ...
528 };
529 ...
530
531 4.7.  add_uri_param(param)
532
533    Add to RURI a parameter (name=value);
534
535    Meaning of the parameters is as follows:
536      * param - parameter to be appended in “name=value” format.
537
538    This function can be used from REQUEST_ROUTE.
539
540    Example 1.16. add_uri_param usage
541 ...
542 add_uri_param("nat=yes");
543 ...
544
545 4.8.  get_uri_param(name, var)
546
547    Get the value of RURI parameter.
548
549    Meaning of the parameters is as follows:
550      * name - the name of R-URI parameter
551      * var - the variable where to store the value of the parameter
552
553    This function can be used from REQUEST_ROUTE.
554
555    Example 1.17. add_uri_param usage
556 ...
557 get_uri_param("nat", "$var(nat)");
558 ...
559
560 4.9.  tel2sip(uri, hostpart, result)
561
562    Converts URI in first param (pseudo variable or string) to SIP URI, if
563    it is a tel URI. If conversion was done, writes resulting SIP URI to
564    third param (pseudo variable). Returns 1 if conversion succeeded or if
565    no conversion was needed.
566
567    The conversion follows the rules in RFC 3261 section 19.1.6:
568      * Visual separators ( "-", ".", "(", ")" ) are removed from tel URI
569        number before converting it to SIP URI userinfo.
570      * tel URI parameters are downcased before appending them to SIP URI
571        userinfo
572
573    The SIP URI hostpart is taken from second param (pseudo variable or
574    string).
575
576    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
577    BRANCH_ROUTE, or ONREPLY_ROUTE.
578
579    Example 1.18. tel2sip usage
580 ...
581 # $ru: tel:+(34)-999-888-777
582 # $fu: sip:test@foo.com
583 tel2sip("$ru", $fd", "$ru");
584 # $ru:  sip:+34999888777@foo.com;user=phone
585
586 # $ru: tel:+12-(34)-56-78;Ext=200;ISUB=+123-456
587 # $fu: sip:test@foo.com
588 tel2sip("$ru", $fd", "$ru");
589 # $ru:  sip:+12345678;ext=200;isub=+123-456@foo.com;user=phone
590 ...
591
592 4.10.  is_e164(pseudo-variable)
593
594    Checks if string value of pseudo variable argument is an E164 number.
595
596    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, and
597    LOCAL_ROUTE.
598
599    Example 1.19. is_e164 usage
600 ...
601 if (is_164("$fU")) {  # Check From header URI user part
602    ...
603 }
604 if (is_e164("$avp(i:705)") {
605    # Check stgring value stored in avp i:705
606    ...
607 };
608 ...
609
610 4.11.  is_uri_user_e164(pseudo-variable)
611
612    Checks if userpart of URI stored in pseudo variable is E164 number.
613
614    This function can be used from ANY_ROUTE.
615
616    Example 1.20. is_uri_user_e164 usage
617 ...
618 if (is_uri_user_e164("$fu")) {  # Check From header URI user part
619    ...
620 }
621 if (is_uri_user_e164("$avp(i:705)") {
622    # Check user part of URI stored in avp i:705
623    ...
624 };
625 ...
626
627 4.12.  is_tel_number(tval)
628
629    Checks if the parameter value is a telephone number: starting with one
630    optional +, followed by digits. The parameter can include variables.
631
632    This function can be used from ANY_ROUTE.
633
634    Example 1.21. is_tel_number usage
635 ...
636 if (is_tel_number("$rU")) {  # Test if R-URI user is telephone number
637    ...
638 }
639 if (is_tel_number("+24242424") {
640    ...
641 }
642 ...
643
644 4.13.  is_numeric(tval)
645
646    Checks if the parameter value consists solely of decimal digits. The
647    parameter can include variables.
648
649    This function can be used from ANY_ROUTE.
650
651    Example 1.22. is_numeric usage
652 ...
653 if (is_numeric("$rU")) {  # Test if R-URI user consists of decimal digits
654    ...
655 }
656 ...
657
658 4.14.  is_alphanum(tval)
659
660    Checks if the parameter value consists solely of decimal digits or
661    alphabetic ASCII characters. The parameter can include variables.
662
663    This function can be used from ANY_ROUTE.
664
665    Example 1.23. is_alphanum usage
666 ...
667 if (is_alphanum("$rU")) {
668    ...
669 }
670 ...
671
672 4.15.  is_alphanumex(tval, eset)
673
674    Checks if the value of parameter 'tval' consists solely of decimal
675    digits, alphabetic ASCII characters and the characters in the second
676    parameter 'eset'. The parameters can include variables.
677
678    This function can be used from ANY_ROUTE.
679
680    Example 1.24. is_alphanumex usage
681 ...
682 if (is_alphanumex("$rU", "+.-_")) {
683    ...
684 }
685 ...
686
687 4.16.  encode_contact(encoding_prefix,hostpart)
688
689    This function will encode uri-s inside Contact header in the following
690    manner sip:username:password@ip:port;transport=protocol goes
691    sip:encoding_prefix*username*ip*port*protocol@hostpart.
692
693    * is the default separator and can be changed by setting the
694    contact_flds_separator module parameter.
695
696    Note: This function discards all of the URI parameters. Thus, none of
697    the parameters (except the transport parameter which is encoded into
698    the userpart) can be restored.
699
700    The function returns negative on error, 1 on success.
701
702    Meaning of the parameters is as follows:
703      * encoding_prefix - Something to allow us to determine that a contact
704        is encoded.
705      * hostpart - An IP address or a hostname.
706
707    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
708
709    Example 1.25. encode_contact usage
710 ...
711 if (src_ip == 10.0.0.0/8) encode_contact("natted_client","1.2.3.4");
712 ...
713
714 4.17.  decode_contact()
715
716    This function will decode the request URI. If the RURI is in the format
717    sip:encoding_prefix*username*ip*port*protocol@hostpart it will be
718    decoded to sip:username:password@ip:port;transport=protocol It uses the
719    default set parameter for contact encoding separator.
720
721    The function returns negative on error, 1 on success.
722
723    Meaning of the parameters is as follows:
724
725    This function can be used from REQUEST_ROUTE.
726
727    Example 1.26. decode_contact usage
728 ...
729 if (uri =~ "^sip:natted_client") { decode_contact(); }
730 ...
731
732 4.18.  decode_contact_header()
733
734    This function will decode URIs inside Contact header. If the URI in the
735    format sip:encoding_prefix*username*ip*port*protocol@hostpart it will
736    be decoded to sip:username:password@ip:port;transport=protocol. It uses
737    the default set parameter for contact encoding separator.
738
739    The function returns negative on error, 1 on success.
740
741    Meaning of the parameters is as follows:
742
743    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
744
745    Example 1.27. decode_contact_header usage
746 ...
747 reply_route[2] {
748         ...
749         decode_contact_header();
750         ...
751 }
752 ...
753
754 4.19.  cmp_uri(str1, str2)
755
756    The function returns true if the two parameters matches as SIP URI.
757
758    This function can be used from ANY_ROUTE.
759
760    Example 1.28. cmp_uri usage
761 ...
762 if(cmp_uri("$ru", "sip:kamailio@kamailio.org"))
763 {
764     # do interesting stuff here
765 }
766 ...
767
768 4.20.  cmp_aor(str1, str2)
769
770    The function returns true if the two parameters matches as AoR. The
771    parameters have to be SIP URIs.
772
773    This function can be used from ANY_ROUTE.
774
775    Example 1.29. cmp_aor usage
776 ...
777 if(cmp_aor("$rU@KaMaIlIo.org", "sip:kamailio@$fd"))
778 {
779     # do interesting stuff here
780 }
781 ...
782
783 4.21.  append_rpid_hf()
784
785    Appends to the message a Remote-Party-ID header that contains header
786    'Remote-Party-ID: ' followed by the saved value of the SIP URI received
787    from the database or radius server followed by the value of module
788    parameter radius_rpid_suffix. The function does nothing if no saved SIP
789    URI exists.
790
791    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
792    BRANCH_ROUTE.
793
794    Example 1.30. append_rpid_hf usage
795 ...
796 append_rpid_hf();  # Append Remote-Party-ID header field
797 ...
798
799 4.22.  append_rpid_hf(prefix, suffix)
800
801    This function is the same as Section 4.21, “ append_rpid_hf()”. The
802    only difference is that it accepts two parameters--prefix and suffix to
803    be added to Remote-Party-ID header field. This function ignores
804    rpid_prefix and rpid_suffix parameters, instead of that allows to set
805    them in every call.
806
807    Meaning of the parameters is as follows:
808      * prefix - Prefix of the Remote-Party-ID URI. The string will be
809        added at the begining of body of the header field, just before the
810        URI.
811      * suffix - Suffix of the Remote-Party-ID header field. The string
812        will be appended at the end of the header field. It can be used to
813        set various URI parameters, for example.
814
815    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
816    BRANCH_ROUTE.
817
818    Example 1.31. append_rpid_hf(prefix, suffix) usage
819 ...
820 # Append Remote-Party-ID header field
821 append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");
822 ...
823
824 4.23.  is_rpid_user_e164()
825
826    The function checks if the SIP URI received from the database or radius
827    server and will potentially be used in Remote-Party-ID header field
828    contains an E164 number (+followed by up to 15 decimal digits) in its
829    user part. Check fails, if no such SIP URI exists (i.e. radius server
830    or database didn't provide this information).
831
832    This function can be used from REQUEST_ROUTE.
833
834    Example 1.32. is_rpid_user_e164 usage
835 ...
836 if (is_rpid_user_e164()) {
837     # do something here
838 };
839 ...
840
841 4.24.  set_uri_user(uri, user)
842
843    Sets userpart of SIP URI stored in writable pseudo variable 'uri' to
844    value of pseudo variable 'user'.
845
846    This function can be used from ANY_ROUTE.
847
848    Example 1.33. set_uri_user usage
849 ...
850 $var(uri) = "sip:user@host";
851 $var(user) = "new_user";
852 set_uri_user("$var(uri)", "$var(user)");
853 ...
854
855 4.25.  set_uri_host(uri, host)
856
857    Sets hostpart of SIP URI stored in writable pseudo variable 'uri' to
858    value of pseudo variable 'host'.
859
860    This function can be used from ANY_ROUTE.
861
862    Example 1.34. set_uri_host usage
863 ...
864 $var(uri) = "sip:user@host";
865 $var(host) = "new_host";
866 set_uri_host("$var(uri)", "$var(host)");
867 ...
868
869 4.26.  is_request()
870
871    Return true if the SIP message is a request.
872
873    This function can be used from ANY_ROUTE.
874
875    Example 1.35. is_request usage
876 ...
877 if (is_request()) {
878         ...
879 }
880 ...
881
882 4.27.  is_reply()
883
884    Return true if the SIP message is a reply.
885
886    This function can be used from ANY_ROUTE.
887
888    Example 1.36. is_reply usage
889 ...
890 if (is_reply()) {
891         ...
892 }
893 ...
894
895 4.28.  is_gruu([uri])
896
897    The function returns true if the uri is GRUU ('gr' parameter is
898    present): 1 - pub-gruu; 2 - temp-gruu.
899
900    Meaning of the parameters is as follows:
901      * uri - the SIP URI to check for GRUU parameter. It is optional, when
902        missing, the value of R-URI is used.
903
904    This function can be used from ANY_ROUTE.
905
906    Example 1.37. is_gruu() usage
907 ...
908 if(is_gruu()) { ... }
909 ...
910
911 4.29.  is_supported(option)
912
913    Function returns true if given option is listed in Supported header(s)
914    (if any) of the request. Currently the following options are known:
915    path, 100rel, timer, eventlist, gruu, and outbound.
916
917    This function can be used from ANY_ROUTE.
918
919    Example 1.38. is_supported() usage
920 ...
921 if (is_supported("outbound")) { ... }
922 ...
923
924 4.30.  is_first_hop()
925
926    The function returns true if the proxy is first hop after the original
927    sender. For incoming SIP requests, it means there is only one Via
928    header. For incoming SIP replies, it means that top Record-Route URI is
929    'myself' and source address is not matching it (to avoid detecting in
930    case of local loops). Note that it does not detect spirals, which can
931    have the condition for replies true also in the case of additional SIP
932    reply receival.
933
934    This function can be used from ANY_ROUTE.
935
936    Example 1.39. is_first_hop() usage
937 ...
938 if(is_first_hop()) { ... }
939 ...
940
941 4.31.  sip_p_charging_vector(flags)
942
943    Manage the P-Charging-Vector header (RFC7315). The flags can be: 'r' -
944    remove; 'g' - generate; 'f' - force (remove + generate).
945
946    This function can be used from ANY_ROUTE.
947
948    Example 1.40. sip_p_charging_vector() usage
949 ...
950 sip_p_charging_vector("g");
951 ...
952
953 5. Exported pseudo-variables
954
955    5.1. $pcv(all)
956    5.2. $pcv(value)
957    5.3. $pcv(genaddr)
958    5.4. $pcv(orig)
959    5.5. $pcv(term)
960
961 5.1. $pcv(all)
962
963    full P-Charging-Vector header
964
965 5.2. $pcv(value)
966
967    icid-value field (see RFC7315 section 5.6)
968
969 5.3. $pcv(genaddr)
970
971    icid-generated-at field (see RFC7315 section 5.6)
972
973 5.4. $pcv(orig)
974
975    orig-ioi field (see RFC7315 section 5.6)
976
977 5.5. $pcv(term)
978
979    term-ioi field (see RFC7315 section 5.6)