git.sip-router.org Git - sip-router/blob - 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)