sipmsgops Module

Andrei Pelinescu-Onciul

   FhG FOKUS
   <pelinescu-onciul@fokus.fraunhofer.de>

Edited by

Andrei Pelinescu-Onciul

   <pelinescu-onciul@fokus.fraunhofer.de>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Ovidiu Sas

   <osas@voipembedded.com>

Edited by

Razvan Crainea

   <razvancrainea@opensips.org>

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision: 7480 $ $Date$
     __________________________________________________________

   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. filter_body(content_type)
              1.3.2. append_to_reply(txt)
              1.3.3. append_hf(txt)
              1.3.4. append_hf(txt, hdr)
              1.3.5. insert_hf(txt)
              1.3.6. insert_hf(txt, hdr)
              1.3.7. append_urihf(prefix, suffix)
              1.3.8. is_present_hf(hf_name)
              1.3.9. append_time()
              1.3.10. is_method(name)
              1.3.11. remove_hf(hname [,flags])
              1.3.12. has_body(), has_body(mime)
              1.3.13. is_audio_on_hold()
              1.3.14. is_privacy(privacy_type)
              1.3.15. strip_body(), strip_body(mime)
              1.3.16. add_body(body_text, new_content_type)
              1.3.17. sipmsg_validate([flags[,result_pvar]])
              1.3.18. codec_exists (name [,clock] )
              1.3.19. codec_delete (name [,clock] )
              1.3.20. codec_move_up (name [,clock] )
              1.3.21. codec_move_down (name [,clock] )
              1.3.22. codec_exists_re ( regexp )
              1.3.23. codec_delete_re ( regexp )
              1.3.24. codec_delete_except_re ( regexp )
              1.3.25. codec_move_up_re ( regexp )
              1.3.26. codec_move_down_re ( regexp )
              1.3.27. change_reply_status(code, reason)
              1.3.28. stream_exists(regexp)
              1.3.29. stream_delete(regexp)

        1.4. Known Limitations

   List of Examples

   1.1. filter_body usage
   1.2. append_to_reply usage
   1.3. append_hf usage
   1.4. append_hf usage
   1.5. insert_hf usage
   1.6. insert_hf usage
   1.7. append_urihf usage
   1.8. is_present_hf usage
   1.9. append_time usage
   1.10. is_method usage
   1.11. remove_hf usage
   1.12. has_body usage
   1.13. is_audio_on_hold usage
   1.14. is_privacy usage
   1.15. strip_body usage
   1.16. add_body usage
   1.17. sipmsg_validate usage
   1.18. codec_exists usage
   1.19. codec_delete usage
   1.20. codec_move_up usage
   1.21. codec_move_down usage
   1.22. codec_move_down usage
   1.23. codec_exists_re usage
   1.24. codec_delete_re usage
   1.25. codec_delete_except_re usage
   1.26. codec_move_up_re usage
   1.27. codec_move_down_re usage
   1.28. codec_move_down usage
   1.29. change_reply_status usage
   1.30. stream_exists usage
   1.31. stream_delete 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.  filter_body(content_type)

   Filters multipart body by leaving out all other body parts
   except the first body part of given type.

   Meaning of the parameters is as follows:
     * content_type - Content type to be left in the body.

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

   Example 1.1. filter_body usage
...
if (has_body("multipart/mixed")) {
    if (filter_body("application/sdp") {
        remove_hf("Content-Type");
        append_hf("Content-Type: application/sdp\r\n");
    } else {
        xlog("Body part application/sdp not found\n");
    }
}
...

1.3.2.  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 which may contains pseudo-variables.

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

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

1.3.3.  append_hf(txt)

   Appends 'txt' as header after the last header field.

   Meaning of the parameters is as follows:
     * txt - Header field to be appended. The value can contain
       pseudo-variables which will be replaced at run time.

   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 temporarely 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.

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

1.3.4.  append_hf(txt, hdr)

   Appends 'txt' as header after first 'hdr' header field.

   Meaning of the parameters is as follows:
     * txt - Header field to be appended. The value can contain
       pseudo-variables which will be replaced at run time.
     * hdr - Header name after which the 'txt' is appended.

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

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

1.3.5.  insert_hf(txt)

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

   Meaning of the parameters is as follows:
     * txt - Header field to be inserted. The value can contain
       pseudo-variables which will be replaced at run time.

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

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

1.3.6.  insert_hf(txt, hdr)

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

   Meaning of the parameters is as follows:
     * txt - Header field to be inserted. The value can contain
       pseudo-variables which will be replaced at run time.
     * hdr - Header name before which the 'txt' is inserted.

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

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

1.3.7.  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,
   BRANCH_ROUTE.

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

1.3.8.  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 - Header field name.(long or compact form). The
       hf_name parameter can have the following types:
          + string - Static header field name
          + pvar - Header field name is given as a pseudo-variable
            (as string value)

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

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

1.3.9.  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 succesfully appended.

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

   Example 1.9. append_time usage
...
append_time();
...

1.3.10.  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: http://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 - SIP method name

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

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

1.3.11.  remove_hf(hname [,flags])

   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 - header name to be removed. The hname parameter can
       have the following types:
          + string - Header name to be removed
          + pvar - Header name to be removed is the value of an
            existing pseudo-variable (as string value)
          + pattern - pattern to match the names of the headers to
            be removed; can be a simple wildcard or a regexp (see
            the second param too)
     * flags - how to interpret the pattern from the first
       parameted.
          + r - pattern is a regexp
          + g - pattern is glob (shell wildcard pattern)

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

   Example 1.11. remove_hf usage
...
if(remove_hf("User-Agent"))
{
    # User Agent header removed
}
...
# removes X-Billing-Account, X-Billing-Price, X-Billing-rateplan, etc
remove_hf("X-Billing*", "g");
...
#removes headers by regex
remove_hf("^X-g.+[0-9]", "r");
...

1.3.12.  has_body(), has_body(mime)

   The function returns true if the SIP message has a body
   attached. The checked includes also the “Content-Lenght” header
   presence and value.

   If a paramter is given, the mime described will be also checked
   against the “Content-Type” header.

   If the SIP message has a multipart body and mime is not a
   multipart type , it will search through all the parts for the
   given type.

   It will not handle multi-layer multiparts

   Meaning of the parameters is as follows:
     * mime - mime to be checked against the “Content-Type”
       header. If not present or 0, this check will be disabled.

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

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

1.3.13.  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.

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

   Example 1.13. is_audio_on_hold usage
...
if(is_audio_on_hold())
{
    # do interesting stuff here
}
...

1.3.14.  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
   http://www.iana.org/assignments/sip-priv-values for possible
   privacy type values.

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

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

1.3.15.  strip_body(), strip_body(mime)

   If the message has a body, this function deletes it, correcting
   Content-Length. This function also deletes the Content-Type
   header.

   If a MIME type is specified it will delete the body if it has
   the same type or, if the message has a multipart body it will
   go through the parts and delete all those with the specified
   type.

   It will not handle multi-layer multiparts

   Meaning of the parameters is as follows:
     * mime - mime to be checked against the “Content-Type”
       header. If not present or 0, this check will be disabled.

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

   Example 1.15. strip_body usage
...
strip_body();   #delete any body
strip_body("multipart/related") # delete a multipart/related body
strip_body("application/sdp") # delete all sdp bodies, even ones enclose
d in multipart
...

1.3.16.  add_body(body_text, new_content_type)

   This function can be used to add a body to a message. If a body
   already exists, it will be replaced with the new one. The
   second parameter is the content type of the new body. It is
   optional: in case the function is used to replace an existing
   body with a body of the same type, there is no need to set this
   parameter. If the message has no body or if the types are
   different, it is compulsory to set this parameter.

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

   Example 1.16. add_body usage
...
add_body("Hello World!", "text/plain");
...

1.3.17.  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.

   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-Forward 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
     * -255 - undefined errors.

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

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

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

1.3.18.  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. The second parameter is
   optional, if it is not supplied any clockrate will match.
   Parameters are CASE INSENSITIVE.

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

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

1.3.19.  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 occured otherwise it
   will return FALSE. The second parameter is optional, if it is
   not supplied any clockrate will match and all will be deleted.
   Parameters are CASE INSENSITIVE.

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

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

1.3.20.  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 occured 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 front while
   preserving their original ordering. Parameters are CASE
   INSENSITIVE.

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

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

1.3.21.  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 occured 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.

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

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

   Example 1.22. 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.22.  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.23. codec_exists_re usage
...
codec_exists_re("sp[a-z]*");
...

1.3.23.  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.24. codec_delete_re usage
...
codec_delete_re("PCMA|PCMU");
...


1.3.24.  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.25. codec_delete_except_re usage
...
codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA
and PCMU
...


1.3.25.  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.26. codec_move_up_re usage
...
codec_move_up_re("sp[a-z]*");
...

1.3.26.  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.27. codec_move_down_re usage
...
codec_move_down_re("sp[a-z]*");
...

   Example 1.28. 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.27.  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 - Status code.
     * reason - Reason phrase.

   This function can be used from ONREPLY_ROUTE.

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

1.3.28.  stream_exists(regexp)

   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.

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

   Example 1.30. stream_exists usage
...
# check for FAX
stream_exists("image");
...

1.3.29.  stream_delete(regexp)

   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 occured otherwise
   it will return FALSE.

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

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

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

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
   ).
