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.
397 lines
12 KiB
397 lines
12 KiB
1. Usrloc Module
|
|
|
|
Jan Janak
|
|
|
|
FhG FOKUS
|
|
|
|
Copyright © 2003 FhG FOKUS
|
|
__________________________________________________________________
|
|
|
|
1.1. Overview
|
|
1.2. Dependencies
|
|
1.3. Parameters
|
|
|
|
1.3.1. user_column (string)
|
|
1.3.2. contact_column (string)
|
|
1.3.3. expires_column (string)
|
|
1.3.4. q_column (string)
|
|
1.3.5. callid_column (string)
|
|
1.3.6. cseq_column (string)
|
|
1.3.7. method_column (string)
|
|
1.3.8. user_agent_column (string)
|
|
1.3.9. received_column (string)
|
|
1.3.10. db_url (string)
|
|
1.3.11. timer_interval (integer)
|
|
1.3.12. db_mode (integer)
|
|
|
|
1.4. Usrloc Module API
|
|
|
|
1.4.1. ul_register_domain(name)
|
|
1.4.2. ul_insert_urecord(domain, aor, rec)
|
|
1.4.3. ul_delete_urecord(domain, aor)
|
|
1.4.4. ul_get_urecord(domain, aor)
|
|
1.4.5. ul_lock_udomain(domain)
|
|
1.4.6. ul_unlock_udomain(domain)
|
|
1.4.7. ul_release_urecord(record)
|
|
1.4.8. ul_insert_ucontact(record, contact, expires, q, callid,
|
|
cseq, flags, cont, ua)
|
|
|
|
1.4.9. ul_delete_ucontact(record, contact)
|
|
1.4.10. ul_get_ucontact(record, contact)
|
|
1.4.11. ul_get_all_ucontacts(buf, len, flags)
|
|
1.4.12. ul_update_ucontact(contact, expires, q, callid, cseq, set,
|
|
res, ua)
|
|
|
|
1.1. Overview
|
|
|
|
User location module. The module keeps a user location table and
|
|
provides access to the table to other modules. The module exports no
|
|
functions that could be used directly from scripts.
|
|
|
|
1.2. Dependencies
|
|
|
|
The following modules must be loaded before this module:
|
|
* Optionally a database module.
|
|
|
|
1.3. Parameters
|
|
|
|
1.3.1. user_column (string)
|
|
|
|
Name of column containing usernames.
|
|
|
|
Default value is "username".
|
|
|
|
Example 1. Set user_column parameter
|
|
...
|
|
modparam("usrloc", "user_column", "username")
|
|
...
|
|
|
|
1.3.2. contact_column (string)
|
|
|
|
Name of column containing contacts.
|
|
|
|
Default value is "contact".
|
|
|
|
Example 2. Set contact_column parameter
|
|
...
|
|
modparam("usrloc", "contact_column", "contact")
|
|
...
|
|
|
|
1.3.3. expires_column (string)
|
|
|
|
Name of column containing expires value.
|
|
|
|
Default value is "expires".
|
|
|
|
Example 3. Set expires_column parameter
|
|
...
|
|
modparam("usrloc", "expires_column", "expires")
|
|
...
|
|
|
|
1.3.4. q_column (string)
|
|
|
|
Name of column containing q values.
|
|
|
|
Default value is "q".
|
|
|
|
Example 4. Set q_column parameter
|
|
...
|
|
modparam("usrloc", "q_column", "q")
|
|
...
|
|
|
|
1.3.5. callid_column (string)
|
|
|
|
Name of column containing callid values.
|
|
|
|
Default value is "callid".
|
|
|
|
Example 5. Set callid_column parameter
|
|
...
|
|
modparam("usrloc", "callid_column", "callid")
|
|
...
|
|
|
|
1.3.6. cseq_column (string)
|
|
|
|
Name of column containing cseq numbers.
|
|
|
|
Default value is "cseq".
|
|
|
|
Example 6. Set cseq_column parameter
|
|
...
|
|
modparam("usrloc", "cseq_column", "cseq")
|
|
...
|
|
|
|
1.3.7. method_column (string)
|
|
|
|
Name of column containing supported methods.
|
|
|
|
Default value is "method".
|
|
|
|
Example 7. Set method_column parameter
|
|
...
|
|
modparam("usrloc", "method_column", "method")
|
|
...
|
|
|
|
1.3.8. user_agent_column (string)
|
|
|
|
Name of column containing user-agent values.
|
|
|
|
Default value is "user_agent".
|
|
|
|
Example 8. Set user_agent_column parameter
|
|
...
|
|
modparam("usrloc", "user_agent_column", "user_agent")
|
|
...
|
|
|
|
1.3.9. received_column (string)
|
|
|
|
Name of column containing the source IP, port, and protocol from the
|
|
REGISTER message.
|
|
|
|
Default value is "received".
|
|
|
|
Example 9. Set received_column parameter
|
|
...
|
|
modparam("usrloc", "received_column", "received")
|
|
...
|
|
|
|
1.3.10. db_url (string)
|
|
|
|
URL of the database that should be used.
|
|
|
|
Default value is "mysql://ser:heslo@localhost/ser".
|
|
|
|
Example 10. Set db_url parameter
|
|
...
|
|
modparam("usrloc", "db_url", "mysql://username:password@localhost/ser")
|
|
...
|
|
|
|
1.3.11. timer_interval (integer)
|
|
|
|
Number of seconds between two timer runs. The module uses timer to
|
|
delete expired contacts, synchronize with database and other tasks,
|
|
that need to be run periodically.
|
|
|
|
Default value is 60.
|
|
|
|
Example 11. Set timer_interval parameter
|
|
...
|
|
modparam("usrloc", "timer_interval", 120)
|
|
...
|
|
|
|
1.3.12. db_mode (integer)
|
|
|
|
The usrloc module can utilize database for persistent contact storage.
|
|
If you use database, your contacts will survive machine restarts or SW
|
|
crashes. The disadvantage is that accessing database can be very time
|
|
consuming. Therefore, usrloc module implements four database accessing
|
|
modes:
|
|
* 0 - This disables database completely. Only memory will be used.
|
|
Contacts will not survive restart. Use this value if you need a
|
|
really fast usrloc and contact persistence is not necessary or is
|
|
provided by other means.
|
|
* 1 - Write-Through scheme. All changes to usrloc are immediately
|
|
reflected in database too. This is very slow, but very reliable.
|
|
Use this scheme if speed is not your priority but need to make sure
|
|
that no registered contacts will be lost during crash or reboot.
|
|
* 2 - Write-Back scheme. This is a combination of previous two
|
|
schemes. All changes are made to memory and database
|
|
synchronization is done in the timer. The timer deletes all expired
|
|
contacts and flushes all modified or new contacts to database. Use
|
|
this scheme if you encounter high-load peaks and want them to
|
|
process as fast as possible. The mode will not help at all if the
|
|
load is high all the time. Also, latency of this mode is much lower
|
|
than latency of mode 1, but slightly higher than latency of mode 0.
|
|
* 3 - Read-Only scheme. Disables commits to database. Upon start
|
|
contacts are read from the database but changes are not written.
|
|
Contacts will thus not survive a restart unless taken care of
|
|
otherwise. Use this if you need the benefits of mode 0 with a
|
|
databases backed preloading feature. Attention: There is a slight
|
|
window where updated contacts might not make it into memory while
|
|
reading and parsing contacts from the database before going into
|
|
full production mode.
|
|
|
|
Warning
|
|
|
|
In case of crash or restart contacts that are in memory only and
|
|
haven't been flushed yet will get lost. If you want minimize the risk,
|
|
use shorter timer interval.
|
|
|
|
Default value is 0.
|
|
|
|
Example 12. Set db_mode parameter
|
|
...
|
|
modparam("usrloc", "db_mode", 2)
|
|
...
|
|
|
|
1.4. Usrloc Module API
|
|
|
|
1.4.1. ul_register_domain(name)
|
|
|
|
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.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* const char* name - Name of the domain (also called table) to be
|
|
registered.
|
|
|
|
1.4.2. ul_insert_urecord(domain, aor, rec)
|
|
|
|
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.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of Record (aka username) of the new record (at
|
|
this time the record will contain no contacts yet).
|
|
|
|
* urecord_t** rec - The newly created record structure.
|
|
|
|
1.4.3. ul_delete_urecord(domain, aor)
|
|
|
|
The function deletes all the contacts bound with the given Address Of
|
|
Record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of record (aka username) of the record, that
|
|
should be deleted.
|
|
|
|
1.4.4. ul_get_urecord(domain, aor)
|
|
|
|
The function returns pointer to record with given Address of Record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of Record of request record.
|
|
|
|
1.4.5. ul_lock_udomain(domain)
|
|
|
|
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.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Domain to be locked.
|
|
|
|
1.4.6. ul_unlock_udomain(domain)
|
|
|
|
Unlock the specified domain previously locked by ul_lock_udomain.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Domain to be unlocked.
|
|
|
|
1.4.7. ul_release_urecord(record)
|
|
|
|
Do some sanity checks - if all contacts have been removed, delete the
|
|
entire record structure.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record to be released.
|
|
|
|
1.4.8. ul_insert_ucontact(record, contact, expires, q, callid, cseq, flags,
|
|
cont, ua)
|
|
|
|
The function inserts a new contact in the given record with specified
|
|
parameters.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record in which the contact should be inserted.
|
|
|
|
* str* contact - Contact URI.
|
|
|
|
* time_t expires - Expires of the contact in absolute value.
|
|
|
|
* float q - q value of the contact.
|
|
|
|
* str* callid - Call-ID of the REGISTER message that contained the
|
|
contact.
|
|
|
|
* int cseq - CSeq of the REGISTER message that contained the contact.
|
|
|
|
* unsigned int flags - Flags to be set.
|
|
|
|
* ucontact_t* cont - Pointer to newly created structure.
|
|
|
|
* str* ua - User-Agent of the REGISTER message that contained the
|
|
contact.
|
|
|
|
1.4.9. ul_delete_ucontact(record, contact)
|
|
|
|
The function deletes given contact from record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record from which the contact should be
|
|
removed.
|
|
|
|
* ucontact_t* contact - Contact to be deleted.
|
|
|
|
1.4.10. ul_get_ucontact(record, contact)
|
|
|
|
The function tries to find contact with given Contact URI and returns
|
|
pointer to structure representing the contact.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record to be searched for the contact.
|
|
|
|
* str_t* contact - URI of the request contact.
|
|
|
|
1.4.11. ul_get_all_ucontacts(buf, len, flags)
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* void* buf - Buffer for returning contacts.
|
|
|
|
* int len - Length of the buffer.
|
|
|
|
* unsigned int flags - Flags that must be set.
|
|
|
|
1.4.12. ul_update_ucontact(contact, expires, q, callid, cseq, set, res, ua)
|
|
|
|
The function updates contact with new values.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* ucontact_t* contact - Contact URI.
|
|
|
|
* time_t expires - Expires of the contact in absolute value.
|
|
|
|
* float q - q value of the contact.
|
|
|
|
* str* callid - Call-ID of the REGISTER message that contained the
|
|
contact.
|
|
|
|
* int cseq - CSeq of the REGISTER message that contained the contact.
|
|
|
|
* unsigned int set - OR value of flags to be set.
|
|
|
|
* unsigned int res - OR value of flags to be reset.
|
|
|
|
* str* ua - User-Agent of the REGISTER message that contained the
|
|
contact.
|