mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
421 lines
11 KiB
421 lines
11 KiB
<?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>
|