<?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"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>

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

    <title>Functions</title>
    
    <section id="save">
	<title>
	    <function>save(domain)</function>
	</title>
	<para>
	    The function processes a REGISTER message. It can add, remove or
	    modify usrloc records depending on Contact and Expires HFs in the
	    REGISTER message. On success, 200 OK will be returned listing all
	    contacts that are currently in usrloc. On an error, error message
	    will be send with a short description in reason phrase.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>domain</emphasis> - Logical domain within registrar. If database
		    is used then this must be name of the table which stores the contacts.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>save</function> usage</title>
	    <programlisting>
...
save("location");
...
	    </programlisting>
	</example>
    </section>
    
    <section id="save_noreply">
	<title>
	    <function>save_noreply(domain)</function>
	</title>
	<para>
	    Same as <function>save()</function> but it doesn't send a reply.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>domain</emphasis> - Logical domain within registrar. If database is
		    used then this must be na e of the table which stores the contacts.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>save_noreply</function> usage</title>
	    <programlisting>
...
save_noreply("location");
...
	    </programlisting>
	</example>
    </section>
    
    <section id="lookup">
	<title>
	    <function>lookup(domain)</function>
	</title>
	<para>
	    The functions extracts username from Request-URI and tries to find
	    all contacts for the username in usrloc. If there are no such
	    contacts, -1 will be returned.  If there are such contacts,
	    Request-URI will be overwritten with the contact that has the
	    highest q value and optionally the rest will be appended to the
	    message (depending on append_branches parameter value).
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>domain</emphasis> - Name of table that should be used for the
		    lookup.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>lookup</function> usage</title>
	    <programlisting>
...
lookup("location");
...
	    </programlisting>
	</example>
    </section>
    
    <section id="registered">
	<title>
	    <function>registered(domain)</function>
	</title>
	<para>
	    The function returns true if the AOR in the Request-URI is
	    registered, false otherwise.  The function does not modify the
	    message being process, it neither rewrites the Request-URI if a
	    contact is found not append branches.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>domain</emphasis> - Name of table that should be used for the
		    lookup.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>registered</function> usage</title>
	    <programlisting>
...
if (registered("location")) {
    sl_send_reply("100", "Trying");
    ...
};
...
	    </programlisting>
	</example>
    </section>

</section>
