kamailio/misc/obsolete/textops/doc/functions.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="textops.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Functions</title>

    <section id="search">
	<title>
	    <function>search(re)</function>
	</title>
	<para>
	    Searches for the re in the message.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>re</emphasis> - Regular expression.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>search</function> usage</title>
	    <programlisting>
...
if ( search("[Ss][Ee][Rr]" ) { /*....*/ };
...
	    </programlisting>
	</example>
    </section>

    <section id="search_append">
	<title>
	    <function>search_append(re, txt)</function>
	</title>
	<para>
	    Searches for the first match of re and appends txt after it.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>re</emphasis> - Regular expression.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>txt</emphasis> - String to be appended. Xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>search_append</function> usage</title>
	    <programlisting>
...
search_append("[Ss]er", " blabla");
...
	    </programlisting>
	</example>
    </section>

    <section id="replace">
	<title>
	    <function>replace(re, txt)</function>
	</title>
	<para>
	    Replaces the first occurrence of re with txt.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>re</emphasis> - Regular expression.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>txt</emphasis> - String. Xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>replace</function> usage</title>
	    <programlisting>
...
replace("ser", "Sip Express Router");
...
	    </programlisting>
	</example>
    </section>

    <section id="subst">
	<title>
	    <function>subst('/re/repl/flags')</function>
	</title>
	<para>
	    Replaces re with repl (sed or perl like).
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>'/re/repl/flags'</emphasis> - 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).
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>subst</function> usage</title>
	    <programlisting>
...
# 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') ) {};
...
	    </programlisting>
	</example>
    </section>

    <section id="subst_uri">
	<title>
	    <function>subst_uri('/re/repl/flags')</function>
	</title>
	<para>
	    Runs the re substitution on the message uri (like subst but works
	    only on the uri)
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>'/re/repl/flags'</emphasis> - 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).
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>subst</function> usage</title>
	    <programlisting>
...
# 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')){$
...
	    </programlisting>
	</example>
    </section>

    <section id="subst_user">
	<title>
	    <function>subst_user('/re/repl/flags')</function>
	</title>
	<para>
	    Runs the re substitution on the message uri (like subst_uri but
	    works only on the user portion of the uri)
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>'/re/repl/flags'</emphasis> - 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).
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>subst</function> usage</title>
	    <programlisting>
...
# adds 3463 prefix to uris ending with 3642 (just an example)
if (subst_user('/3642$/36423463/')){$
...
	    </programlisting>
	</example>
    </section>

    <section id="append_to_reply">
	<title>
	    <function>append_to_reply(txt)</function>
	</title>
	<para>
	    Append txt to the reply.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>txt</emphasis> - String. Xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>append_to_reply</function> usage</title>
	    <programlisting>
...
append_to_reply("Foo: bar\r\n");
...
	    </programlisting>
	</example>
    </section>

    <section id="append_hf">
	<title>
	    <function>append_hf(hf)</function>
	</title>
	<para>
	    Appends txt after the last header field.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field to be appended. Xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>append_hf</function> usage</title>
	    <programlisting>
...
append_hf("P-hint: VOICEMAIL\r\n");
...
	    </programlisting>
	</example>
    </section>

    <section id="append_urihf">
	<title>
	    <function>append_urihf(prefix, suffix)</function>
	</title>
	<para>
	    Append header field name with original <acronym>Request-URI</acronym> in middle.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>prefix</emphasis> - string (usually at least header field name). Xl_lib formatting supported.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>suffix</emphasis> - string (usually at least line terminator). Xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>append_urihf</function> usage</title>
	    <programlisting>
...
append_urihf("CC-Diversion: ", "\r\n");
...
	    </programlisting>
	</example>
    </section>

    <section id="is_present_hf">
	<title>
	    <function>is_present_hf(hf_name)</function>
	</title>
	<para>
	    Return true if a header field is present in message.
	</para>
	<note>
	    <para>
		Takes header field names "as is" and doesn't distinguish compact
		names.
	    </para>
	</note>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_name</emphasis> - Header field name.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>is_present_hf</function> usage</title>
	    <programlisting>
...
if (is_present_hf("From")) log(1, "From HF Present");
...
	    </programlisting>
	</example>
    </section>

    <section id="append_time">
	<title>
	    <function>append_time()</function>
	</title>
	<para>
	    Append "Date" header containing the current date and time to the
	    reply generated by SER.
	</para>
	<example>
	    <title><function>is_present_hf</function> usage</title>
	    <programlisting>
...
if (method == "REGISTER" ) {
    # Many user agents can use the Date header field
    # in 200 OK replies to REGISTER to synchronize
    # internal clock
    append_time();
};
...
	    </programlisting>
	</example>
    </section>

    <section id="remove_hf">
	<title>
	    <function>remove_hf(hf_name)</function>
	</title>
	<para>
		Remove from the message all the headers with the specified name.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_name</emphasis> - Header field name to be removed.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>remove_hf</function> usage</title>
	    <programlisting>
...
remove_hf("Subject")  # strip all headers whose name is "Subject".
...
	    </programlisting>
	</example>
    </section>

    <section id="remove_hf_re">
	<title>
	    <function>remove_hf_re(reg_exp)</function>
	</title>
	<para>
		Remove from the message all the headers whose names match a given
		regular expression.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>reg_exp</emphasis> - Regular expression that is
		matched against header name fields.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>remove_hf_re</function> usage</title>
	    <programlisting>
...
remove_hf_re("Subject|P-.*|X-.*")  # strip all headers whose names match
"Subject", contain "P-" or "X-".
...
	    </programlisting>
	</example>
    </section>

    <section id="append_hf_value">
	<title>
	    <function>append_hf_value(hf, xl_value)</function>
	</title>
	<para>
		Append new header value after an existing header, if no index acquired append at the end of
		list. Note that a header may consist of comma delimited list of values.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field to be appended. Format: HFNAME [ [IDX] ].
		If index is not specified new header is inserted at the end of message.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>xl_value</emphasis> - Value to be added, xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>append_hf_value</function> usage</title>
	    <programlisting>
...
append_hf_value("foo", "gogo;stamp=%Ts")   # add new header
append_hf_value("foo[1]", "gogo")  # add new value behind first value
append_hf_value("foo[-1]", "%@Bar") # try add value to the last header, if not exists add new header
...
	    </programlisting>
	</example>
    </section>

    <section id="insert_hf_value">
	<title>
	    <function>insert_hf_value(hf, xl_value)</function>
	</title>
	<para>
		Insert new header value before an existing header, if no index acquired insert before first
		hf header. Note that a header may consist of comma delimited list of values.
		To insert value behing last value use <function>appenf_hf_value</function>.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field to be appended. Format: HFNAME [ [IDX] ].
		If index is not specified new header is inserted at the top of message.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>xl_value</emphasis> - Value to be added, xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>insert_hf_value</function> usage</title>
	    <programlisting>
...
insert_hf_value("foo[2]", "gogo")
insert_hf_value("foo", "%$an_avp")   # add new header at the top of list
insert_hf_value("foo[1]", "gogo") # try add to the first header
...
	    </programlisting>
	</example>
    </section>

    <section id="remove_hf_value">
	<title>
	    <function>remove_hf_value(hf_par)</function>
	</title>
	<para>
		Remove the header value from existing header, Note that a header may consist of comma delimited list of values.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_par</emphasis> - Header field/param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ]
		If asterisk is specified as index then all values are affected.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>remove_hf_value</function> usage</title>
	    <programlisting>
...
remove_hf_value("foo")  # remove foo[1]
remove_hf_value("foo[*]")  # remove all foo's headers
remove_hf_value("foo[-1]") # last foo
remove_hf_value("foo.bar")  # delete parameter
remove_hf_value("foo[*].bar") # for each foo delete bar parameters
...
	    </programlisting>
	</example>
    </section>

    <section id="remove_hf_value2">
	<title>
	    <function>remove_hf_value2(hf_par)</function>
	</title>
	<para>
		Remove specified header or parameter. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).

	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_par</emphasis> - Header/param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ]
		If asterisk is specified as index then all values are affected.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>remove_hf_value2</function> usage</title>
	    <programlisting>
...
remove_hf_value2("foo")  # remove foo[1]
remove_hf_value2("foo[*]")  # remove all foo's headers, the same as remove_hf_header("foo[*]");
remove_hf_value2("foo[-1]") # last foo
remove_hf_value2("foo.bar")  # delete parameter
remove_hf_value2("foo[*].bar") # for each foo delete bar parameters
...
	    </programlisting>
	</example>
    </section>

    <section id="assign_hf_value">
	<title>
	    <function>assign_hf_value(hf, xl_value)</function>
	</title>
	<para>
		Assign value to specified header value / param.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_para</emphasis> - Header field value / param to be appended. Format: HFNAME [ [IDX] ] [. PARAM]
		If asterisk is specified as index then all values are affected.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>xl_value</emphasis> - Value to be assigned, xl_lib formatting supported. If value is empty then no equal sign apears in param.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>assign_hf_value</function> usage</title>
	    <programlisting>
...
assign_hf_value("foo", "gogo")  # foo[1]
assign_hf_value("foo[-1]", "gogo")  # foo[last_foo]

assign_hf_value("foo.bar", "")
assign_hf_value("foo[3].bar", "")
assign_hf_value("foo[*]", "")  # remove all foo's, empty value remains
assign_hf_value("foo[*].bar", "")  # set empty value (ex. lr)
...
	    </programlisting>
	</example>
    </section>

    <section id="assign_hf_value2">
	<title>
	    <function>assign_hf_value2(hf, xl_value)</function>
	</title>
	<para>
		Assign value to specified header. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf_para</emphasis> - Header field value / param to be appended. Format: HFNAME [ [IDX] ] [. PARAM]
		If asterisk is specified as index then all values are affected.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>xl_value</emphasis> - Value to be assigned, xl_lib formatting supported. If value is empty then no equal sign apears in param.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>assign_hf_value2</function> usage</title>
	    <programlisting>
...
assign_hf_value2("Authorization.integrity-protected", "\"yes\"")
assign_hf_value2("foo[-1]", "gogo")  # foo[last_foo]
assign_hf_value2("foo[*].bar", "")  # set empty value (ex. lr)
...
	    </programlisting>
	</example>
    </section>

    <section id="include_hf_value">
	<title>
	    <function>include_hf_value(hf, xl_value)</function>
	</title>
	<para>
		Add value in set if not exists, eg. "Supported: path,100rel".
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field name to be affected.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>value</emphasis> - xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>include_hf_value</function> usage</title>
	    <programlisting>
...
include_hf_value("Supported", "path");
...
	    </programlisting>
	</example>
    </section>

    <section id="exclude_hf_value">
	<title>
	    <function>exclude_hf_value(hf, xl_value)</function>
	</title>
	<para>
		Remove value from set if exists, eg. "Supported: path,100rel".
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field name to be affected.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>value</emphasis> - xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>exclude_hf_value</function> usage</title>
	    <programlisting>
...
exclude_hf_value("Supported", "100rel");
...
	    </programlisting>
	</example>
    </section>

    <section id="hf_value_exists">
	<title>
	    <function>hf_value_exists(hf, xl_value)</function>
	</title>
	<para>
		Check if value exists in set. Alternate select <emphasis>@hf_value_exists.HF.VALUE</emphasis>
		may be used. It returns one or zero.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>hf</emphasis> - Header field name to be affected. Underscores are treated as dashes.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>value</emphasis> - xl_lib formatting supported.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>hf_value_exists</function> usage</title>
	    <programlisting>
...
if (hf_value_exists("Supported", "100rel")) {

}

if (@hf_value_exists.supported.path == "1") {

}
...
	    </programlisting>
	</example>
    </section>

    <section id="@hf_value">
	<title>
	    <function>@hf_value selects</function>
	</title>
	<para>
		Get value of required header-value or param. Note that functions called 'value2'
		works with Authorization-like headers where comma is not treated as value delimiter. Formats:
		@hf_value.HFNAME[IDX]    # idx value, negative value counts from bottom
		@hf_value.HFNAME.PARAM_NAME
		@hf_value.HFNAME[IDX].PARAM_NAME
		@hf_value.HFNAME.p.PARAM_NAME  # or .param., useful if requred called "uri", "p", "param"
		@hf_value.HFNAME[IDX].p.PARAM_NAME # dtto
		@hf_value.HFNAME[IDX].uri # (&lt; &amp; &gt; excluded)
		@hf_value.HFNAME[*]     # return comma delimited list of all values (combines headers)
		@hf_value.HFNAME        # the same as above [*] but may be parsed by cfg.y
		@hf_value.HFNAME[*].uri # return comma delimited list of uris (&lt; &amp; &gt; excluded)
		@hf_value.HFNAME.uri    # the same as above [*] but may be parsed by cfg.y
		@hf_value.HFNAME[IDX].name  # returns name part, quotes excluded
		@hf_value.HFNAME.name   # returns name part of the first value

		@hf_value2.HFNAME        # returns value of first header
		@hf_value2.HFNAME[IDX]   # returns value of idx's header
		@hf_value2.HFNAME.PARAM_NAME
		@hf_value2.HFNAME[IDX].PARAM_NAME

		@hf_value.HFNAME[IDX].uri  # return URI, quotes excluded
		@hf_value.HFNAME.p.uri  # returns param named uri, not URI itself
		@hf_value.HFNAME.p.name # returns param named name, not name itself
		@hf_value.HFNAME[IDX].uri.name #  any sel_any_uri nested features may be used
		@hf_value.HFNAME[IDX].nameaddr.name # select_any_nameaddr
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>HFNAME</emphasis> - Header field name. Underscores are treated as dashes.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>IDX</emphasis> - Value index, negative value counts from bottom
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>PARAM_NAME</emphasis> - name of parameter
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>@hf_value select</function> usage</title>
	    <programlisting>
...
$a = @hf_value.my_header[1].my_param;
xplog("L_ERR", "%@hf_value.via[-1], %@hf_value.from.tag\n");
$b = @hf_value.p_associated_uri;

xplog("L_ERR", "Route uris: '%@hf_value.route[*].uri'\n");
$rr = @hf_value.route.uri;

$prt = @hf_value2.authorization.integrity_protected;
...
	    </programlisting>
	</example>
    </section>

</section>