
textops Module

Andrei Pelinescu-Onciul

   FhG FOKUS

Edited by

Andrei Pelinescu-Onciul

   Copyright © 2003 FhG FOKUS
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview

              1.1.1. Known Limitations

        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Functions

              1.3.1. search(re)
              1.3.2. search_append(re, txt)
              1.3.3. replace(re, txt)
              1.3.4. replace_all(re, txt)
              1.3.5. subst('/re/repl/flags')
              1.3.6. subst_uri('/re/repl/flags')
              1.3.7. subst_user('/re/repl/flags')
              1.3.8. append_to_reply(txt)
              1.3.9. append_hf(hf)
              1.3.10. append_urihf(prefix, suffix)
              1.3.11. is_present_hf(hf_name)
              1.3.12. append_time()
              1.3.13. is_method(name)
              1.3.14. remove_hf(hname)

        1.4. Known Limitations

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. search usage
   1-2. search_append usage
   1-3. replace usage
   1-4. replace_all usage
   1-5. subst usage
   1-6. subst_uri usage
   1-7. subst usage
   1-8. append_to_reply usage
   1-9. append_hf usage
   1-10. append_urihf usage
   1-11. is_present_hf usage
   1-12. append_time usage
   1-13. is_method usage
   1-14. remove_hf usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This is mostly an example module. It implements text based
   operation (search, replace, append a.s.o).
     _________________________________________________________

1.1.1. Known Limitations

   search ignores folded lines. For example,
   search("(From|f):.*@foo.bar") doesn't match the following From
   header field:
From: medabeda
 <sip:medameda@foo.bar>;tag=1234
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * No dependencies on other OpenSER modules.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Functions

1.3.1. search(re)

   Searches for the re in the message.

   Meaning of the parameters is as follows:

     * re - Regular expression.

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

   Example 1-1. search usage
...
if ( search("[Ss][Ii][Pp]" ) { /*....*/ };
...
     _________________________________________________________

1.3.2. search_append(re, txt)

   Searches for the first match of re and appends txt after it.

   Meaning of the parameters is as follows:

     * re - Regular expression.
     * txt - String to be appended.

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

   Example 1-2. search_append usage
...
search_append("[Oo]pen[Ss]er", " SIP Proxy");
...
     _________________________________________________________

1.3.3. replace(re, txt)

   Replaces the first occurrence of re with txt.

   Meaning of the parameters is as follows:

     * re - Regular expression.
     * txt - String.

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

   Example 1-3. replace usage
...
replace("openser", "OpenSER SIP Proxy");
...
     _________________________________________________________

1.3.4. replace_all(re, txt)

   Replaces all occurrence of re with txt.

   Meaning of the parameters is as follows:

     * re - Regular expression.
     * txt - String.

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

   Example 1-4. replace_all usage
...
replace_all("openser", "OpenSER SIP Proxy");
...
     _________________________________________________________

1.3.5. subst('/re/repl/flags')

   Replaces re with repl (sed or perl like).

   Meaning of the parameters is as follows:

     * '/re/repl/flags' - sed like regular expression. flags can
       be a combination of i (case insensitive), g (global) or s
       (match newline don't treat it as end of line).
       're' - is regular expresion
       'repl' - is replacement string - may contain
       pseudo-varibales
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1-5. subst usage
...
# replace the uri in to: with the message uri (just an example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};

# replace the uri in to: with the value of avp sip_address (just an exa
mple)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)
\2/ig') ) {};

...
     _________________________________________________________

1.3.6. subst_uri('/re/repl/flags')

   Runs the re substitution on the message uri (like subst but
   works only on the uri)

   Meaning of the parameters is as follows:

     * '/re/repl/flags' - sed like regular expression. flags can
       be a combination of i (case insensitive), g (global) or s
       (match newline don't treat it as end of line).
       're' - is regular expresion
       'repl' - is replacement string - may contain
       pseudo-varibales
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1-6. subst_uri usage
...
# adds 3463 prefix to numeric uris, and save the original uri (\0 match
)
# as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$

# adds the avp 'uri_prefix' as prefix to numeric uris, and save the ori
ginal
# uri (\0 match) as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=
\0/i')){$

...
     _________________________________________________________

1.3.7. subst_user('/re/repl/flags')

   Runs the re substitution on the message uri (like subst_uri
   but works only on the user portion of the uri)

   Meaning of the parameters is as follows:

     * '/re/repl/flags' - sed like regular expression. flags can
       be a combination of i (case insensitive), g (global) or s
       (match newline don't treat it as end of line).
       're' - is regular expresion
       'repl' - is replacement string - may contain
       pseudo-varibales
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1-7. subst usage
...
# adds 3463 prefix to uris ending with 3642 (just an example)
if (subst_user('/3642$/36423463/')){$

...
# adds avp 'user_prefix' as prefix to username in r-uri ending with 364
2
if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$

...
     _________________________________________________________

1.3.8. append_to_reply(txt)

   Append txt to the reply.

   Meaning of the parameters is as follows:

     * txt - String.

   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE.

   Example 1-8. append_to_reply usage
...
append_to_reply("Foo: bar\r\n");
...
     _________________________________________________________

1.3.9. append_hf(hf)

   Appends txt after the last header field.

   Meaning of the parameters is as follows:

     * hf - Header field to be appended.

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

   Example 1-9. append_hf usage
...
append_hf("P-hint: VOICEMAIL\r\n");
...
     _________________________________________________________

1.3.10. 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-10. append_urihf usage
...
append_urihf("CC-Diversion: ", "\r\n");
...
     _________________________________________________________

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

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

   Example 1-11. is_present_hf usage
...
if (is_present_hf("From")) log(1, "From HF Present");
...
     _________________________________________________________

1.3.12. append_time()

   Adds a time header to the message. 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-12. append_time usage
...
append_time();
...
     _________________________________________________________

1.3.13. 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 OpenSER with
   ID (invite, cancel, ack, bye, options, info, update, register,
   message, subscribe, notify, refer, prack).

   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.

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

1.3.14. 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 - header name to be removed.

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

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

1.4. Known Limitations

   Search functions are applied to the original request, i.e.,
   they ignore all changes resulting from message processing in
   OpenSER script.
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://openser.org/bugs.
