$Revision: 2449 $
$Date: 2007-07-13 13:08:18 +0300 (Fri, 13 Jul 2007) $
User's Guide
Overview
This is mostly an example module. It implements text based operation
(search, replace, append a.s.o).
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
Dependencies
&ser; Modules
The following modules must be loaded before this module:
No dependencies on other &ser; modules.
External Libraries or Applications
The following libraries or applications must be installed before
running &ser; with this module loaded:
None.
Exported Functions
<function moreinfo="none">search(re)</function>
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.
<function>search</function> usage
...
if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
...
<function moreinfo="none">search_body(re)</function>
Searches for the re in the body of 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.
<function>search_body</function> usage
...
if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
...
<function moreinfo="none">search_append(re, txt)</function>
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.
<function>search_append</function> usage
...
search_append("[Oo]pen[Ss]er", " SIP Proxy");
...
<function moreinfo="none">search_append_body(re, txt)</function>
Searches for the first match of re in the body of the message
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.
<function>search_append_body</function> usage
...
search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
...
<function moreinfo="none">replace(re, txt)</function>
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.
<function>replace</function> usage
...
replace("openser", "OpenSER SIP Proxy");
...
<function moreinfo="none">replace_body(re, txt)</function>
Replaces the first occurrence of re in the body of the message
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.
<function>replace_body</function> usage
...
replace_body("openser", "OpenSER SIP Proxy");
...
<function moreinfo="none">replace_all(re, txt)</function>
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.
<function>replace_all</function> usage
...
replace_all("openser", "OpenSER SIP Proxy");
...
<function moreinfo="none">replace_body_all(re, txt)</function>
Replaces all occurrence of re in the body of the message
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.
<function>replace_body_all</function> usage
...
replace_body_all("openser", "OpenSER SIP Proxy");
...
<function moreinfo="none">subst('/re/repl/flags')</function>
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.
<function>subst</function> 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 example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') ) {};
...
<function moreinfo="none">subst_uri('/re/repl/flags')</function>
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.
<function>subst_uri</function> 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 original
# 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')){$
...
<function moreinfo="none">subst_user('/re/repl/flags')</function>
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.
<function>subst</function> 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 3642
if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
...
<function moreinfo="none">subst_body('/re/repl/flags')</function>
Replaces re with repl (sed or perl like) in the body of the message.
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.
<function>subst_body</function> usage
...
if ( subst_body('/^o=(.*) /o=$fU ') ) {};
...
<function moreinfo="none">append_to_reply(txt)</function>
Append txt as header to the reply.
Meaning of the parameters is as follows:
txt - String which may contains
pseudo-variables.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
ERROR_ROUTE.
<function>append_to_reply</function> usage
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...
<function moreinfo="none">append_hf(txt)</function>
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.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
FAILURE_ROUTE, BRANCH_ROUTE.
<function>append_hf</function> usage
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n");
...
<function moreinfo="none">append_hf(txt, hdr)</function>
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.
<function>append_hf</function> usage
...
append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
append_hf("From-username: $fU\r\n", "Call-ID");
...
<function moreinfo="none">insert_hf(txt)</function>
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.
<function>insert_hf</function> usage
...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
...
<function moreinfo="none">insert_hf(txt, hdr)</function>
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.
<function>insert_hf</function> usage
...
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...
<function moreinfo="none">append_urihf(prefix, suffix)</function>
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.
<function>append_urihf</function> usage
...
append_urihf("CC-Diversion: ", "\r\n");
...
<function moreinfo="none">is_present_hf(hf_name)</function>
Return true if a header field is present in message.
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.
<function>is_present_hf</function> usage
...
if (is_present_hf("From")) log(1, "From HF Present");
...
<function moreinfo="none">append_time()</function>
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.
<function>append_time</function> usage
...
append_time();
...
<function moreinfo="none">is_method(name)</function>
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 &ser; 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.
<function>is_method</function> usage
...
if(is_method("INVITE"))
{
# process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
# process OPTIONs and UPDATEs here
}
...
<function moreinfo="none">remove_hf(hname)</function>
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.
<function>remove_hf</function> usage
...
if(remove_hf("User-Agent"))
{
# User Agent header removed
}
...
<function moreinfo="none">has_body()</function>,
<function moreinfo="none">has_body(mime)</function>
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.
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.
<function>has_body</function> usage
...
if(has_body("application/sdp"))
{
# do interesting stuff here
}
...
<function moreinfo="none">is_privacy(privacy_type)</function>
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.
<function>is_privacy</function> usage
...
if(is_privacy("id"))
{
# do interesting stuff here
}
...
Known Limitations
Search functions are applied to the original request,
i.e., they ignore all changes resulting from message
processing in &ser; script.