modules_k/registrar/README
31ccf6a2
 registrar Module
 
 Jan Janak
 
    FhG FOKUS
 
9fc784c6
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
31ccf6a2
 Edited by
 
 Jan Janak
 
d77df08a
 Edited by
 
31ccf6a2
 Bogdan-Andre Iancu
 
8b2457cf
    Copyright © 2003 FhG FOKUS
d77df08a
    Revision History
e45ac57e
    Revision $Revision$ $Date$
      __________________________________________________________________
31ccf6a2
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
31ccf6a2
 
e45ac57e
         1. Overview
 
               1.1. PATH support
 
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Exported Parameters
 
               3.1. default_expires (integer)
4480f807
               3.2. default_expires_range (integer)
               3.3. min_expires (integer)
               3.4. max_expires (integer)
               3.5. default_q (integer)
               3.6. realm_prefix (string)
               3.7. append_branches (integer)
               3.8. aor_avp (str)
               3.9. case_sensitive (integer)
               3.10. received_avp (str)
               3.11. received_param (string)
               3.12. max_contacts (integer)
               3.13. retry_after (integer)
               3.14. sock_flag (integer)
               3.15. sock_hdr_name (string)
               3.16. method_filtering (integer)
               3.17. use_path (integer)
               3.18. path_mode (integer)
               3.19. path_use_received (integer)
               3.20. reg_callid_avp (string)
e45ac57e
 
         4. Exported Functions
 
               4.1. save(domain)
               4.2. save(domain,flags)
               4.3. lookup(domain)
               4.4. registered(domain)
               4.5. add_sock_hdr(hdr_name)
               4.6. unregister(domain, uri)
               4.7. reg_fetch_contacts(domain, uri, profile)
               4.8. reg_free_contacts(profile)
 
         5. Exported Statistics
 
               5.1. max_expires
               5.2. max_contacts
               5.3. defaults_expires
               5.4. accepted_regs
               5.5. rejected_regs
 
         6. Exported pseudo-variables
 
               6.1. $ulc(profile=>attr)
7a67411c
 
033b5989
    2. Frequently Asked Questions
31ccf6a2
 
    List of Examples
d77df08a
 
    1.1. Set default_expires parameter
4480f807
    1.2. Set default_expires_range parameter
    1.3. Set min_expires parameter
    1.4. Set max_expires parameter
    1.5. Set default_q parameter
    1.6. Set realm_prefix parameter
    1.7. Set append_branches parameter
    1.8. Set aor_avp parameter
    1.9. Set case_sensitive parameter
    1.10. Set received_avp parameter
    1.11. Set received_param parameter
    1.12. Set max_contacts parameter
    1.13. Set retry_after parameter
    1.14. Set sock_flag parameter
    1.15. Set sock_hdr_namer parameter
    1.16. Set method_filtering parameter
    1.17. Set use_path parameter
    1.18. Set path_mode parameter
    1.19. Set path_use_received parameter
    1.20. Set reg_callid_avp parameter
d77df08a
    1.21. save usage
4480f807
    1.22. save usage
    1.23. lookup usage
    1.24. registered usage
    1.25. add_sock_hdr usage
b235af63
    1.26. registered usage
7a67411c
    1.27. registered usage
4480f807
    1.28. registered usage
    1.29. $ulc(name) usage
31ccf6a2
 
9fc784c6
 Chapter 1. Admin Guide
31ccf6a2
 
e45ac57e
    Table of Contents
 
    1. Overview
 
         1.1. PATH support
 
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Exported Parameters
 
         3.1. default_expires (integer)
4480f807
         3.2. default_expires_range (integer)
         3.3. min_expires (integer)
         3.4. max_expires (integer)
         3.5. default_q (integer)
         3.6. realm_prefix (string)
         3.7. append_branches (integer)
         3.8. aor_avp (str)
         3.9. case_sensitive (integer)
         3.10. received_avp (str)
         3.11. received_param (string)
         3.12. max_contacts (integer)
         3.13. retry_after (integer)
         3.14. sock_flag (integer)
         3.15. sock_hdr_name (string)
         3.16. method_filtering (integer)
         3.17. use_path (integer)
         3.18. path_mode (integer)
         3.19. path_use_received (integer)
         3.20. reg_callid_avp (string)
e45ac57e
 
    4. Exported Functions
 
         4.1. save(domain)
         4.2. save(domain,flags)
         4.3. lookup(domain)
         4.4. registered(domain)
         4.5. add_sock_hdr(hdr_name)
         4.6. unregister(domain, uri)
         4.7. reg_fetch_contacts(domain, uri, profile)
         4.8. reg_free_contacts(profile)
 
    5. Exported Statistics
 
         5.1. max_expires
         5.2. max_contacts
         5.3. defaults_expires
         5.4. accepted_regs
         5.5. rejected_regs
 
    6. Exported pseudo-variables
 
         6.1. $ulc(profile=>attr)
 
 1. Overview
 
    1.1. PATH support
31ccf6a2
 
    The module contains REGISTER processing logic.
 
e45ac57e
 1.1. PATH support
bff5fbbc
 
e45ac57e
    Register module includes Path support (according to RFC 3327) for usage
    in registrars and home-proxies.
bff5fbbc
 
    A call to save(...) stores, if path-support is enabled in the
e45ac57e
    registrar-module, the values of the Path Header(s) along with the
    contact into usrloc. There are three modes regarding the reply to a
    REGISTER including one or more Path HFs:
      * off - stores the value of the Path headers into usrloc without
        passing it back to the UAC in the reply.
      * lazy - stores the Path header and passes it back to the UAC if
8b2457cf
        Path-support is indicated by the “path” param in the Supported HF.
      * strict - rejects the registration with “420 Bad Extension” if
e45ac57e
        there's a Path header but no support for it is indicated by the
        UAC. Otherwise it's stored and passed back to the UAC.
 
    A call to lookup(...) always uses the path header if found, and inserts
    it as Route HF either in front of the first Route HF, or after the last
    Via HF if no Route is present. It also sets the destination uri to the
    first Path uri, thus overwriting the received-uri, because NAT has to
    be handled at the outbound-proxy of the UAC (the first hop after
    client's NAT).
 
    The whole process is transparent to the user, so no config changes are
8b2457cf
    required beside setting the registrar-parameters “use_path” and
    “path_mode”.
e45ac57e
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
31ccf6a2
 
    The following modules must be loaded before this module:
      * usrloc - User Location Module.
      * sl - Stateless Replies.
 
e45ac57e
 2.2. External Libraries or Applications
31ccf6a2
 
e45ac57e
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
31ccf6a2
      * None.
 
e45ac57e
 3. Exported Parameters
 
    3.1. default_expires (integer)
4480f807
    3.2. default_expires_range (integer)
    3.3. min_expires (integer)
    3.4. max_expires (integer)
    3.5. default_q (integer)
    3.6. realm_prefix (string)
    3.7. append_branches (integer)
    3.8. aor_avp (str)
    3.9. case_sensitive (integer)
    3.10. received_avp (str)
    3.11. received_param (string)
    3.12. max_contacts (integer)
    3.13. retry_after (integer)
    3.14. sock_flag (integer)
    3.15. sock_hdr_name (string)
    3.16. method_filtering (integer)
    3.17. use_path (integer)
    3.18. path_mode (integer)
    3.19. path_use_received (integer)
    3.20. reg_callid_avp (string)
e45ac57e
 
 3.1. default_expires (integer)
 
    If the processed message contains neither Expires HFs nor expires
    contact parameters, this value will be used for newly created usrloc
    records. The parameter contains number of second to expire (for example
f565de5a
    use 3600 for one hour). If it is set to a lower value than the
8b2457cf
    “min_expires” parameter then it will be ignored. This parameter can be
4480f807
    modified via ser config framework. A random value in a specific
    interval can be selected by using the default_expires_range parameter
31ccf6a2
 
989206bd
    Default value is 3600.
31ccf6a2
 
d77df08a
    Example 1.1. Set default_expires parameter
31ccf6a2
 ...
 modparam("registrar", "default_expires", 1800)
 ...
 
4480f807
 3.2. default_expires_range (integer)
 
    This parameter specifies that the expiry used for newly created usrloc
    records are not fixed(when “default_expires” applies), but a random
    value in the interval “[default_expires-default_expires_range%,
    default_expires+default_expires_range%]”. The value is between 0 and
    100 and represent the maximim percentage from default_expires that will
    be substracted or added when computing the value. Default in 0, meaning
    default_expires is left unmodified. This parameter can be modified via
    ser config framework.
 
    Default value is 0.
 
    Example 1.2. Set default_expires_range parameter
 ...
 modparam("registrar", "default_expires", 30) # +- 30% from default_expires
 ...
 
 3.3. min_expires (integer)
31ccf6a2
 
e45ac57e
    The minimum expires value of a Contact, values lower than this minimum
    will be automatically set to the minimum. Value 0 disables the
8b2457cf
    checking. This parameter can be modified via ser config framework.
31ccf6a2
 
989206bd
    Default value is 60.
31ccf6a2
 
4480f807
    Example 1.3. Set min_expires parameter
31ccf6a2
 ...
 modparam("registrar", "min_expires", 60)
 ...
 
4480f807
 3.4. max_expires (integer)
31ccf6a2
 
e45ac57e
    The maximum expires value of a Contact, values higher than this maximum
    will be automatically set to the maximum. Value 0 disables the
8b2457cf
    checking. This parameter can be modified via ser config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
4480f807
    Example 1.4. Set max_expires parameter
31ccf6a2
 ...
 modparam("registrar", "max_expires", 120)
 ...
 
4480f807
 3.5. default_q (integer)
31ccf6a2
 
e45ac57e
    The parameter represents default q value for new contacts. Because
    Kamailio doesn't support float parameter types, the value in the
    parameter is divided by 1000 and stored as float. For example, if you
8b2457cf
    want default_q to be 0.38, use value 380 here. This parameter can be
    modified via ser config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
4480f807
    Example 1.5. Set default_q parameter
31ccf6a2
 ...
7baba426
 modparam("registrar", "default_q", 1000)
31ccf6a2
 ...
 
4480f807
 3.6. realm_prefix (string)
624ef7e8
 
e45ac57e
    Prefix to be automatically strip from realm. As an alternative to SRV
    records (not all SIP clients support SRV lookup), a subdomain of the
    master domain can be defined for SIP purposes (like sip.mydomain.net
    pointing to same IP address as the SRV record for mydomain.net). By
    ignoring the realm_prefix "sip.", at registration, sip.mydomain.net
8b2457cf
    will be equivalent to mydomain.net.This parameter can be modified via
    ser config framework.
624ef7e8
 
989206bd
    Default value is NULL (none).
624ef7e8
 
4480f807
    Example 1.6. Set realm_prefix parameter
624ef7e8
 ...
 modparam("registrar", "realm_prefix", "sip.")
 ...
 
4480f807
 3.7. append_branches (integer)
31ccf6a2
 
e45ac57e
    The parameter controls how lookup function processes multiple contacts.
    If there are multiple contacts for the given username in usrloc and
    this parameter is set to 1, Request-URI will be overwritten with the
    highest-q rated contact and the rest will be appended to sip_msg
    structure and can be later used by tm for forking. If the parameter is
    set to 0, only Request-URI will be overwritten with the highest-q rated
8b2457cf
    contact and the rest will be left unprocessed. This parameter can be
    modified via ser config framework.
31ccf6a2
 
989206bd
    Default value is 1.
31ccf6a2
 
4480f807
    Example 1.7. Set append_branches parameter
31ccf6a2
 ...
 modparam("registrar", "append_branches", 0)
 ...
 
4480f807
 3.8. aor_avp (str)
982b9d7a
 
e45ac57e
    If set, the module will try first to get the AOR from this AVP instead
    of fetching it form the processed request.
982b9d7a
 
e45ac57e
    The AVP must contain a valid SIP URI. If no AVP is found, it will be
    tried to get the AOR from the message (standard behaviour).
982b9d7a
 
989206bd
    Default value is "NULL" (disabled).
982b9d7a
 
4480f807
    Example 1.8. Set aor_avp parameter
982b9d7a
 ...
4c5fb67e
 modparam("registrar", "aor_avp", "$avp(i:3223)")
982b9d7a
 ...
 
4480f807
 3.9. case_sensitive (integer)
31ccf6a2
 
b0c6ef43
    If set to 1 then AOR comparison and also storing will be case
    sensitive, if set to 0 then AOR comparison and storing will be case
    insensitive--This is recommended. This parameter can be modified via
    ser config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
4480f807
    Example 1.9. Set case_sensitive parameter
31ccf6a2
 ...
 modparam("registrar", "case_sensitive", 1)
 ...
 
4480f807
 3.10. received_avp (str)
31ccf6a2
 
e45ac57e
    Registrar will store the value of the AVP configured by this parameter
    in the received column in the user location database. It will leave the
    column empty if the AVP is empty. The AVP should contain a SIP URI
    consisting of the source IP, port, and protocol of the REGISTER message
    being processed.
31ccf6a2
 
d77df08a
 Note
31ccf6a2
 
d77df08a
    The value of this parameter should be the same as the value of
    corresponding parameter of nathelper module.
31ccf6a2
 
989206bd
    Default value is "NULL" (disabled).
31ccf6a2
 
4480f807
    Example 1.10. Set received_avp parameter
31ccf6a2
 ...
8d9d76ed
 modparam("registrar", "received_avp", "$avp(s:rcv)")
31ccf6a2
 ...
 
4480f807
 3.11. received_param (string)
31ccf6a2
 
e45ac57e
    The name of the parameter that will be appended to Contacts of 200 OK
    when the received URI was set by nathelper module.
31ccf6a2
 
989206bd
    Default value is "received".
31ccf6a2
 
4480f807
    Example 1.11. Set received_param parameter
31ccf6a2
 ...
 modparam("registrar", "received_param", "rcv")
 ...
 
4480f807
 3.12. max_contacts (integer)
31ccf6a2
 
e45ac57e
    The parameter can be used to limit the number of contacts per AOR
    (Address of Record) in the user location database. Value 0 disables the
8b2457cf
    check. This parameter can be modified via ser config framework.
31ccf6a2
 
989206bd
    Default value is 0.
31ccf6a2
 
4480f807
    Example 1.12. Set max_contacts parameter
31ccf6a2
 ...
 # Allow no more than 10 contacts per AOR
 modparam("registrar", "max_contacts", 10)
 ...
 
4480f807
 3.13. retry_after (integer)
31ccf6a2
 
e45ac57e
    The registrar can generate 5xx reply to REGISTER in various situations.
    It can, for example, happen when the max_contacts parameter is set and
    the processing of REGISTER request would exceed the limit. In this case
8b2457cf
    the registrar would generate "503 Service Unavailable" response. This
    parameter can be modified via ser config framework.
31ccf6a2
 
e45ac57e
    If you want to add the Retry-After header field in 5xx replies, set
    this parameter to a value grater than zero (0 means do not add the
    header field). See section 20.33 of RFC3261 for more details.
31ccf6a2
 
989206bd
    Default value is 0 (disabled).
31ccf6a2
 
4480f807
    Example 1.13. Set retry_after parameter
31ccf6a2
 ...
 modparam("registrar", "retry_after", 30)
 ...
 
4480f807
 3.14. sock_flag (integer)
31ccf6a2
 
e45ac57e
    Message flag to signal to register module to look into REGISTER request
    for a header which contains a socket description (IP:port). This socket
    info will be stored by register instead of the received socket info.
31ccf6a2
 
    This make sens only in multiple replicated servers scenarios.
 
989206bd
    Default value is -1 (no flag).
31ccf6a2
 
4480f807
    Example 1.14. Set sock_flag parameter
31ccf6a2
 ...
 modparam("registrar", "sock_flag", 18)
 ...
 
4480f807
 3.15. sock_hdr_name (string)
31ccf6a2
 
e45ac57e
    Header which contains a socket description (proto:IP:port) to override
    the received socket info. The header will be read only if the flag
    sock_flag is set.
31ccf6a2
 
    This make sens only in multiple replicated servers scenarios.
 
989206bd
    Default value is NULL.
31ccf6a2
 
4480f807
    Example 1.15. Set sock_hdr_namer parameter
31ccf6a2
 ...
 modparam("registrar", "sock_hdr_name", "Sock-Info")
 ...
 
4480f807
 3.16. method_filtering (integer)
76af1362
 
e45ac57e
    Tells if the contact filtering based on supported methods should be
    performed during lookup. It's enabled only if it has a non zero value.
76af1362
 
989206bd
    Default value is 0 (disabled).
76af1362
 
4480f807
    Example 1.16. Set method_filtering parameter
76af1362
 ...
 modparam("registrar", "method_filtering", 1)
 ...
 
4480f807
 3.17. use_path (integer)
79bf803d
 
8b2457cf
    If set to 1, the Path header is handled according to the parameter This
    parameter can be modified via ser config framework. “path_mode”.
79bf803d
 
989206bd
    Default value is 0 (disabled).
79bf803d
 
4480f807
    Example 1.17. Set use_path parameter
79bf803d
 ...
 modparam("registrar", "use_path", 1)
 ...
 
4480f807
 3.18. path_mode (integer)
e45ac57e
 
    The registrar module implements three different modes regarding the
    response to a registration which includes one or more Path headers:
      * 0 - The Path header is saved into usrloc, but is not included in
        the reply.
      * 1 - The Path header is saved into usrloc, but is only included in
        the reply if path support is indicated in the registration request
8b2457cf
        by the “path” option of the “Supported” header.
e45ac57e
      * 2 - The path header is only saved into usrloc, if path support is
8b2457cf
        indicated in the registration request by the “path” option of the
        “Supported” header. If no path support is indicated, the request is
        rejected with “420 - Bad Extension” and the header “Unsupported:
        path” is included in the reply along with the received “Path”
e45ac57e
        header. This mode is the one recommended by RFC-3327.
79bf803d
 
989206bd
    Default value is 2.
79bf803d
 
4480f807
    Example 1.18. Set path_mode parameter
79bf803d
 ...
 modparam("registrar", "path_mode", 0)
 ...
 
4480f807
 3.19. path_use_received (integer)
932053d7
 
8b2457cf
    If set to 1, the “received” parameter of the first Path URI of a
e45ac57e
    registration is set as received-uri and the NAT branch flag is set for
    this contact. This is useful if the registrar is placed behind a SIP
8b2457cf
    loadbalancer, which passes the nat'ed UAC address as “received”
e45ac57e
    parameter in it's Path uri.
932053d7
 
989206bd
    Default value is 0 (disabled).
932053d7
 
4480f807
    Example 1.19. Set path_use_received parameter
932053d7
 ...
 modparam("registrar", "path_use_received", 1)
 ...
 
4480f807
 3.20. reg_callid_avp (string)
f0ed82ce
 
    If reg_callid_avp is defined and populated when registered() is
e45ac57e
    invoked, the result is TRUE only if an active registration with the
    specified callID is found.
f0ed82ce
 
    Default value is NULL (disabled).
 
4480f807
    Example 1.20. Set reg_callid_avp parameter
f0ed82ce
 ...
 modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
 ...
 
e45ac57e
 4. Exported Functions
31ccf6a2
 
e45ac57e
    4.1. save(domain)
    4.2. save(domain,flags)
    4.3. lookup(domain)
    4.4. registered(domain)
    4.5. add_sock_hdr(hdr_name)
    4.6. unregister(domain, uri)
    4.7. reg_fetch_contacts(domain, uri, profile)
    4.8. reg_free_contacts(profile)
31ccf6a2
 
f565de5a
 4.1.  save(domain)
e45ac57e
 
    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 and when called from the REQUEST_ROUTE, 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.
31ccf6a2
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Logical domain within registrar. If database is used then
        this must be name of the table which stores the contacts.
 
    Return codes:
      * -1 - error.
        1 - contacts inserted.
        2 - contacts updated.
        3 - contacts deleted.
        4 - contacts returned.
31ccf6a2
 
d02a8f6f
    This function can be used from REQUEST_ROUTE and REPLY_ROUTE.
bfcbd22f
 
4480f807
    Example 1.21. save usage
31ccf6a2
 ...
 save("location");
 ...
 
f565de5a
 4.2.  save(domain,flags)
31ccf6a2
 
e45ac57e
    Same as save() but it accepts a set of flags for controlling its
    behaviour.
31ccf6a2
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Logical domain within registrar. If database is used then
        this must be name of the table which stores the contacts.
      * flags - the value may be a bitwise OR of the following flags:
           + 0x01 - save the contacts only in memory cache without no DB
             operation;
           + 0x02 - do not generate a SIP reply to the current REGISTER
             request. When used in ONREPLY_ROUTE, this parameter is
             obsolete.
           + 0x04 - store and maintain one contact per AoR. If there are
             other contact addresses for AoR not matching current
             registration, remove them. This mode ensures one contact per
             AoR (user).
bf3705d3
        The flags may be given in decimal or hexa format.
31ccf6a2
 
d02a8f6f
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
bfcbd22f
 
4480f807
    Example 1.22. save usage
624ef7e8
 ...
0beda308
 save("location","0x01");
624ef7e8
 ...
 
f565de5a
 4.3.  lookup(domain)
31ccf6a2
 
e45ac57e
    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).
31ccf6a2
 
e45ac57e
    If the method_filtering option is enabled, the lookup function will
    return only the contacts that support the method of the processed
    request.
76af1362
 
31ccf6a2
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
 
76af1362
    Return codes:
      * 1 - contacts found and returned.
        -1 - no contact found.
        -2 - contacts found, but method not supported.
56853adf
        -3 - internal error during processing.
76af1362
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
4480f807
    Example 1.23. lookup usage
31ccf6a2
 ...
 lookup("location");
e832d080
 switch ($retcode) {
76af1362
     case -1:
     case -3:
         sl_send_reply("404", "Not Found");
         exit;
     case -2:
         sl_send_reply("405", "Not Found");
         exit;
 };
31ccf6a2
 ...
 
f565de5a
 4.4.  registered(domain)
31ccf6a2
 
e45ac57e
    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.
31ccf6a2
 
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
4480f807
    Example 1.24. registered usage
31ccf6a2
 ...
 if (registered("location")) {
         sl_send_reply("100", "Trying");
         ...
 };
 ...
 
f565de5a
 4.5.  add_sock_hdr(hdr_name)
31ccf6a2
 
8b2457cf
    Adds to the current REGISTER request a new header with “hdr_name” which
e45ac57e
    contains the description of the received socket (proto:ip:port)
31ccf6a2
 
    This make sens only in multiple replicated servers scenarios.
 
    Meaning of the parameters is as follows:
      * hdr_name - header name to be used.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE.
 
4480f807
    Example 1.25. add_sock_hdr usage
31ccf6a2
 ...
 add_sock_hdr("Sock-Info");
 ...
1061d103
 
f565de5a
 4.6.  unregister(domain, uri)
b235af63
 
    The function remove all the contact associated to 'uri'.
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Name of table that should be used for the lookup or
        contact addresses.
      * uri - The SIP URI address of the user which to remove the contact
        addresses for. It can contain pseudo-variables that are evaluated
        at runtime.
b235af63
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
4480f807
    Example 1.26. registered usage
b235af63
 ...
 unregister("location", "$ru");
 unregister("location", "sip:user@kamailio.org");
 ...
 
f565de5a
 4.7.  reg_fetch_contacts(domain, uri, profile)
7a67411c
 
e45ac57e
    The function fetches the contacts for 'uri' from table 'domain' to
    pseudo-variable $ulc(profile).
7a67411c
 
    Meaning of the parameters is as follows:
e45ac57e
      * domain - Name of table that should be used for the lookup of
        contact addresses.
      * uri - The SIP URI address of the user which to fetch the contact
        addresses for. It can contain pseudo-variables that are evaluated
        at runtime.
      * profile - Name of $ulc pseudo-variable profile that will store the
        fetched contacts. It is a static string.
7a67411c
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
4480f807
    Example 1.27. registered usage
7a67411c
 ...
 reg_fetch_contacts("location", "$ru", "callee");
 reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
 ...
 
f565de5a
 4.8.  reg_free_contacts(profile)
7a67411c
 
e45ac57e
    The function frees the contacts from pseudo-variable $ulc(profile).
    Should be called to release the content of a profile. Anyhow, fetching
    a new contact addresses set over a profile will release any existing
    data in that profile.
7a67411c
 
    Meaning of the parameters is as follows:
e45ac57e
      * profile - Name of $ulc pseudo-variable profile that stores fetched
        contacts. It is a static string.
7a67411c
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
4480f807
    Example 1.28. registered usage
7a67411c
 ...
 reg_free_contacts("callee");
 ...
 
e45ac57e
 5. Exported Statistics
 
    5.1. max_expires
    5.2. max_contacts
    5.3. defaults_expires
    5.4. accepted_regs
    5.5. rejected_regs
1061d103
 
e45ac57e
 5.1. max_expires
1061d103
 
    Value of max_expires parameter.
 
e45ac57e
 5.2. max_contacts
1061d103
 
    The value of max_contacts parameter.
 
e45ac57e
 5.3. defaults_expires
1061d103
 
    The value of default_expires parameter.
 
e45ac57e
 5.4. accepted_regs
1061d103
 
    Number of accepted registrations.
 
e45ac57e
 5.5. rejected_regs
1061d103
 
    Number of rejected registrations.
31ccf6a2
 
e45ac57e
 6. Exported pseudo-variables
7a67411c
 
e45ac57e
    6.1. $ulc(profile=>attr)
7a67411c
 
e45ac57e
 6.1. $ulc(profile=>attr)
 
    Access the attributes of contact addresses stored in 'profile'. It must
8b2457cf
    be used after a call of “reg_fetch_contacts()”.
7a67411c
 
8b2457cf
    The “profile” has to be one of the values used with
    “reg_fetch_contacts()”.
7a67411c
 
8b2457cf
    The “attr” can be:
7a67411c
      * aor - address of record
      * domain - use location domain name
      * aorhash - hash id for the record
      * count - number of contacts
      * addr - contact address
      * path - path vector
      * received - received address
      * expires - expires value
      * callid - call-id header value
      * q - the q value
      * flags - flags value
      * cflags - cflags value
      * user_agent - user agent
      * socket - local socket
      * modified - last modified time
      * methods - methods value
 
e45ac57e
    The pseudo-variable accepts positive index value to access a specific
    contact record.
7a67411c
 
4480f807
    Example 1.29. $ulc(name) usage
7a67411c
 ...
 if(reg_fetch_contacts("location", "$fu", "caller"))
 {
740c1bbd
   xlog("caller=>aor: $(ulc(caller=>aor))\n");
   xlog("caller=>domain: $(ulc(caller=>domain))\n");
   xlog("caller=>aorhash $(ulc(caller=>aorhash))\n");
   xlog("caller=>count $(ulc(caller=>count))\n");
   $var(i) = 0;
   while($var(i) < $(ulc(caller=>count)))
   {
     xlog("--- contact [$var(i)]\n");
     xlog("caller=>addr:       $(ulc(caller=>addr)[$var(i)])\n");
     xlog("caller=>path:       $(ulc(caller=>path)[$var(i)])\n");
     xlog("caller=>received:   $(ulc(caller=>received)[$var(i)])\n");
     xlog("caller=>expires:    $(ulc(caller=>expires)[$var(i)])\n");
     xlog("caller=>callid:     $(ulc(caller=>callid)[$var(i)])\n");
     xlog("caller=>q:          $(ulc(caller=>q)[$var(i)])\n");
     xlog("caller=>cseq:       $(ulc(caller=>cseq)[$var(i)])\n");
     xlog("caller=>flags:      $(ulc(caller=>flags)[$var(i)])\n");
     xlog("caller=>cflags:     $(ulc(caller=>cflags)[$var(i)])\n");
     xlog("caller=>user_agent: $(ulc(caller=>user_agent)[$var(i)])\n");
     xlog("caller=>socket:     $(ulc(caller=>socket)[$var(i)])\n");
     xlog("caller=>modified:   $(ulc(caller=>modified)[$var(i)])\n");
     xlog("caller=>methods:    $(ulc(caller=>methods)[$var(i)])\n");
     $var(i) = $var(i) + 1;
   }
7a67411c
 }
 ...
 
033b5989
 Chapter 2. Frequently Asked Questions
31ccf6a2
 
8b2457cf
    2.1. What happend with the old “nat_flag” module parameter?
    2.2. What happend with the old “use_domain” module parameter?
    2.3. What happend with the old “save_noreply” and “save_memory”
e45ac57e
           functions?
 
    2.4. Where can I find more about Kamailio?
    2.5. Where can I post a question about this module?
    2.6. How can I report a bug?
    2.7. What happened to the desc_time_order parameter?
 
d77df08a
    2.1.
 
8b2457cf
    What happend with the old “nat_flag” module parameter?
f565de5a
 
8b2457cf
    In was removed, as the module internally loads this value from the
    “USRLOC” module (see the “nat_bflag” USRLOC parameter).
d77df08a
 
    2.2.
 
8b2457cf
    What happend with the old “use_domain” module parameter?
f565de5a
 
8b2457cf
    In was removed, as the module internally loads this option from the
    “USRLOC” module. This was done in order to simplify the configuration.
bf3705d3
 
d77df08a
    2.3.
4c5fb67e
 
8b2457cf
    What happend with the old “save_noreply” and “save_memory” functions?
f565de5a
 
8b2457cf
    There functions were merged into the new “save(domain,flags)”
    functions. If a reply should be sent or if the DB should be updated
    also is controlled via the flags.
bf3705d3
 
d77df08a
    2.4.
bf3705d3
 
8b2457cf
    Where can I find more about Kamailio?
f565de5a
 
8b2457cf
    Take a look at http://www.kamailio.org/.
31ccf6a2
 
d77df08a
    2.5.
31ccf6a2
 
8b2457cf
    Where can I post a question about this module?
f565de5a
 
8b2457cf
    First at all check if your question was already answered on one of our
    mailing lists:
      * User Mailing List -
        http://lists.kamailio.org/cgi-bin/mailman/listinfo/users
      * Developer Mailing List -
        http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel
31ccf6a2
 
8b2457cf
    E-mails regarding any stable Kamailio release should be sent to
    <users@lists.kamailio.org> and e-mails regarding development versions
    should be sent to <devel@lists.kamailio.org>.
989206bd
 
8b2457cf
    If you want to keep the mail private, send it to
    <team@lists.kamailio.org>.
31ccf6a2
 
d77df08a
    2.6.
31ccf6a2
 
8b2457cf
    How can I report a bug?
f565de5a
 
8b2457cf
    Please follow the guidelines provided at:
    http://sourceforge.net/tracker/?group_id=139143.
31ccf6a2
 
d77df08a
    2.7.
1c8ce5f4
 
8b2457cf
    What happened to the desc_time_order parameter?
1c8ce5f4
 
8b2457cf
    It was removed, as its functionality was mmigrate into usrloc module,
    were there is a parameter with the same name.