sipmsgops Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Functions

              1.3.1. append_to_reply(txt)
              1.3.2. append_body_to_reply(txt)
              1.3.3. append_hf(txt[, hdr_anchor])
              1.3.4. insert_hf(txt)
              1.3.5. insert_hf(txt, hdr)
              1.3.6. append_urihf(prefix, suffix)
              1.3.7. is_present_hf(hf_name)
              1.3.8. append_time()
              1.3.9. is_method(name)
              1.3.10. remove_hf(hname)
              1.3.11. remove_hf_re(hname_expr)
              1.3.12. remove_hf_glob(hname_pattern)
              1.3.13. has_totag()
              1.3.14. ruri_has_param(param[,value])
              1.3.15. ruri_add_param(param)
              1.3.16. ruri_del_param(param)
              1.3.17. ruri_tel2sip()
              1.3.18. is_uri_user_e164(uri)
              1.3.19. has_body_part([mime])
              1.3.20. is_audio_on_hold()
              1.3.21. is_privacy(privacy_type)
              1.3.22. remove_body_part([mime[, revert]])
              1.3.23. add_body_part(body, mime[, headers])
              1.3.24. get_updated_body_part( [mime], variable)
              1.3.25. sipmsg_validate([flags[, result_pvar]])
              1.3.26. codec_exists (name[, clock])
              1.3.27. codec_delete(name[, clock])
              1.3.28. codec_move_up(name[, clock])
              1.3.29. codec_move_down(name[, clock])
              1.3.30. codec_exists_re ( regexp )
              1.3.31. codec_delete_re ( regexp )
              1.3.32. codec_delete_except_re ( regexp )
              1.3.33. codec_move_up_re ( regexp )
              1.3.34. codec_move_down_re ( regexp )
              1.3.35. change_reply_status(code, reason)
              1.3.36. stream_exists(regexp[,regexp2])
              1.3.37. stream_delete(regexp[,regexp2])
              1.3.38. list_hdr_has_option(hdr_name, option)
              1.3.39. list_hdr_add_option(hdr_name, option)
              1.3.40. list_hdr_remove_option(hdr_name, option)
              1.3.41. get_glob_headers_values(hdr_name_glob,
                      hdr_names_avp,hdr_vals_avp)

              1.3.42. sip_to_json(out_var)

        1.4. Known Limitations

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. append_to_reply usage
   1.2. append_to_reply usage
   1.3. append_hf usage
   1.4. insert_hf usage
   1.5. insert_hf usage
   1.6. append_urihf usage
   1.7. is_present_hf usage
   1.8. append_time usage
   1.9. is_method usage
   1.10. remove_hf usage
   1.11. remove_hf_re usage
   1.12. remove_hf_glob usage
   1.13. has_totag usage
   1.14. ruri_has_param usage
   1.15. ruri_add_param usage
   1.16. ruri_del_param usage
   1.17. ruri_tel2sip usage
   1.18. is_uri_user_e164 usage
   1.19. has_body_part usage
   1.20. is_audio_on_hold usage
   1.21. is_privacy usage
   1.22. remove_body_part() usage
   1.23. add_body_part usage
   1.24. get_updated_body_part usage
   1.25. sipmsg_validate usage
   1.26. codec_exists usage
   1.27. codec_delete usage
   1.28. codec_move_up usage
   1.29. codec_move_down usage
   1.30. codec_move_down usage
   1.31. codec_exists_re usage
   1.32. codec_delete_re usage
   1.33. codec_delete_except_re usage
   1.34. codec_move_up_re usage
   1.35. codec_move_down_re usage
   1.36. codec_move_down usage
   1.37. change_reply_status usage
   1.38. stream_exists usage
   1.39. stream_delete usage
   1.40. list_hdr_has_option usage
   1.41. list_hdr_add_option usage
   1.42. list_hdr_remove_option usage
   1.43. get_glob_headers_values usage
   1.44. sip_to_json usage

Chapter 1. Admin Guide

1.1. Overview

   The module implements SIP based operations over the messages
   processed by OpenSIPS. SIP is a text based protocol and the
   module provides a large set of very useful functions to
   manipulate the message at SIP level, e.g., inserting new
   headers or deleting them, check for method type, etc.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Functions

1.3.1.  append_to_reply(txt)

   Append 'txt' as header to all replies that will be generated by
   OpenSIPS for this request.

   Meaning of the parameters is as follows:
     * txt (string) - SIP header field, value and CRLF marker.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and ERROR_ROUTE.

   Example 1.1. append_to_reply usage
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...

1.3.2.  append_body_to_reply(txt)

   Append 'txt' as body to all replies that will be generated by
   OpenSIPS for this request.

   Multiple calls will override the already set body.

   NOTE: the function does not add any Content-Type hdr to match
   the body, so you should use "append_to_reply()" to do that.

   Meaning of the parameters is as follows:
     * txt (string) - body of the SIP reply

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and ERROR_ROUTE.

   Example 1.2. append_to_reply usage
...
append_body_to_reply( $var(sdp_body) );
...

1.3.3.  append_hf(txt[, hdr_anchor])

   Appends 'txt' as header after the last header field. If
   'hdr_anchor' is given, 'txt' will be appended after the first
   occurrence of 'hdr_anchor' instead.

   Meaning of the parameters is as follows:
     * txt (string) - Header field to be appended.
     * hdr_anchor (string, optional) - Header name after which the
       'txt' is appended.

   Note: Headers which are added in main route cannot be removed
   in further routes (e.g. failure routes). So, the idea is not to
   add there any headers that you might want to remove later. To
   add headers temporarily, use the branch route because the
   changes you do there are per-branch.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.3. append_hf usage
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n");
append_hf("From-username: $fU\r\n", "Call-ID");
...

1.3.4.  insert_hf(txt)

   Inserts 'txt' as header before the first header field.

   Meaning of the parameters is as follows:
     * txt (string) - Header field to be inserted.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.4. insert_hf usage
...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
...

1.3.5.  insert_hf(txt, hdr)

   Inserts 'txt' as header before first 'hdr' header field.

   Meaning of the parameters is as follows:
     * txt (string) - Header field to be inserted.
     * hdr (string, optional) - Header name before which the 'txt'
       is inserted.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.5. insert_hf usage
...
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...

1.3.6.  append_urihf(prefix, suffix)

   Append header field name with original Request-URI in middle.

   Meaning of the parameters is as follows:
     * prefix - string (usually at least header field name).
     * suffix - string (usually at least line terminator).

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
   BRANCH_ROUTE.

   Example 1.6. append_urihf usage
...
append_urihf("CC-Diversion: ", "\r\n");
...

1.3.7.  is_present_hf(hf_name)

   Return true if a header field is present in message.

Note

   The function is also able to distinguish the compact names. For
   exmaple “From” will match with “f”

   Meaning of the parameters is as follows:
     * hf_name (string) - Header field name (long or compact
       form).

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.7. is_present_hf usage
...
if (is_present_hf("From")) log(1, "From HF Present");
...

1.3.8.  append_time()

   Adds a time header to the reply of the request. You must use it
   before functions that are likely to send a reply, e.g., save()
   from 'registrar' module. Header format is: “Date: %a, %d %b %Y
   %H:%M:%S GMT”, with the legend:
     * %a abbreviated week of day name (locale)
     * %d day of month as decimal number
     * %b abbreviated month name (locale)
     * %Y year with century
     * %H hour
     * %M minutes
     * %S seconds

   Return true if a header was successfully appended.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.8. append_time usage
...
append_time();
...

1.3.9.  is_method(name)

   Check if the method of the message matches the name. If name is
   a known method (invite, cancel, ack, bye, options, info,
   update, register, message, subscribe, notify, refer, prack),
   the function performs method ID testing (integer comparison)
   instead of ignore case string comparison.

   The 'name' can be a list of methods in the form of
   'method1|method2|...'. In this case, the function returns true
   if the SIP message's method is one from the list. IMPORTANT
   NOTE: in the list must be only methods defined in OpenSIPS with
   ID (invite, cancel, ack, bye, options, info, update, register,
   message, subscribe, notify, refer, prack, publish; for more
   see: https://www.iana.org/assignments/sip-parameters).

   If used for replies, the function tests the value of method
   field from CSeq header.

   Meaning of the parameters is as follows:
     * name (string) - SIP method name

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.9. is_method usage
...
if(is_method("INVITE"))
{
    # process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
    # process OPTIONs and UPDATEs here
}
...

1.3.10.  remove_hf(hname)

   Remove from message all headers with name “hname”

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * hname (string) - header name to be removed.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.10. remove_hf usage
...
if(remove_hf("User-Agent"))
{
    # User Agent header removed
}
...

1.3.11.  remove_hf_re(hname_expr)

   Remove from message all headers matching the “hname_expr” POSIX
   regular expression.

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * hname_expr (string) - regular expression.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.11. remove_hf_re usage
...
remove_hf_re("^X-g.+[0-9]");
...

1.3.12.  remove_hf_glob(hname_pattern)

   Remove from message all headers matching the “hname_pattern”
   glob pattern.

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * hname_pattern (string) - glob pattern

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.12. remove_hf_glob usage
...
# removes X-Billing-Account, X-Billing-Price, X-Billing-rateplan, etc
remove_hf_glob("X-Billing*");
...

1.3.13.  has_totag()

   Check if To header field uri contains tag parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.13. has_totag usage
...
if (has_totag()) {
        ...
};
...

1.3.14.  ruri_has_param(param[,value])

   Find if Request URI has a given parameter. If no value is
   given, the function will look for the paramter with no value,
   oherwise it will search for the parameter with the matching
   value.

   Meaning of the parameters is as follows:
     * param (string) - parameter name to look for.
     * value (string, optional) - parameter value to match.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.14. ruri_has_param usage
...
if (ruri_has_param("user","phone")) {
        ...
};
...

1.3.15.  ruri_add_param(param)

   Add to RURI an URI parameter formated as "name=value".

   Meaning of the parameters is as follows:
     * param (string) - parameter to be appended in “name=value”
       format.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.15. ruri_add_param usage
...
ruri_add_param("nat=yes");
...

1.3.16.  ruri_del_param(param)

   Delete a parameter, its value and any leading ";" from the
   Request-URI of the current SIP message.

   Meaning of the parameters is as follows:
     * param (string) - the parameter to be removed

   Returns 1 on a successful deletion or -1 otherwise.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.16. ruri_del_param usage
...
ruri_del_param("user");
...

1.3.17.  ruri_tel2sip()

   Converts RURI, if it is tel URI, to SIP URI. Returns true, only
   if conversion succeeded or if no conversion was needed (like
   RURI was not tel URI.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.17. ruri_tel2sip usage
...
ruri_tel2sip();
...

1.3.18.  is_uri_user_e164(uri)

   Checks if the username part of the given URI is an E164 number.

   Meaning of the parameters is as follows:
     * uri (string) - a SIP URI

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
   LOCAL_ROUTE.

   Example 1.18. is_uri_user_e164 usage
...
if (is_uri_user_e164($fu)) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164($avp(uri)) {
   # Check user part of URI stored in avp uri
   ...
};
...

1.3.19.  has_body_part([mime])

   The function returns true if the SIP message has any body part
   with the given MIME. If there is no MIME given, it will return
   true if at least one body part is found (with any MIME).

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.19. has_body_part usage
...
if(has_body_part("application/sdp"))
{
    # do interesting stuff here
}
...

1.3.20.  is_audio_on_hold()

   The function returns true if the SIP message has an SDP body
   attached and at least one audio stream in on hold. The return
   code of the function indicates the detected hold type:
     * 1 - RFC2543 hold type: null connection IP detected
     * 2 - RFC3264 hold type: inactive or sendonly attributes
       detected

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.20. is_audio_on_hold usage
...
if(is_audio_on_hold())
{
    switch ($rc) {
    case 1:
        # RFC2543 hold type
        # do interesting stuff here
        break;
    case 2:
        # RFC3264 hold type
        # do interesting stuff here
        break;
}
...

1.3.21.  is_privacy(privacy_type)

   The function returns true if the SIP message has a Privacy
   header field that includes the given privacy_type among its
   privacy values. See
   https://www.iana.org/assignments/sip-parameters/sip-parameters.
   xhtml#sip-parameters-8 for possible privacy type values.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.21. is_privacy usage
...
if(is_privacy("id"))
{
    # do interesting stuff here
}
...

1.3.22.  remove_body_part([mime[, revert]])

   Removes from the message body all the body parts with the given
   mime. The necessary corrections over the Content-Type and
   Content-Length headers are automatically done.

   If a MIME type is given, it will delete only the body parts
   with that mime. If no MIME given, all the parts (entire body)
   will be removed.

   Meaning of the parameters is as follows:
     * mime (string, optional) - MIME type to be checked against
       the body parts; If not given, all parts are to remvoed;
     * revert (string, optional) - useful only if a MIME was
       specified. If "revert" string is given here, the function
       will delete all body parts but the ones with the given
       MIME.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.22. remove_body_part() usage
...
# delete entire body message (all parts)
remove_body_part();
# delete all body parts with mime "application/isup"
remove_body_part("application/isup");
# delete all body parts but keep the the ones with  "application/sdp"
remove_body_part("application/sdp","revert")
...

1.3.23.  add_body_part(body, mime[, headers])

   This function can be used to add a new body part to the message
   body. If another part already exist, body of the message will
   be converted to a multi-part body automatically.

   Meaning of the parameters is as follows:
     * body (string) - the content of the body part to be added
     * mime (string) - the mime string for the body part to be
       added
     * headers (string, optional) - optional list of SIP headers
       (fully defined, including the header separator) to be
       pushed into this part next to the Content-Type header.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.23. add_body_part usage
...
add_body_part("Hello World!", "text/plain");
...

1.3.24.  get_updated_body_part( [mime], variable)

   This function returns into a variable the regenerated body
   part, meaning the body part updated with all the changes done
   so far by OpenSIPS. This is helpful if you want to do a
   sequance of operations over the body parts and some operations
   require to have all the previous changes applied (like first
   doing some codec related changes and later to rtpengine
   insertion).

   NOTE: the actual SIP message will not be affected by this
   operation!

   Meaning of the parameters is as follows:
     * mime (string) - the mime string for the body to be
       regenerated and returned. If missing, the whole body (with
       all its parts) will be regenerated.
     * variable - a variable to be used to return the regenerated
       body part (as text).

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.24. get_updated_body_part usage
...
        codec_delete_re("PCMA|PCMU");

        get_updated_body_part( "application/sdp", $var(new_sdp));

        xlog("------updated SDP is ----\n$var(new_sdp)\n-----------\n");
        exit;
...

1.3.25.  sipmsg_validate([flags[, result_pvar]])

   The function returns true if the SIP message is properly built
   according to SIP RFC3261. It verifies if the mandatory headers
   for each request/reply and can also check the format of the
   headers body.

   The flags parameter received is optional and can be composed
   with the following values:
     * 's' - checks the integrity of the SDP body, if it exists
     * 'h' - checks the format and integrity of each header body.
     * 'm' - don't check the Max-Forwards header.
     * 'r' - checks the R-URI and whether the domain contains
       valid characters.
     * 'f' - checks the URI of the 'From' field and whether the
       domain contains valid characters.
     * 't' - checks the URI of the 'To' field and whether the
       domain contains valid characters.
     * 'c' - checks the URI of the 'Contact' field.

   The result_pvar parameter sets resulting pvar with text error
   reason in case of negative result ( easy for logging or
   propagating the rejection reason back to the bogus UA )

   This function can return the following codes:
     * 1 - the message is RFC3261 compliant and has been
       successfully validated.
     * -1 - No SIP message
     * -2 - Header Parsing error
     * -3 - No Call-ID header
     * -4 - No Content-Length header for transports that require
       it ( eg. TCP )
     * -5 - Invalid Content-Length, other from the size of the
       actual body
     * -6 - SDP body parsing error.
     * -7 - No Cseq header.
     * -8 - No From header.
     * -9 - No To header.
     * -10 - No Via header.
     * -11 - Request URI parse error.
     * -12 - Bad hostname in R-URI.
     * -13 - No Max-Forwards header.
     * -14 - No Contact header.
     * -15 - Path user for non-Register request.
     * -16 - No allow header in 405 reply.
     * -17 - No Min-Expire header in 423 reply.
     * -18 - No Proxy-Authorize header in 407 reply.
     * -19 - No Unsupported header in 420 reply.
     * -20 - No WWW-Authorize header in 401 reply.
     * -21 - No Content-Type header
     * -22 - To header parse error
     * -23 - Bad hostname in To header
     * -24 - From header parse error
     * -25 - Bad hostname in From header
     * -26 - Contact header parse error
     * -27 - Bad URI username
     * -28 - Bad From URI username
     * -29 - Bad To URI username
     * -255 - undefined errors.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE and BRANCH_ROUTE.

   Example 1.25. sipmsg_validate usage
...
if(!sipmsg_validate())
{
        send_reply(400, "Bad Request");
        exit;
}
...

...
# checks also the SDP and headers body
if(!sipmsg_validate("sh", $var(err_reason)))
{
        send_reply(400, "Bad Request/Body");
        exit;
}
...

1.3.26.  codec_exists (name[, clock])

   This function can be used to verify if a codec exists inside an
   sdp payload. It will search for the codec inside all streams
   from all sdp sessions. If it is found anywhere it will return
   TRUE otherwise it will return FALSE.

   Parameters:
     * name (string) - Parameter is CASE INSENSITIVE.
     * clock (string, optional) - if not supplied any clockrate
       will match. Parameter is CASE INSENSITIVE.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.26. codec_exists usage
...
codec_exists("speex");
or
codec_exists("GSM", "8000");
...

1.3.27.  codec_delete(name[, clock])

   This function can be used to delete a codec from inside an sdp
   payload. It will search for the codec inside all streams from
   all sdp sessions. If it is found anywhere it will be deleted
   from the mapping ("a=...") and from the list of indexes
   ("m=..."). Returns TRUE if any deletion occurred otherwise it
   will return FALSE.
     * name (string) - Parameter is CASE INSENSITIVE.
     * clock (string, optional) - if not supplied any clockrate
       will match and all will be deleted. Parameter is CASE
       INSENSITIVE.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.27. codec_delete usage
...
codec_delete("speex");
or
codec_delete("GSM", "8000");
...

1.3.28.  codec_move_up(name[, clock])

   This function can be used to move a codec up in the list of
   indexes ("m=..."). It will search for the codec inside all
   streams from all sdp sessions. If it is found anywhere it will
   be moved to the top of the index list. Returns TRUE if any
   moves occurred otherwise it will return FALSE.
     * name (string) - parameter is CASE INSENSITIVE.
     * clock (string, optional) - if not supplied any clockrate
       will match and all codecs will be moved to the front while
       preserving their original ordering. Parameter is CASE
       INSENSITIVE.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.28. codec_move_up usage
...
codec_move_up("speex");
or
codec_move_up("GSM", "8000");
...

1.3.29.  codec_move_down(name[, clock])

   This function can be used to move a codec down in the list of
   indexes ("m=..."). It will search for the codec inside all
   streams from all sdp sessions. If it is found anywhere it will
   be moved to the back of the index list. Returns TRUE if any
   moves occurred otherwise it will return FALSE. The second
   parameter is optional, if it is not supplied any clockrate will
   match and all codecs will be moved to the back while preserving
   their original ordering. Parameters are CASE INSENSITIVE.
     * name (string) - parameter is CASE INSENSITIVE.
     * clock (string, optional) - if not supplied any clockrate
       will match and all codecs will be moved to the back while
       preserving their original ordering. Parameter is CASE
       INSENSITIVE.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.29. codec_move_down usage
...
codec_move_down("speex");
or
codec_move_down("GSM", "8000");
...

   Example 1.30. codec_move_down usage
...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex", "8000");
codec_delete("GSM", "8000");
codec_move_up("speex");
...

1.3.30.  codec_exists_re ( regexp )

   This function has the same effect as codec_exists ( without the
   clock parameter ) the only difference is that it takes a POSIX
   regular expression as a parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.31. codec_exists_re usage
...
codec_exists_re("sp[a-z]*");
...

1.3.31.  codec_delete_re ( regexp )

   This function has the same effect as codec_delete ( without the
   clock parameter ) the only difference is that it takes a POSIX
   regular expression as a parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.32. codec_delete_re usage
...
codec_delete_re("PCMA|PCMU");
...


1.3.32.  codec_delete_except_re ( regexp )

   This function deletes all the codecs except those specified by
   the regular expression.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.33. codec_delete_except_re usage
...
codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA
and PCMU
...


1.3.33.  codec_move_up_re ( regexp )

   This function has the same effect as codec_move_up ( without
   the clock parameter ) the only difference is that it takes a
   POSIX regular expression as a parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.34. codec_move_up_re usage
...
codec_move_up_re("sp[a-z]*");
...

1.3.34.  codec_move_down_re ( regexp )

   This function has the same effect as codec_move_down ( without
   the clock parameter ) the only difference is that it takes a
   POSIX regular expression as a parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.35. codec_move_down_re usage
...
codec_move_down_re("sp[a-z]*");
...

   Example 1.36. codec_move_down usage
...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...

1.3.35.  change_reply_status(code, reason)

   Intercept a SIP reply (in any onreply_route) and change its
   status code and reason phrase prior to propogating it.

   Meaning of the parameters is as follows:
     * code (int) - Status code.
     * reason (string) - Reason phrase.

   This function can be used from ONREPLY_ROUTE.

   Example 1.37. change_reply_status usage
...
onreply_route {
    if ($rs == "603") {
        change_reply_status(404, "Not Found");
        exit;
    }
}
...

1.3.36.  stream_exists(regexp[,regexp2])

   This function can be used to verify if a stream exists inside
   an sdp payload. It will search for the stream inside all sdp
   sessions. If it is found anywhere it will return TRUE otherwise
   it will return FALSE.

   Meaning of the parameters is as follows:
     * regexp - a POSIX regular expression to match the stream
       media name.
     * regexp2 - an optional POSIX regular expression to match the
       stream transport name.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.38. stream_exists usage
...
# check for FAX
stream_exists("image");
...
stream_exists("audio","SAVP");
...

1.3.37.  stream_delete(regexp[,regexp2])

   This function can be used to delete a whole stream from inside
   an sdp payload. It will search for the stream inside all sdp
   sessions. If it is found anywhere it will be deleted along with
   all attributes Returns TRUE if any deletion occurred otherwise
   it will return FALSE.

   Meaning of the parameters is as follows:
     * regexp - a POSIX regular expression to match the stream
       media name.
     * regexp2 - an optional POSIX regular expression to match the
       stream transport name.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.39. stream_delete usage
...
# prevent usage of video
stream_delete("video");
...

1.3.38.  list_hdr_has_option(hdr_name, option)

   Checks and returns true if the given option/token is listed in
   the body of the given header. The header must have its body
   formated as a CSV list of tokens/option (like the Supported,
   Require, Content-Dispsition headers) body format

   Meaning of the parameters is as follows:
     * hdr_name (string) - the name of the header to be checked.
       Note that all instances of that header will be checked (if
       the header has multiple instances in the SIP message). Any
       kind of header name is supported - RFC3261 standard, RFC
       extensions or custom names.
     * opt (string) - the option/tolen to be searched for.

   The function returns true if the options was found listed in
   one of the header instances. If no header was found, if the
   option was not found or if there was a parsing or runtime
   error, false will be returned.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.40. list_hdr_has_option usage
...
# check if 100rel is advertised
if (list_hdr_has_option("Supported", "100rel"))
        xlog("100rel option found\n");
...

1.3.39.  list_hdr_add_option(hdr_name, option)

   Add a new option/token at the end of the list in the body of
   the given header. The header must have its body formated as a
   CSV list of tokens/option (like the Supported, Require,
   Content-Disposition headers) body format

   Multiple add / remove operations can be performed over the same
   header.

   Meaning of the parameters is as follows:
     * hdr_name (string) - the name of the header where the option
       has to be added. If multiple instances of that header are
       present in the SIP message, the add will be performed on
       the first instance. Any kind of header name is supported -
       RFC3261 standard, RFC extensions or custom names.
     * opt (string) - the option/token to be added to the CSV
       list. Note there is not verification for duplicated (if the
       newly added option is not already present in the header).

   The function returns true if the options was successfully added
   to the listed of the given header. If no header was found or if
   there was a parsing or runtime error, false will be returned.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.41. list_hdr_add_option usage
...
# add 100rel for advertising
if (!list_hdr_has_option("Supported", "100rel"))
    list_hdr_add_option("Supported", "100rel");

1.3.40.  list_hdr_remove_option(hdr_name, option)

   Removes an option/token from the list inside the body of the
   given header. The header must have its body formated as a CSV
   list of tokens/option (like the Supported, Require,
   Content-Dispsition headers) body format

   Multiple add / remove operations can be performed over the same
   header.

   Meaning of the parameters is as follows:
     * hdr_name (string) - the name of the header where the option
       has to be removed from. If the option is duplicated in the
       same header, only the last one will be removed. If multiple
       instances of that header are present in the SIP message,
       the remove will be performed on all instance instance. Any
       kind of header name is supported - RFC3261 standard, RFC
       extensions or custom names.
     * opt (string) - the option/token to be removed from the CSV
       list. Note that if this the only option in the header, the
       whole header will be removed.

   The function returns true if the options was successfully
   removed from at least one heaer instance. If no header was
   found or if the token was not found or if there was a parsing
   or runtime error, false will be returned.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.42. list_hdr_remove_option usage
...
# add 100rel for advertising
if (list_hdr_has_option("Supported", "100rel"))
    list_hdr_remove_option("Supported", "100rel");
list_hdr_add_option("Supported", "optionX");

1.3.41.  get_glob_headers_values(hdr_name_glob,
hdr_names_avp,hdr_vals_avp)

   Populates the hdr_names_avp and hdr_vals_avp AVPs with all the
   header names and values that match the hdr_name_glob pattern.

   Meaning of the parameters is as follows:
     * hdr_name_glob (string) - the glob pattern for matching the
       header names
     * hdr_names_avp (var) - the AVP which will get populated with
       all the header names that match the glob pattern
     * hdr_vals_avp (var) - the AVP which will get populated with
       all the header values corresponding to the header names
       that match the glob pattern

   The function returns true if at least 1 header was found that
   matches the glob pattern and false if no match is found.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.43. get_glob_headers_values usage
...
       if (get_glob_headers_values("X-*",$avp(names),$avp(values))) {
           xlog("All X- names are $(avp(names)[*]) and X- vals are $(avp
(values)[*])\n");
       }
...

1.3.42.  sip_to_json(out_var)

   Returns a JSON formatted representation of the current SIP
   message, containing first_line , headers and body json members
   Useful in cases when you want to pass a generic SIP message to
   a SIP agnostic entity, but still want to provide some layer of
   SIP parsing before sending the full message further.

   Meaning of the parameters is as follows:
     * out_var (string) - the output JSON formatted SIP message
       variable

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

   Example 1.44. sip_to_json usage
...
       if (sip_to_json($var(out_sip_json))) {
           xlog("The JSON format for the current SIP message is $var(out
_sip_json) \n");
       }
...

1.4. Known Limitations

   Search functions are applied to the current message so
   modifications made to the sdp will be visible to the
   codec_exists functions( e.g. after calling
   codec_delete("speex") , codec_exists("speex") will return false
   ).

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 74 43 2195 723
   2. Liviu Chircu (@liviuchircu) 59 27 809 1510
   3. Razvan Crainea (@razvancrainea) 47 20 2949 87
   4. Vlad Paiu (@vladpaiu) 16 8 663 123
   5. Mihai Tiganus (@tallicamike) 6 3 155 28
   6. Maksym Sobolyev (@sobomax) 5 3 2 3
   7. Vlad Patrascu (@rvlad-patrascu) 4 2 49 13
   8. Ovidiu Sas (@ovidiusas) 4 2 22 1
   9. Peter Lemenkov (@lemenkov) 4 2 2 2
   10. Boris Ratner 4 1 129 46

   All remaining contributors: Bence Szigeti, Julián Moreno
   Patiño, Fabian Gast (@fgast), Alexey Vasilyev (@vasilevalex),
   Jarrod Baumann (@jarrodb), Ezequiel Lovelle (@lovelle), Walter
   Doekes (@wdoekes), Nick Altmann (@nikbyte), Ionut Ionita
   (@ionutrazvanionita), Dan Pascu (@danpascu).

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Feb 2012 - Mar 2025
   2.  Vlad Paiu (@vladpaiu)               Feb 2012 - May 2024
   3.  Bence Szigeti                       May 2023 - May 2023
   4.  Maksym Sobolyev (@sobomax)          Mar 2021 - Feb 2023
   5.  Liviu Chircu (@liviuchircu)         Nov 2012 - Oct 2022
   6.  Razvan Crainea (@razvancrainea)     Feb 2012 - Aug 2021
   7.  Dan Pascu (@danpascu)               May 2019 - May 2019
   8.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   9.  Alexey Vasilyev (@vasilevalex)      Jan 2019 - Jan 2019
   10. Fabian Gast (@fgast)                Nov 2018 - Nov 2018

   All remaining contributors: Peter Lemenkov (@lemenkov), Ovidiu
   Sas (@ovidiusas), Jarrod Baumann (@jarrodb), Julián Moreno
   Patiño, Ionut Ionita (@ionutrazvanionita), Ezequiel Lovelle
   (@lovelle), Mihai Tiganus (@tallicamike), Boris Ratner, Nick
   Altmann (@nikbyte), Walter Doekes (@wdoekes).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad Paiu
   (@vladpaiu), Bence Szigeti, Liviu Chircu (@liviuchircu), Vlad
   Patrascu (@rvlad-patrascu), Fabian Gast (@fgast), Peter
   Lemenkov (@lemenkov), Ovidiu Sas (@ovidiusas), Julián Moreno
   Patiño, Razvan Crainea (@razvancrainea), Mihai Tiganus
   (@tallicamike), Boris Ratner, Nick Altmann (@nikbyte).

   Documentation Copyrights:

   Copyright © 2003 FhG FOKUS
