kamailio/misc/obsolete/usrloc/doc/api.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="usrloc.api" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Usrloc Module API</title>

    <section id="ul_register_domain">
	<title>
	    <function>ul_register_domain(name)</function>
	</title>
	<para>
	    The function registers a new domain. Domain is just another name
	    for table used in registrar. The function is called from fixups in
	    registrar. It gets name of the domain as a parameter and returns
	    pointer to a new domain structure. The fixup than 'fixes' the
	    parameter in registrar so that it will pass the pointer instead of
	    the name every time save() or lookup() is called. Some usrloc
	    functions get the pointer as parameter when called. For more
	    details see implementation of save function in registrar.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>const char* name</emphasis> - Name of the domain (also called
		    table) to be registered.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_insert_urecord">
	<title>
	    <function>ul_insert_urecord(domain, aor, rec)</function>
	</title>
	<para>
	    The function creates a new record structure and inserts it in the
	    specified domain. The record is structure that contains all the
	    contacts for belonging to the specified username.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>udomain_t* domain</emphasis> - Pointer to domain
		    returned by ul_register_udomain.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* aor</emphasis> - Address of Record (aka
		    username) of the new record (at this time the record will
		    contain no contacts yet).
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>urecord_t** rec</emphasis> - The newly created
		    record structure.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_delete_urecord">
	<title>
	    <function>ul_delete_urecord(domain, aor)</function>
	</title>
	<para>
	    The function deletes all the contacts bound with the given Address
	    Of Record.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>udomain_t* domain</emphasis> - Pointer to domain returned by ul_register_udomain.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* aor</emphasis> - Address of record (aka
		    username) of the record, that should be deleted.
		</para>
	    </listitem>
	</itemizedlist>
    </section>
    
    <section id="ul_get_urecord">
	<title>
	    <function>ul_get_urecord(domain, aor)</function>
	</title>
	<para>
	    The function returns pointer to record with given Address of Record.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>udomain_t* domain</emphasis> - Pointer to domain
		    returned by ul_register_udomain.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* aor</emphasis> - Address of Record of
		    request record.
		</para>
	    </listitem>
	</itemizedlist>
    </section>
    
    <section id="ul_lock_udomain">
	<title>
	    <function>ul_lock_udomain(domain)</function>
	</title>
	<para>
	    The function lock the specified domain, it means, that no other
	    processes will be able to access during the time. This prevents
	    race conditions. Scope of the lock is the specified domain, that
	    means, that multiple domain can be accessed simultaneously, they
	    don't block each other.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>udomain_t* domain</emphasis> - Domain to be locked.
		</para>
	    </listitem>
	</itemizedlist>
    </section>
    
    <section id="ul_unlock_udomain">
	<title>
	    <function>ul_unlock_udomain(domain)</function>
	</title>
	<para>
	    Unlock the specified domain previously locked by ul_lock_udomain.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>udomain_t* domain</emphasis> - Domain to be unlocked.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_release_urecord">
	<title>
	    <function>ul_release_urecord(record)</function>
	</title>
	<para>
	    Do some sanity checks - if all contacts have been removed, delete
	    the entire record structure.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>urecord_t* record</emphasis> - Record to be released.
		</para>
	    </listitem>
	</itemizedlist>
    </section>
    
    <section id="ul_insert_ucontact">
	<title>
	    <function>
		ul_insert_ucontact(record, contact, expires, q, callid, cseq,
		flags, cont, ua)
	    </function>
	</title>
	<para>
	    The function inserts a new contact in the given record with
	    specified parameters.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>urecord_t* record</emphasis> - Record in which
		    the contact should be inserted.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* contact</emphasis> - Contact URI.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>time_t expires</emphasis> - Expires of the
		    contact in absolute value.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>float q</emphasis> - q value of the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* callid</emphasis> - Call-ID of the REGISTER
		    message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>int cseq</emphasis> - CSeq of the REGISTER
		    message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>unsigned int flags</emphasis> - Flags to be set.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>ucontact_t* cont</emphasis> - Pointer to newly
		    created structure.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* ua</emphasis> - User-Agent of the REGISTER
		    message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_delete_ucontact">
	<title>
	    <function>ul_delete_ucontact(record, contact)</function>
	</title>
	<para>
	    The function deletes given contact from record.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>urecord_t* record</emphasis> - Record from which the contact should be removed.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para><emphasis>ucontact_t* contact</emphasis> - Contact to be deleted.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_get_ucontact">
	<title>
	    <function>ul_get_ucontact(record, contact)</function>
	</title>
	<para>
	    The function tries to find contact with given Contact URI and returns pointer to
	    structure representing the contact.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>urecord_t* record</emphasis> - Record to be
		    searched for the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str_t* contact</emphasis> - URI of the request
		    contact.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_get_all_ucontacts">
	<title>
	    <function>ul_get_all_ucontacts(buf, len, flags)</function>
	</title>
	<para>
	    The function retrieves all contacts of all registered users and
	    returns them in the caller-supplied buffer. If the buffer is too
	    small, the function returns positive value indicating how much
	    additional space would be necessary to accommodate all of
	    them. Please note that the positive return value should be used
	    only as a "hint", as there is no guarantee that during
	    the time between two subsequent calls number of registered contacts
	    will remain the same.
	</para>
	<para>
	    If flag parameter is set to non-zero value then only contacts that
	    have the specified flags set will be returned. It is, for example,
	    possible to list only contacts that are behind NAT.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>void* buf</emphasis> - Buffer for returning contacts.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>int len</emphasis> - Length of the buffer.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>unsigned int flags</emphasis> - Flags that must be set.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <section id="ul_update_ucontact">
	<title>
	    <function>
		ul_update_ucontact(contact, expires, q, callid, cseq, set, res,
		ua)
	    </function>
	</title>
	<para>
	    The function updates contact with new values.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>ucontact_t* contact</emphasis> - Contact URI.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>time_t expires</emphasis> - Expires of the contact in absolute value.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>float q</emphasis> - q value of the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* callid</emphasis> - Call-ID of the REGISTER message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>int cseq</emphasis> - CSeq of the REGISTER message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>unsigned int set</emphasis> - OR value of flags to be set.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>unsigned int res</emphasis> - OR value of flags to be reset.
		</para>
	    </listitem>
	</itemizedlist>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>str* ua</emphasis> - User-Agent of the REGISTER message that contained the contact.
		</para>
	    </listitem>
	</itemizedlist>
    </section>
</section>