"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/sipmsgops/README" (1 Oct 2019, 35106 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 sipmsgops Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. Dependencies
   10 
   11               1.2.1. OpenSIPS Modules
   12               1.2.2. External Libraries or Applications
   13 
   14         1.3. Exported Functions
   15 
   16               1.3.1. append_to_reply(txt)
   17               1.3.2. append_hf(txt[, hdr_anchor])
   18               1.3.3. insert_hf(txt)
   19               1.3.4. insert_hf(txt, hdr)
   20               1.3.5. append_urihf(prefix, suffix)
   21               1.3.6. is_present_hf(hf_name)
   22               1.3.7. append_time()
   23               1.3.8. is_method(name)
   24               1.3.9. remove_hf(hname)
   25               1.3.10. remove_hf_re(hname_expr)
   26               1.3.11. remove_hf_glob(hname_pattern)
   27               1.3.12. has_totag()
   28               1.3.13. ruri_has_param(param[,value])
   29               1.3.14. ruri_add_param(param)
   30               1.3.15. ruri_del_param(param)
   31               1.3.16. ruri_tel2sip()
   32               1.3.17. is_uri_user_e164(uri)
   33               1.3.18. has_body_part([mime])
   34               1.3.19. is_audio_on_hold()
   35               1.3.20. is_privacy(privacy_type)
   36               1.3.21. remove_body_part([mime[, revert]])
   37               1.3.22. add_body_part(body, mime[, headers])
   38               1.3.23. sipmsg_validate([flags[, result_pvar]])
   39               1.3.24. codec_exists (name[, clock])
   40               1.3.25. codec_delete(name[, clock])
   41               1.3.26. codec_move_up(name[, clock])
   42               1.3.27. codec_move_down(name[, clock])
   43               1.3.28. codec_exists_re ( regexp )
   44               1.3.29. codec_delete_re ( regexp )
   45               1.3.30. codec_delete_except_re ( regexp )
   46               1.3.31. codec_move_up_re ( regexp )
   47               1.3.32. codec_move_down_re ( regexp )
   48               1.3.33. change_reply_status(code, reason)
   49               1.3.34. stream_exists(regexp)
   50               1.3.35. stream_delete(regexp)
   51               1.3.36. list_hdr_has_option(hdr_name, option)
   52               1.3.37. list_hdr_add_option(hdr_name, option)
   53               1.3.38. list_hdr_remove_option(hdr_name, option)
   54 
   55         1.4. Known Limitations
   56 
   57    2. Contributors
   58 
   59         2.1. By Commit Statistics
   60         2.2. By Commit Activity
   61 
   62    3. Documentation
   63 
   64         3.1. Contributors
   65 
   66    List of Tables
   67 
   68    2.1. Top contributors by DevScore^(1), authored commits^(2) and
   69           lines added/removed^(3)
   70 
   71    2.2. Most recently active contributors^(1) to this module
   72 
   73    List of Examples
   74 
   75    1.1. append_to_reply usage
   76    1.2. append_hf usage
   77    1.3. insert_hf usage
   78    1.4. insert_hf usage
   79    1.5. append_urihf usage
   80    1.6. is_present_hf usage
   81    1.7. append_time usage
   82    1.8. is_method usage
   83    1.9. remove_hf usage
   84    1.10. remove_hf_re usage
   85    1.11. remove_hf_glob usage
   86    1.12. has_totag usage
   87    1.13. ruri_has_param usage
   88    1.14. ruri_add_param usage
   89    1.15. ruri_del_param usage
   90    1.16. ruri_tel2sip usage
   91    1.17. is_uri_user_e164 usage
   92    1.18. has_body_part usage
   93    1.19. is_audio_on_hold usage
   94    1.20. is_privacy usage
   95    1.21. remove_body_part() usage
   96    1.22. add_body_part usage
   97    1.23. sipmsg_validate usage
   98    1.24. codec_exists usage
   99    1.25. codec_delete usage
  100    1.26. codec_move_up usage
  101    1.27. codec_move_down usage
  102    1.28. codec_move_down usage
  103    1.29. codec_exists_re usage
  104    1.30. codec_delete_re usage
  105    1.31. codec_delete_except_re usage
  106    1.32. codec_move_up_re usage
  107    1.33. codec_move_down_re usage
  108    1.34. codec_move_down usage
  109    1.35. change_reply_status usage
  110    1.36. stream_exists usage
  111    1.37. stream_delete usage
  112    1.38. list_hdr_has_option usage
  113    1.39. list_hdr_add_option usage
  114    1.40. list_hdr_remove_option usage
  115 
  116 Chapter 1. Admin Guide
  117 
  118 1.1. Overview
  119 
  120    The module implements SIP based operations over the messages
  121    processed by OpenSIPS. SIP is a text based protocol and the
  122    module provides a large set of very useful functions to
  123    manipulate the message at SIP level, e.g., inserting new
  124    headers or deleting them, check for method type, etc.
  125 
  126 1.2. Dependencies
  127 
  128 1.2.1. OpenSIPS Modules
  129 
  130    The following modules must be loaded before this module:
  131      * No dependencies on other OpenSIPS modules.
  132 
  133 1.2.2. External Libraries or Applications
  134 
  135    The following libraries or applications must be installed
  136    before running OpenSIPS with this module loaded:
  137      * None.
  138 
  139 1.3. Exported Functions
  140 
  141 1.3.1.  append_to_reply(txt)
  142 
  143    Append 'txt' as header to all replies that will be generated by
  144    OpenSIPS for this request.
  145 
  146    Meaning of the parameters is as follows:
  147      * txt (string) - SIP header field, value and CRLF marker.
  148 
  149    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  150    BRANCH_ROUTE, ERROR_ROUTE.
  151 
  152    Example 1.1. append_to_reply usage
  153 ...
  154 append_to_reply("Foo: bar\r\n");
  155 append_to_reply("Foo: $rm at $Ts\r\n");
  156 ...
  157 
  158 1.3.2.  append_hf(txt[, hdr_anchor])
  159 
  160    Appends 'txt' as header after the last header field. If
  161    'hdr_anchor' is given, 'txt' will be appended after the first
  162    occurrence of 'hdr_anchor' instead.
  163 
  164    Meaning of the parameters is as follows:
  165      * txt (string) - Header field to be appended.
  166      * hdr_anchor (string, optional) - Header name after which the
  167        'txt' is appended.
  168 
  169    Note: Headers which are added in main route cannot be removed
  170    in further routes (e.g. failure routes). So, the idea is not to
  171    add there any headers that you might want to remove later. To
  172    add headers temporarely use the branch route because the
  173    changes you do there are per-branch.
  174 
  175    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  176    FAILURE_ROUTE, BRANCH_ROUTE.
  177 
  178    Example 1.2. append_hf usage
  179 ...
  180 append_hf("P-hint: VOICEMAIL\r\n");
  181 append_hf("From-username: $fU\r\n");
  182 append_hf("From-username: $fU\r\n", "Call-ID");
  183 ...
  184 
  185 1.3.3.  insert_hf(txt)
  186 
  187    Inserts 'txt' as header before the first header field.
  188 
  189    Meaning of the parameters is as follows:
  190      * txt (string) - Header field to be inserted.
  191 
  192    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  193    FAILURE_ROUTE, BRANCH_ROUTE.
  194 
  195    Example 1.3. insert_hf usage
  196 ...
  197 insert_hf("P-hint: VOICEMAIL\r\n");
  198 insert_hf("To-username: $tU\r\n");
  199 ...
  200 
  201 1.3.4.  insert_hf(txt, hdr)
  202 
  203    Inserts 'txt' as header before first 'hdr' header field.
  204 
  205    Meaning of the parameters is as follows:
  206      * txt (string) - Header field to be inserted.
  207      * hdr (string, optional) - Header name before which the 'txt'
  208        is inserted.
  209 
  210    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  211    FAILURE_ROUTE, BRANCH_ROUTE.
  212 
  213    Example 1.4. insert_hf usage
  214 ...
  215 insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
  216 insert_hf("To-username: $tU\r\n", "Call-ID");
  217 ...
  218 
  219 1.3.5.  append_urihf(prefix, suffix)
  220 
  221    Append header field name with original Request-URI in middle.
  222 
  223    Meaning of the parameters is as follows:
  224      * prefix - string (usually at least header field name).
  225      * suffix - string (usually at least line terminator).
  226 
  227    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  228    BRANCH_ROUTE.
  229 
  230    Example 1.5. append_urihf usage
  231 ...
  232 append_urihf("CC-Diversion: ", "\r\n");
  233 ...
  234 
  235 1.3.6.  is_present_hf(hf_name)
  236 
  237    Return true if a header field is present in message.
  238 
  239 Note
  240 
  241    The function is also able to distinguish the compact names. For
  242    exmaple “From” will match with “f”
  243 
  244    Meaning of the parameters is as follows:
  245      * hf_name (string) - Header field name (long or compact
  246        form).
  247 
  248    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  249    FAILURE_ROUTE, BRANCH_ROUTE.
  250 
  251    Example 1.6. is_present_hf usage
  252 ...
  253 if (is_present_hf("From")) log(1, "From HF Present");
  254 ...
  255 
  256 1.3.7.  append_time()
  257 
  258    Adds a time header to the reply of the request. You must use it
  259    before functions that are likely to send a reply, e.g., save()
  260    from 'registrar' module. Header format is: “Date: %a, %d %b %Y
  261    %H:%M:%S GMT”, with the legend:
  262      * %a abbreviated week of day name (locale)
  263      * %d day of month as decimal number
  264      * %b abbreviated month name (locale)
  265      * %Y year with century
  266      * %H hour
  267      * %M minutes
  268      * %S seconds
  269 
  270    Return true if a header was successfully appended.
  271 
  272    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  273    BRANCH_ROUTE.
  274 
  275    Example 1.7. append_time usage
  276 ...
  277 append_time();
  278 ...
  279 
  280 1.3.8.  is_method(name)
  281 
  282    Check if the method of the message matches the name. If name is
  283    a known method (invite, cancel, ack, bye, options, info,
  284    update, register, message, subscribe, notify, refer, prack),
  285    the function performs method ID testing (integer comparison)
  286    instead of ignore case string comparison.
  287 
  288    The 'name' can be a list of methods in the form of
  289    'method1|method2|...'. In this case, the function returns true
  290    if the SIP message's method is one from the list. IMPORTANT
  291    NOTE: in the list must be only methods defined in OpenSIPS with
  292    ID (invite, cancel, ack, bye, options, info, update, register,
  293    message, subscribe, notify, refer, prack, publish; for more
  294    see: https://www.iana.org/assignments/sip-parameters).
  295 
  296    If used for replies, the function tests the value of method
  297    field from CSeq header.
  298 
  299    Meaning of the parameters is as follows:
  300      * name (string) - SIP method name
  301 
  302    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  303    FAILURE_ROUTE, and BRANCH_ROUTE.
  304 
  305    Example 1.8. is_method usage
  306 ...
  307 if(is_method("INVITE"))
  308 {
  309     # process INVITEs here
  310 }
  311 if(is_method("OPTION|UPDATE"))
  312 {
  313     # process OPTIONs and UPDATEs here
  314 }
  315 ...
  316 
  317 1.3.9.  remove_hf(hname)
  318 
  319    Remove from message all headers with name “hname”
  320 
  321    Returns true if at least one header is found and removed.
  322 
  323    Meaning of the parameters is as follows:
  324      * hname (string) - header name to be removed.
  325 
  326    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  327    FAILURE_ROUTE and BRANCH_ROUTE.
  328 
  329    Example 1.9. remove_hf usage
  330 ...
  331 if(remove_hf("User-Agent"))
  332 {
  333     # User Agent header removed
  334 }
  335 ...
  336 
  337 1.3.10.  remove_hf_re(hname_expr)
  338 
  339    Remove from message all headers matching the “hname_expr” POSIX
  340    regular expression.
  341 
  342    Returns true if at least one header is found and removed.
  343 
  344    Meaning of the parameters is as follows:
  345      * hname_expr (string) - regular expression.
  346 
  347    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  348    FAILURE_ROUTE and BRANCH_ROUTE.
  349 
  350    Example 1.10. remove_hf_re usage
  351 ...
  352 remove_hf_re("^X-g.+[0-9]");
  353 ...
  354 
  355 1.3.11.  remove_hf_glob(hname_pattern)
  356 
  357    Remove from message all headers matching the “hname_pattern”
  358    glob pattern.
  359 
  360    Returns true if at least one header is found and removed.
  361 
  362    Meaning of the parameters is as follows:
  363      * hname_pattern (string) - glob pattern
  364 
  365    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  366    FAILURE_ROUTE and BRANCH_ROUTE.
  367 
  368    Example 1.11. remove_hf_glob usage
  369 ...
  370 # removes X-Billing-Account, X-Billing-Price, X-Billing-rateplan, etc
  371 remove_hf_glob("X-Billing*");
  372 ...
  373 
  374 1.3.12.  has_totag()
  375 
  376    Check if To header field uri contains tag parameter.
  377 
  378    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  379    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  380 
  381    Example 1.12. has_totag usage
  382 ...
  383 if (has_totag()) {
  384         ...
  385 };
  386 ...
  387 
  388 1.3.13.  ruri_has_param(param[,value])
  389 
  390    Find if Request URI has a given parameter. If no value is
  391    given, the function will look for the paramter with no value,
  392    oherwise it will search for the parameter with the matching
  393    value.
  394 
  395    Meaning of the parameters is as follows:
  396      * param (string) - parameter name to look for.
  397      * value (string, optional) - parameter value to match.
  398 
  399    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  400    BRANCH_ROUTE and LOCAL_ROUTE.
  401 
  402    Example 1.13. ruri_has_param usage
  403 ...
  404 if (ruri_has_param("user","phone")) {
  405         ...
  406 };
  407 ...
  408 
  409 1.3.14.  ruri_add_param(param)
  410 
  411    Add to RURI an URI parameter formated as "name=value".
  412 
  413    Meaning of the parameters is as follows:
  414      * param (string) - parameter to be appended in “name=value”
  415        format.
  416 
  417    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  418    BRANCH_ROUTE and LOCAL_ROUTE.
  419 
  420    Example 1.14. ruri_add_param usage
  421 ...
  422 ruri_add_param("nat=yes");
  423 ...
  424 
  425 1.3.15.  ruri_del_param(param)
  426 
  427    Delete a parameter from the RURI being given the
  428    key(key=value);
  429 
  430    Meaning of the parameters is as follows:
  431      * param (string) - key of the parameter to be removed/
  432 
  433    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  434    BRANCH_ROUTE and LOCAL_ROUTE.
  435 
  436    Example 1.15. ruri_del_param usage
  437 ...
  438 ruri_del_param("user");
  439 ...
  440 
  441 1.3.16.  ruri_tel2sip()
  442 
  443    Converts RURI, if it is tel URI, to SIP URI. Returns true, only
  444    if conversion succeeded or if no conversion was needed (like
  445    RURI was not tel URI.
  446 
  447    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  448    BRANCH_ROUTE and LOCAL_ROUTE.
  449 
  450    Example 1.16. ruri_tel2sip usage
  451 ...
  452 ruri_tel2sip();
  453 ...
  454 
  455 1.3.17.  is_uri_user_e164(uri)
  456 
  457    Checks if the username part of the given URI is an E164 number.
  458 
  459    Meaning of the parameters is as follows:
  460      * uri (string) - a SIP URI
  461 
  462    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
  463 
  464    Example 1.17. is_uri_user_e164 usage
  465 ...
  466 if (is_uri_user_e164($fu)) {  # Check From header URI user part
  467    ...
  468 }
  469 if (is_uri_user_e164($avp(uri)) {
  470    # Check user part of URI stored in avp uri
  471    ...
  472 };
  473 ...
  474 
  475 1.3.18.  has_body_part([mime])
  476 
  477    The function returns true if the SIP message has any body part
  478    with the given MIME. If there is no MIME given, it will return
  479    true if at least one body part is found (with any MIME).
  480 
  481    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  482    FAILURE_ROUTE and BRANCH_ROUTE.
  483 
  484    Example 1.18. has_body_part usage
  485 ...
  486 if(has_body_part("application/sdp"))
  487 {
  488     # do interesting stuff here
  489 }
  490 ...
  491 
  492 1.3.19.  is_audio_on_hold()
  493 
  494    The function returns true if the SIP message has an SDP body
  495    attached and at least one audio stream in on hold. The return
  496    code of the function indicates the detected hold type:
  497      * 1 - RFC2543 hold type: null connection IP detected
  498      * 2 - RFC3264 hold type: inactive or sendonly attributes
  499        detected
  500 
  501    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  502    FAILURE_ROUTE and BRANCH_ROUTE.
  503 
  504    Example 1.19. is_audio_on_hold usage
  505 ...
  506 if(is_audio_on_hold())
  507 {
  508     switch ($rc) {
  509     case 1:
  510         # RFC2543 hold type
  511         # do interesting stuff here
  512         break;
  513     case 2:
  514         # RFC3264 hold type
  515         # do interesting stuff here
  516         break;
  517 }
  518 ...
  519 
  520 1.3.20.  is_privacy(privacy_type)
  521 
  522    The function returns true if the SIP message has a Privacy
  523    header field that includes the given privacy_type among its
  524    privacy values. See
  525    https://www.iana.org/assignments/sip-parameters/sip-parameters.
  526    xhtml#sip-parameters-8 for possible privacy type values.
  527 
  528    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  529    FAILURE_ROUTE and BRANCH_ROUTE.
  530 
  531    Example 1.20. is_privacy usage
  532 ...
  533 if(is_privacy("id"))
  534 {
  535     # do interesting stuff here
  536 }
  537 ...
  538 
  539 1.3.21.  remove_body_part([mime[, revert]])
  540 
  541    Removes from the message body all the body parts with the given
  542    mime. The necessary corrections over the Content-Type and
  543    Content-Length headers are automatically done.
  544 
  545    If a MIME type is given, it will delete only the body parts
  546    with that mime. If no MIME given, all the parts (entire body)
  547    will be removed.
  548 
  549    Meaning of the parameters is as follows:
  550      * mime (string, optional) - MIME type to be checked against
  551        the body parts; If not given, all parts are to remvoed;
  552      * revert (string, optional) - useful only if a MIME was
  553        specified. If "revert" string is given here, the function
  554        will delete all body parts but the ones with the given
  555        MIME.
  556 
  557    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  558    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  559 
  560    Example 1.21. remove_body_part() usage
  561 ...
  562 # delete entire body message (all parts)
  563 remove_body_part();
  564 # delete all body parts with mime "application/isup"
  565 remove_body_part("application/isup");
  566 # delete all body parts but keep the the ones with  "application/sdp"
  567 remove_body_part("application/sdp","revert")
  568 ...
  569 
  570 1.3.22.  add_body_part(body, mime[, headers])
  571 
  572    This function can be used to add a new body part to the message
  573    body. If another part already exist, body of the message will
  574    be converted to a multi-part body automatically.
  575 
  576    Meaning of the parameters is as follows:
  577      * body (string) - the content of the body part to be added
  578      * mime (string) - the mime string for the body part to be
  579        added
  580      * headers (string, optional) - optional list of SIP headers
  581        (fully defined, including the header separator) to be
  582        pushed into this part next to the Content-Type header.
  583 
  584    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  585    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  586 
  587    Example 1.22. add_body_part usage
  588 ...
  589 add_body_part("Hello World!", "text/plain");
  590 ...
  591 
  592 1.3.23.  sipmsg_validate([flags[, result_pvar]])
  593 
  594    The function returns true if the SIP message is properly built
  595    according to SIP RFC3261. It verifies if the mandatory headers
  596    for each request/reply and can also check the format of the
  597    headers body.
  598 
  599    The flags parameter received is optional and can be composed
  600    with the following values:
  601      * 's' - checks the integrity of the SDP body, if it exists
  602      * 'h' - checks the format and integrity of each header body.
  603      * 'm' - don't check the Max-Forwards header.
  604      * 'r' - checks the R-URI and whether the domain contains
  605        valid characters.
  606      * 'f' - checks the URI of the 'From' field and whether the
  607        domain contains valid characters.
  608      * 't' - checks the URI of the 'To' field and whether the
  609        domain contains valid characters.
  610      * 'c' - checks the URI of the 'Contact' field.
  611 
  612    The result_pvar parameter sets resulting pvar with text error
  613    reason in case of negative result ( easy for logging or
  614    propagating the rejection reason back to the bogus UA )
  615 
  616    This function can return the following codes:
  617      * 1 - the message is RFC3261 compliant and has been
  618        successfully validated.
  619      * -1 - No SIP message
  620      * -2 - Header Parsing error
  621      * -3 - No Call-ID header
  622      * -4 - No Content-Length header for transports that require
  623        it ( eg. TCP )
  624      * -5 - Invalid Content-Length, other from the size of the
  625        actual body
  626      * -6 - SDP body parsing error.
  627      * -7 - No Cseq header.
  628      * -8 - No From header.
  629      * -9 - No To header.
  630      * -10 - No Via header.
  631      * -11 - Request URI parse error.
  632      * -12 - Bad hostname in R-URI.
  633      * -13 - No Max-Forwards header.
  634      * -14 - No Contact header.
  635      * -15 - Path user for non-Register request.
  636      * -16 - No allow header in 405 reply.
  637      * -17 - No Min-Expire header in 423 reply.
  638      * -18 - No Proxy-Authorize header in 407 reply.
  639      * -19 - No Unsupported header in 420 reply.
  640      * -20 - No WWW-Authorize header in 401 reply.
  641      * -21 - No Content-Type header
  642      * -22 - To header parse error
  643      * -23 - From header parse error
  644      * -24 - Bad hostname in To header
  645      * -25 - Bad hostname in From header
  646      * -26 - Contact header parse error
  647      * -255 - undefined errors.
  648 
  649    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  650    FAILURE_ROUTE and BRANCH_ROUTE.
  651 
  652    Example 1.23. sipmsg_validate usage
  653 ...
  654 if(!sipmsg_validate())
  655 {
  656         send_reply(400, "Bad Request");
  657         exit;
  658 }
  659 ...
  660 
  661 ...
  662 # checks also the SDP and headers body
  663 if(!sipmsg_validate("sh", $var(err_reason)))
  664 {
  665         send_reply(400, "Bad Request/Body");
  666         exit;
  667 }
  668 ...
  669 
  670 1.3.24.  codec_exists (name[, clock])
  671 
  672    This function can be used to verify if a codec exists inside an
  673    sdp payload. It will search for the codec inside all streams
  674    from all sdp sessions. If it is found anywhere it will return
  675    TRUE otherwise it will return FALSE.
  676 
  677    Parameters:
  678      * name (string) - Parameter is CASE INSENSITIVE.
  679      * clock (string, optional) - if not supplied any clockrate
  680        will match. Parameter is CASE INSENSITIVE.
  681 
  682    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  683    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  684 
  685    Example 1.24. codec_exists usage
  686 ...
  687 codec_exists("speex");
  688 or
  689 codec_exists("GSM", "8000");
  690 ...
  691 
  692 1.3.25.  codec_delete(name[, clock])
  693 
  694    This function can be used to delete a codec from inside an sdp
  695    payload. It will search for the codec inside all streams from
  696    all sdp sessions. If it is found anywhere it will be deleted
  697    from the mapping ("a=...") and from the list of indexes
  698    ("m=..."). Returns TRUE if any deletion occurred otherwise it
  699    will return FALSE.
  700      * name (string) - Parameter is CASE INSENSITIVE.
  701      * clock (string, optional) - if not supplied any clockrate
  702        will match and all will be deleted. Parameter is CASE
  703        INSENSITIVE.
  704 
  705    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  706    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  707 
  708    Example 1.25. codec_delete usage
  709 ...
  710 codec_delete("speex");
  711 or
  712 codec_delete("GSM", "8000");
  713 ...
  714 
  715 1.3.26.  codec_move_up(name[, clock])
  716 
  717    This function can be used to move a codec up in the list of
  718    indexes ("m=..."). It will search for the codec inside all
  719    streams from all sdp sessions. If it is found anywhere it will
  720    be moved to the top of the index list. Returns TRUE if any
  721    moves occurred otherwise it will return FALSE.
  722      * name (string) - parameter is CASE INSENSITIVE.
  723      * clock (string, optional) - if not supplied any clockrate
  724        will match and all codecs will be moved to the front while
  725        preserving their original ordering. Parameter is CASE
  726        INSENSITIVE.
  727 
  728    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  729    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  730 
  731    Example 1.26. codec_move_up usage
  732 ...
  733 codec_move_up("speex");
  734 or
  735 codec_move_up("GSM", "8000");
  736 ...
  737 
  738 1.3.27.  codec_move_down(name[, clock])
  739 
  740    This function can be used to move a codec down in the list of
  741    indexes ("m=..."). It will search for the codec inside all
  742    streams from all sdp sessions. If it is found anywhere it will
  743    be moved to the back of the index list. Returns TRUE if any
  744    moves occurred otherwise it will return FALSE. The second
  745    parameter is optional, if it is not supplied any clockrate will
  746    match and all codecs will be moved to the back while preserving
  747    their original ordering. Parameters are CASE INSENSITIVE.
  748      * name (string) - parameter is CASE INSENSITIVE.
  749      * clock (string, optional) - if not supplied any clockrate
  750        will match and all codecs will be moved to the back while
  751        preserving their original ordering. Parameter is CASE
  752        INSENSITIVE.
  753 
  754    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  755    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  756 
  757    Example 1.27. codec_move_down usage
  758 ...
  759 codec_move_down("speex");
  760 or
  761 codec_move_down("GSM", "8000");
  762 ...
  763 
  764    Example 1.28. codec_move_down usage
  765 ...
  766 /*
  767   This example will move speex with 8000 codec to the back of the list,
  768   then it will erase GSM with 8000 clock, and then it will bring all
  769   speex codecs to the front of the list. Speex/8000 will be behind any
  770   other speex.
  771 */
  772 codec_move_down("speex", "8000");
  773 codec_delete("GSM", "8000");
  774 codec_move_up("speex");
  775 ...
  776 
  777 1.3.28.  codec_exists_re ( regexp )
  778 
  779    This function has the same effect as codec_exists ( without the
  780    clock parameter ) the only difference is that it takes a POSIX
  781    regular expression as a parameter.
  782 
  783    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  784    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  785 
  786    Example 1.29. codec_exists_re usage
  787 ...
  788 codec_exists_re("sp[a-z]*");
  789 ...
  790 
  791 1.3.29.  codec_delete_re ( regexp )
  792 
  793    This function has the same effect as codec_delete ( without the
  794    clock parameter ) the only difference is that it takes a POSIX
  795    regular expression as a parameter.
  796 
  797    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  798    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  799 
  800    Example 1.30. codec_delete_re usage
  801 ...
  802 codec_delete_re("PCMA|PCMU");
  803 ...
  804 
  805 
  806 1.3.30.  codec_delete_except_re ( regexp )
  807 
  808    This function deletes all the codecs except those specified by
  809    the regular expression.
  810 
  811    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  812    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  813 
  814    Example 1.31. codec_delete_except_re usage
  815 ...
  816 codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA
  817 and PCMU
  818 ...
  819 
  820 
  821 1.3.31.  codec_move_up_re ( regexp )
  822 
  823    This function has the same effect as codec_move_up ( without
  824    the clock parameter ) the only difference is that it takes a
  825    POSIX regular expression as a parameter.
  826 
  827    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  828    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  829 
  830    Example 1.32. codec_move_up_re usage
  831 ...
  832 codec_move_up_re("sp[a-z]*");
  833 ...
  834 
  835 1.3.32.  codec_move_down_re ( regexp )
  836 
  837    This function has the same effect as codec_move_down ( without
  838    the clock parameter ) the only difference is that it takes a
  839    POSIX regular expression as a parameter.
  840 
  841    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  842    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  843 
  844    Example 1.33. codec_move_down_re usage
  845 ...
  846 codec_move_down_re("sp[a-z]*");
  847 ...
  848 
  849    Example 1.34. codec_move_down usage
  850 ...
  851 /*
  852   This example will move speex with 8000 codec to the back of the list,
  853   then it will erase GSM with 8000 clock, and then it will bring all
  854   speex codecs to the front of the list. Speex/8000 will be behind any
  855   other speex.
  856 */
  857 codec_move_down("speex","8000");
  858 codec_delete("GSM","8000");
  859 codec_move_up("speex");
  860 ...
  861 
  862 1.3.33.  change_reply_status(code, reason)
  863 
  864    Intercept a SIP reply (in any onreply_route) and change its
  865    status code and reason phrase prior to propogating it.
  866 
  867    Meaning of the parameters is as follows:
  868      * code (int) - Status code.
  869      * reason (string) - Reason phrase.
  870 
  871    This function can be used from ONREPLY_ROUTE.
  872 
  873    Example 1.35. change_reply_status usage
  874 ...
  875 onreply_route {
  876     if ($rs == "603") {
  877         change_reply_status(404, "Not Found");
  878         exit;
  879     }
  880 }
  881 ...
  882 
  883 1.3.34.  stream_exists(regexp)
  884 
  885    This function can be used to verify if a stream exists inside
  886    an sdp payload. It will search for the stream inside all sdp
  887    sessions. If it is found anywhere it will return TRUE otherwise
  888    it will return FALSE.
  889 
  890    Meaning of the parameters is as follows:
  891      * regexp - a POSIX regular expression to match the stream
  892        media name.
  893 
  894    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  895    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  896 
  897    Example 1.36. stream_exists usage
  898 ...
  899 # check for FAX
  900 stream_exists("image");
  901 ...
  902 
  903 1.3.35.  stream_delete(regexp)
  904 
  905    This function can be used to delete a whole stream from inside
  906    an sdp payload. It will search for the stream inside all sdp
  907    sessions. If it is found anywhere it will be deleted along with
  908    all attributes Returns TRUE if any deletion occurred otherwise
  909    it will return FALSE.
  910 
  911    Meaning of the parameters is as follows:
  912      * regexp - a POSIX regular expression to match the stream
  913        media name.
  914 
  915    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  916    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  917 
  918    Example 1.37. stream_delete usage
  919 ...
  920 # prevent usage of video
  921 stream_delete("video");
  922 ...
  923 
  924 1.3.36.  list_hdr_has_option(hdr_name, option)
  925 
  926    Checks and returns true if the given option/token is listed in
  927    the body of the given header. The header must have its body
  928    formated as a CSV list of tokens/option (like the Supported,
  929    Require, Content-Dispsition headers) body format
  930 
  931    Meaning of the parameters is as follows:
  932      * hdr_name (string) - the name of the header to be checked.
  933        Note that all instances of that header will be checked (if
  934        the header has multiple instances in the SIP message). Any
  935        kind of header name is supported - RFC3261 standard, RFC
  936        extensions or custom names.
  937      * opt (string) - the option/tolen to be searched for.
  938 
  939    The function returns true if the options was found listed in
  940    one of the header instances. If no header was found, if the
  941    option was not found or if there was a parsing or runtime
  942    error, false will be returned.
  943 
  944    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  945    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  946 
  947    Example 1.38. list_hdr_has_option usage
  948 ...
  949 # check if 100rel is advertised
  950 if (list_hdr_has_option("Supported", "100rel"))
  951         xlog("100rel option found\n");
  952 ...
  953 
  954 1.3.37.  list_hdr_add_option(hdr_name, option)
  955 
  956    Add a new option/token at the end of the list in the body of
  957    the given header. The header must have its body formated as a
  958    CSV list of tokens/option (like the Supported, Require,
  959    Content-Disposition headers) body format
  960 
  961    Multiple add / remove operations can be performed over the same
  962    header.
  963 
  964    Meaning of the parameters is as follows:
  965      * hdr_name (string) - the name of the header where the option
  966        has to be added. If multiple instances of that header are
  967        present in the SIP message, the add will be performed on
  968        the first instance. Any kind of header name is supported -
  969        RFC3261 standard, RFC extensions or custom names.
  970      * opt (string) - the option/token to be added to the CSV
  971        list. Note there is not verification for duplicated (if the
  972        newly added option is not already present in the header).
  973 
  974    The function returns true if the options was successfully added
  975    to the listed of the given header. If no header was found or if
  976    there was a parsing or runtime error, false will be returned.
  977 
  978    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
  979    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
  980 
  981    Example 1.39. list_hdr_add_option usage
  982 ...
  983 # add 100rel for advertising
  984 if (!list_hdr_has_option("Supported", "100rel"))
  985     list_hdr_add_option("Supported", "100rel");
  986 
  987 1.3.38.  list_hdr_remove_option(hdr_name, option)
  988 
  989    Removes an option/token from the list inside the body of the
  990    given header. The header must have its body formated as a CSV
  991    list of tokens/option (like the Supported, Require,
  992    Content-Dispsition headers) body format
  993 
  994    Multiple add / remove operations can be performed over the same
  995    header.
  996 
  997    Meaning of the parameters is as follows:
  998      * hdr_name (string) - the name of the header where the option
  999        has to be removed from. If the option is duplicated in the
 1000        same header, only the last one will be removed. If multiple
 1001        instances of that header are present in the SIP message,
 1002        the remove will be performed on all instance instance. Any
 1003        kind of header name is supported - RFC3261 standard, RFC
 1004        extensions or custom names.
 1005      * opt (string) - the option/token to be removed from the CSV
 1006        list. Note that if this the only option in the header, the
 1007        whole header will be removed.
 1008 
 1009    The function returns true if the options was successfully
 1010    removed from at least one heaer instance. If no header was
 1011    found or if the token was not found or if there was a parsing
 1012    or runtime error, false will be returned.
 1013 
 1014    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
 1015    FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
 1016 
 1017    Example 1.40. list_hdr_remove_option usage
 1018 ...
 1019 # add 100rel for advertising
 1020 if (list_hdr_has_option("Supported", "100rel"))
 1021     list_hdr_remove_option("Supported", "100rel");
 1022 list_hdr_add_option("Supported", "optionX");
 1023 
 1024 1.4. Known Limitations
 1025 
 1026    Search functions are applied to the current message so
 1027    modifications made to the sdp will be visible to the
 1028    codec_exists functions( e.g. after calling
 1029    codec_delete("speex") , codec_exists("speex") will return false
 1030    ).
 1031 
 1032 Chapter 2. Contributors
 1033 
 1034 2.1. By Commit Statistics
 1035 
 1036    Table 2.1. Top contributors by DevScore^(1), authored
 1037    commits^(2) and lines added/removed^(3)
 1038      Name DevScore Commits Lines ++ Lines --
 1039    1. Bogdan-Andrei Iancu (@bogdan-iancu) 54 28 1712 658
 1040    2. Liviu Chircu (@liviuchircu) 49 19 757 1313
 1041    3. Razvan Crainea (@razvancrainea) 40 16 2890 36
 1042    4. Vlad Paiu (@vladpaiu) 9 4 281 68
 1043    5. Mihai Tiganus (@tallicamike) 6 3 155 28
 1044    6. Vlad Patrascu (@rvlad-patrascu) 4 2 49 13
 1045    7. Ovidiu Sas (@ovidiusas) 4 2 22 1
 1046    8. Peter Lemenkov (@lemenkov) 4 2 2 2
 1047    9. Boris Ratner 4 1 129 46
 1048    10. Julián Moreno Patiño 3 1 8 8
 1049 
 1050    All remaining contributors: Fabian Gast (@fgast), Alexey
 1051    Vasilyev (@vasilevalex), Jarrod Baumann (@jarrodb), Ezequiel
 1052    Lovelle, Walter Doekes (@wdoekes), Nick Altmann (@nikbyte),
 1053    Ionut Ionita (@ionutrazvanionita), Dan Pascu (@danpascu).
 1054 
 1055    (1) DevScore = author_commits + author_lines_added /
 1056    (project_lines_added / project_commits) + author_lines_deleted
 1057    / (project_lines_deleted / project_commits)
 1058 
 1059    (2) including any documentation-related commits, excluding
 1060    merge commits. Regarding imported patches/code, we do our best
 1061    to count the work on behalf of the proper owner, as per the
 1062    "fix_authors" and "mod_renames" arrays in
 1063    opensips/doc/build-contrib.sh. If you identify any
 1064    patches/commits which do not get properly attributed to you,
 1065    please submit a pull request which extends "fix_authors" and/or
 1066    "mod_renames".
 1067 
 1068    (3) ignoring whitespace edits, renamed files and auto-generated
 1069    files
 1070 
 1071 2.2. By Commit Activity
 1072 
 1073    Table 2.2. Most recently active contributors^(1) to this module
 1074                       Name                   Commit Activity
 1075    1.  Razvan Crainea (@razvancrainea)     Feb 2012 - Sep 2019
 1076    2.  Liviu Chircu (@liviuchircu)         Nov 2012 - May 2019
 1077    3.  Dan Pascu (@danpascu)               May 2019 - May 2019
 1078    4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
 1079    5.  Bogdan-Andrei Iancu (@bogdan-iancu) Feb 2012 - Apr 2019
 1080    6.  Alexey Vasilyev (@vasilevalex)      Jan 2019 - Jan 2019
 1081    7.  Fabian Gast (@fgast)                Nov 2018 - Nov 2018
 1082    8.  Peter Lemenkov (@lemenkov)          Jan 2013 - Jun 2018
 1083    9.  Ovidiu Sas (@ovidiusas)             Feb 2018 - Feb 2018
 1084    10. Jarrod Baumann (@jarrodb)           Mar 2016 - Mar 2016
 1085 
 1086    All remaining contributors: Julián Moreno Patiño, Ionut Ionita
 1087    (@ionutrazvanionita), Ezequiel Lovelle, Vlad Paiu (@vladpaiu),
 1088    Mihai Tiganus (@tallicamike), Boris Ratner, Nick Altmann
 1089    (@nikbyte), Walter Doekes (@wdoekes).
 1090 
 1091    (1) including any documentation-related commits, excluding
 1092    merge commits
 1093 
 1094 Chapter 3. Documentation
 1095 
 1096 3.1. Contributors
 1097 
 1098    Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu
 1099    (@rvlad-patrascu), Fabian Gast (@fgast), Bogdan-Andrei Iancu
 1100    (@bogdan-iancu), Peter Lemenkov (@lemenkov), Ovidiu Sas
 1101    (@ovidiusas), Julián Moreno Patiño, Razvan Crainea
 1102    (@razvancrainea), Mihai Tiganus (@tallicamike), Vlad Paiu
 1103    (@vladpaiu), Boris Ratner, Nick Altmann (@nikbyte).
 1104 
 1105    Documentation Copyrights:
 1106 
 1107    Copyright © 2003 FhG FOKUS