<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section id="rergistrar.overview">
	<title>Overview</title>
	<para>The module contains REGISTER processing logic. The actual location
		database is managed by the USRLOC module.
	</para>
	<section>
		<title>PATH support</title>
		<para>
		The Register module includes Path support (according to RFC 3327)
		for usage in registrars and home-proxies.
		</para>
		<para>
		If path support is enabled in the registrar module, a call to save(...)
		stores 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 header fields:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>off</emphasis> - stores the value of the
				Path headers into usrloc without passing it back to
				the UAC in the reply.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>lazy</emphasis> - stores the Path header and
				passes it back to the UAC if Path-support is indicated
				by the <quote>path</quote> param in the Supported header field.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>strict</emphasis> - rejects the registration
				with <quote>420 Bad Extension</quote> if 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.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		A call to lookup(...) always uses the path header if
		found, and inserts it as Route header field either in front of
		the first Route header field, or after the last Via header field 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).
		</para>
		<para>
		The whole process is transparent to the user, so no
		config changes are required beside setting the
		registrar-parameters <quote>use_path</quote> and
		<quote>path_mode</quote>.
		</para>
	</section>
	<section>
		<title>GRUU Support</title>
		<para>
			GRUU (RFC5627) is supported with both public and temporary
			addresses.
		</para>
		<para>
			The public GRUU is built based on the '+sip.instance'
			UUID parameter as recommended by RFC.
		</para>
		<para>
			The temporary GRUU is built based on internal SRUID (unique
			id generator) and it is kept the same for the duration of
			contact validity.
		</para>
	</section>

	</section>


	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>usrloc - User Location Module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>sl - Stateless Replies</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before
		running &kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="registrar.p.default_expires">
		<title><varname>default_expires</varname> (integer)</title>
		<para>
		If the processed message contains neither Expires
		header fields nor expires contact parameters, this value
		will be used for newly created usrloc records. The parameter contains
		number of second to expire (for example use 3600 for one hour). If it
		is set to a lower value than the <quote>min_expires</quote> parameter
		then it will be ignored. This parameter can be modified via ser config framework.
		A random value in a specific interval can be selected by using the default_expires_range
		parameter
		</para>
		<para>
		<emphasis>
			Default value is 3600.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "default_expires", 1800)
...
</programlisting>
		</example>
	</section>
	<section id="registrar.p.default_expires_range">
		<title><varname>default_expires_range</varname> (integer)</title>
		<para>
		This parameter specifies that the expiry used for newly created usrloc records
		are not fixed, but a random value in the interval <quote>[default_expires-default_expires_range%, default_expires]</quote>.
		The value is between 0 and 100 and represent the maximum percentage from expires that
		will be subtracted when computing the value. Default is 0, meaning default_expires
		is left unmodified. This parameter can be modified via the &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_expires_range</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "default_expires_range", 30) # +- 30% from default_expires
...
</programlisting>
		</example>
	</section>
	<section id="registrar.p.expires_range">
		<title><varname>expires_range</varname> (integer)</title>
		<para>
		Similar to default_expires_range, but it applies to the incoming expires
		value. Default in 0, meaning the expires is left unmodified.
		This parameter can be modified via the &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>expires_range</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expires]
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.min_expires">
		<title><varname>min_expires</varname> (integer)</title>
		<para>
		The minimum expires value of a <quote>Contact</quote>. Values lower than this
		minimum will be either set to the minimum or 423 response is sent back.
		Value 0 disables the checking. This parameter can be modified via the
		&kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 60.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>min_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "min_expires", 60)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.min_expires_mode">
		<title><varname>min_expires_mode</varname> (integer)</title>
		<para>
		Control what to do when expires value in REGISTER request is lower than
		min_expires parameter. If set to 0, expires is set to min_expires. If
		set to 1, then 423 Interval Too Brief is sent back.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>min_expires_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "min_expires_mode", 1)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.max_expires">
		<title><varname>max_expires</varname> (integer)</title>
		<para>
		The maximum accepted expires value of a <quote>Contact</quote>, values higher than this
		maximum will be automatically set to the maximum. Value 0 disables
		the checking. This parameter can be modified via the &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "max_expires", 120)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.default_q">
		<title><varname>default_q</varname> (integer)</title>
		<para>
		The parameter represents default <quote>q</quote> 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 want
		default_q to be 0.38, use value 380 here. This parameter can be modified via
		the &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_q</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "default_q", 1000)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.realm_prefix">
		<title><varname>realm_prefix</varname> (string)</title>
		<para>
		 Prefix to be automatically stripped 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 will be equivalent to mydomain.net. This parameter
		 can be modified via the &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is NULL (none).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>realm_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "realm_prefix", "sip.")
...
</programlisting>
		</example>
	</section>


	<section>
		<title><varname>append_branches</varname> (integer)</title>
		<para>
		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.  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 contact and the rest will be left unprocessed.
		This parameter can be modified via &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>append_branches</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "append_branches", 0)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.aor_avp">
		<title><varname>aor_avp</varname> (str)</title>
		<para>
		This module parameter has been removed. Use the 'uri' parameter from
		functions (e.g., save, lookup, registered).
		</para>
	</section>

	<section id="registrar.p.case_sensitive">
		<title><varname>case_sensitive</varname> (integer)</title>
		<para>
		If set to 1 then <acronym>AOR</acronym> comparison and also
		storing will be case sensitive, if set to 0 then <acronym>AOR</acronym>
		comparison and storing will be case insensitive. This is recommended.
		This parameter can be modified via &kamailio; config framework.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>case_sensitive</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "case_sensitive", 1)
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.received_avp">
		<title><varname>received_avp</varname> (str)</title>
		<para>
		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 transport protocol of the REGISTER message being processed.
		</para>
		<note>
		<para>
			The value of this parameter should be the same as the value of
			corresponding parameter of nathelper module.
		</para>
		</note>
		<para>
		<emphasis>
			Default value is "NULL" (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>received_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "received_avp", "$avp(s:rcv)")
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.received_param">
		<title><varname>received_param</varname> (string)</title>
		<para>
		The name of the parameter that will be appended to Contact URI's of
		200 OK when the received URI was set by the <quote>nathelper</quote> module. If the
		value is an empty string, then the parameter is not appended anymore.
		</para>
		<para>
		<emphasis>
			Default value is "received".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>received_param</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "received_param", "rcv")
...
</programlisting>
		</example>
	</section>

	<section id="registrar.p.max_contacts">
		<title><varname>max_contacts</varname> (integer)</title>
		<para>
		The parameter can be used to limit the number of contacts per
		AOR (Address of Record) in the user location database.
		If the maximum number of contacts is exceeded, &kamailio; will not
		accept the registration and send an error response.
		Value 0 disables the check. This parameter can be modified via
		the &kamailio; config framework.
		(Please also check the flag for <function>save()</function> if you only want
		only one active registration).
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_contacts</varname> parameter</title>
		<programlisting format="linespecific">
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.retry_after">
		<title><varname>retry_after</varname> (integer)</title>
		<para>
		The registrar can generate a 5xx reply to REGISTER requests in various
		situations. It can, for example, happen when the
		<varname>max_contacts</varname> parameter is set and the
		processing of REGISTER request would exceed the limit. In this case
		the registrar would generate "503 Service Unavailable" response.
		This parameter can be modified via the &kamailio; config framework.
		</para>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>retry_after</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "retry_after", 30)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.sock_flag">
		<title><varname>sock_flag</varname> (integer)</title>
		<para>
		Message flag to signal to the registrar module to look into REGISTER
		request for a header which contains a socket description (IP:port).
		This socket info will be stored by registrar instead of the received
		socket info.
		</para>
		<para>
		This makes sense only in multiple replicated servers scenarios.
		</para>
		<para>
		<emphasis>
			Default value is -1 (no flag).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sock_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "sock_flag", 18)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.sock_hdr_name">
		<title><varname>sock_hdr_name</varname> (string)</title>
		<para>
		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.
		</para>
		<para>
		This makes sense only in multiple replicated servers scenarios.
		</para>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sock_hdr_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.sock_mode">
		<title><varname>sock_mode</varname> (integer)</title>
		<para>
		If set to 1, the server stores the advertised address in socket field,
		instead of bind address.
		</para>
		<para>
		This could be useful when kamailio is installed behind NAT and it is
		necessary to store its public IP instead socket on which the register
		request was received.
		</para>
		<para>
		<emphasis>
			Default value is 0 (store bind address).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sock_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "sock_mode", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.method_filtering">
		<title><varname>method_filtering</varname> (integer)</title>
		<para>
		Tells if the contact filtering based on supported methods should be
		performed during lookup on initial requests without to-tag.
        It's enabled only if it has a non zero
		value. Supported methods are listed in the <quote>Allow:</quote>
		header in the REGISTER message and stored in the location database.
		</para>
		<para>
		<emphasis>
			Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>method_filtering</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "method_filtering", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.use_path">
		<title><varname>use_path</varname> (integer)</title>
		<para>
		If set to 1, the <quote>Path:</quote> header is handled according to the parameter
		This parameter can be modified via &kamailio; config framework.
		<quote>path_mode</quote>.
		</para>
		<para>
		<emphasis>
			Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_path</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "use_path", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.path_mode">
		<title><varname>path_mode</varname> (integer)</title>
		<para>
		The registrar module implements three different modes regarding the
		response to a registration which includes one or more Path headers:
		</para>
		<itemizedlist>
		<listitem>
			<para>
			0 - The Path header is saved into usrloc, but is not included in
			the reply.
			</para>
		</listitem>
		<listitem>
			<para>
			1 - The Path header is saved into usrloc, but is only included in
			the reply if path support is indicated in the registration request
			by the <quote>path</quote> option in the
			<quote>Supported:</quote> header.
			</para>
		</listitem>
		<listitem>
			<para>
			2 - The path header is only saved into usrloc, if path support is
			indicated in the registration request by the <quote>path</quote>
			option of the <quote>Supported</quote> header. If no path support
			is indicated, the request is rejected with
			<quote>420 - Bad Extension</quote> and the header
			<quote>Unsupported: path</quote> is included in the reply along
			with the received <quote>Path</quote> header. This mode is the
			one recommended by RFC-3327.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is 2.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>path_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "path_mode", 0)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.path_use_received">
		<title><varname>path_use_received</varname> (integer)</title>
		<para>
		If set to 1, the <quote>received</quote> parameter of the first Path
		URI of a 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 loadbalancer, which passes the nat'ed UAC address as
		<quote>received</quote> parameter
		in it's Path uri.
		</para>
		<para>
		<emphasis>
			Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>path_use_received</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "path_use_received", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.path_check_local">
		<title><varname>path_check_local</varname> (integer)</title>
		<para>
		If set to 1, when performing a lookup the Path (if present) is evaluated
		and if the first hop is local (according to <quote>myself</quote> test), we
		skip it	to avoid unnecessary looping.
		</para>
		<para>
		This is useful if multiple servers are sharing a common location database,
		each saving contacts with their local address as the Path.
		</para>
		<para>
		<emphasis>
		Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>path_check_local</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "path_check_local", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.reg_callid_avp">
		<title><varname>reg_callid_avp</varname> (string)</title>
		<para>
			<emphasis>
				obsolete. use match_option in registered function
			</emphasis>
		</para>
		<para>
		If reg_callid_avp is defined and populated when the
		<function>registered()</function> is invoked, the result is
		TRUE only if an active registration with
		the specified callID is found.
		</para>
		<para>
		<emphasis>
			Default value is NULL (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>reg_callid_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.xavp_cfg">
		<title><varname>xavp_cfg</varname> (string)</title>
		<para>
			Defines the name of XAVP class to store runtime module config
			values. The values are stored as inner XAVPs, like
			$xavp(class=&gt;attribute). Valid inner XAVP names:
		</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>match_callid</emphasis> - filter contacts by callid.
				Used in registered().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>match_contact</emphasis> - filter contacts by contact.
				Used in registered().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>match_received</emphasis> - filter contacts by received.
				Used in registered().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>rlf_bflags</emphasis> - filter contacts by branch flags.
				Used in lookup().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>q</emphasis> - q value of contact
				(integer 0-1000). It overrides q value given in
				contact header and default_q parameter.
				Used in save().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>expires</emphasis> - the expires value, to overwrite the
				value from SIP headers.
				Used in save().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>max_contacts</emphasis> - the number of maximum
				contacts to be stored for the current registration AoR. It
				overwrites the 'max_contacts' module parameter value.
				Used in save().
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>socket</emphasis> - the string representing the
				socket on which the register request was received, as alternative
				to using the sock_hdr.
				Used in save().
			</para>
		</listitem>
		</itemizedlist>
		<para>
			For example. if this parameter is set to 'reg', then the number
			of maximum contacts can be set in $xavp(reg=&gt;max_contacts).
		</para>
		<para>
		<emphasis>
			Default value is NULL (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xavp_cfg</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "xavp_cfg", "reg")
...
request_route {
    ...
    $xavp(reg=&gt;max_contacts) = 4;
    $xavp(reg[0]=&gt;expires) = 600;
    save("location");
    ...
}
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.xavp_rcd">
		<title><varname>xavp_rcd</varname> (string)</title>
		<para>
			Defines the name of XAVP class to store details from the
			location records. The values are stored as inner XAVPs, like
			$xavp(class[0]=&gt;attribute). Valid inner XAVP names:
		</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>ruid</emphasis> - the record's internal unique
				id.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>contact</emphasis> - the record's contact value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>expires</emphasis> - the record's expires value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>received</emphasis> - the record's received value.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>path</emphasis> - the record's path value.
			</para>
		</listitem>
		</itemizedlist>
		<para>
			For example. if this parameter is set to 'ulrcd', then values are set in:
		</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>$xavp(ulrcd[0]=&gt;ruid)</emphasis></para>
		</listitem>
		<listitem>
			<para><emphasis>$xavp(ulrcd[0]=&gt;contact)</emphasis></para>
		</listitem>
		<listitem>
			<para><emphasis>$xavp(ulrcd[0]=&gt;received)</emphasis></para>
		</listitem>
		<listitem>
			<para><emphasis>$xavp(ulrcd[0]=&gt;path)</emphasis></para>
		</listitem>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is NULL (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xavp_rcd</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "xavp_rcd", "ulrcd")
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.xavp_rcd_mask">
		<title><varname>xavp_rcd_mask</varname> (int)</title>
		<para>
			Defines what values to skip when xavp_rcd is stored.
		</para>
		<itemizedlist>
		<listitem><para>1 - <emphasis>ruid</emphasis></para></listitem>
		<listitem><para>2 - <emphasis>contact</emphasis></para></listitem>
		<listitem><para>4 - <emphasis>expires</emphasis></para></listitem>
		<listitem><para>8 - <emphasis>received</emphasis></para></listitem>
		<listitem><para>16 - <emphasis>path</emphasis></para></listitem>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is 0 (none).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xavp_rcd_mask</varname> parameter</title>
		<programlisting format="linespecific">
...
# skip path value
modparam("registrar", "xavp_rcd_mask", 16)
...
# skip path and expires values
modparam("registrar", "xavp_rcd_mask", 20)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.gruu_enabled">
		<title><varname>gruu_enabled</varname> (integer)</title>
		<para>
		If set to 1 and the <quote>+sip.instance</quote> parameter to
		Contact header of REGISTER is present, then the value of the
		parameter is saved to location and pub-gruu and temp-gruu addresses
		are generated.
		</para>
		<para>
		Set it to 0 if you want to ignore GRUU extensions in REGISTER.
		</para>
		<para>
		<emphasis>
			Default value is 1 (enabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>gruu_enabled</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "gruu_enabled", 0)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.outbound_mode">
		<title><varname>outbound_mode</varname> (integer)</title>
		<para>
		If set to 0 this module will accept REGISTER requests that do
		not contain a <quote>Supported:</quote> header with the outbound options-tag.
		The 200 OK response to REGISTER requests that this module
		generates will not contain <quote>Require:</quote> or
		<quote>Supported:</quote> headers with
		the outbound options-tag. If the client has a <quote>Require:</quote> header
		with the outbound options tag the REGISTER will be rejected
		with a <quote>420 Bad Extension</quote> response.
		</para>
		<para>
		If set to 1 this module will accept REGISTER requests that
		do not contain a <quote>Supported:</quote> header with the outbound
		options-tag and REGISTER requests that do contain a Supported:
		or Requires: header with the outbound options-tag. When the
		client supports <emphasis>outbound</emphasis> the appropriate
		RFC5626 procedures will be followed.
		</para>
		<para>
		If set to 2 this module will reject REGISTER requests that
		do not contain a <quote>Supported:</quote> header with the outbound
		options-tag. When the client supports outbound the appropriate
		RFC5626 procedures will be followed.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>outbound_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "outbound_mode", 2)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.regid_mode">
		<title><varname>regid_mode</varname> (integer)</title>
		<para>
		If set to 0 this module will ignore the <quote>regid</quote> contact param
		when saving REGISTER request if the request does not
		indicate support for outbound.
		</para>
		<para>
		If set to 1 this module will use <quote>regid</quote> contact param
		(if present) when saving REGISTER request even if
		REGISTER request does not indicate support for outbound.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>regid_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "regid_mode", 1)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.flow_timer">
		<title><varname>flow_timer</varname> (integer)</title>
		<para>
		If set to 0 then this module will not add a <quote>Flow-Timer:</quote> header
		to 200 OK responses to REGISTER requests.
		</para>
		<para>
		If set to > 0 then this module will add a <quote>Flow-Timer:</quote> header
		containing this value to 200 OK responses to REGISTER requests.
		This parameter may only be set to a value > 0 when
		<emphasis>outbound_mode</emphasis> is set to 1 or 2.
		</para>
		<para>
		When set to a value greater than 0 this parameter should be set to slightly
		less than the connection timeout value between the UAC and the
		network (this corresponds to the core
		<emphasis>tcp_connection_lifetime</emphasis> option and
		<emphasis>websocket</emphasis>
		<emphasis>keepalive_timeout</emphasis> modparam). This
		parameter is most useful when you have a single edge
		proxy/registrar or if you have an edge proxy that cannot modify
		responses. If you are using a separate edge proxy you should
		consider leaving this parameter set to 0 and adding the
		<quote>Flow-Timer:</quote> header on the edge proxy as this allows you to
		keep all of the timer values for a specific flow in one
		configuration.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>flow_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "flow_timer", 25)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.contact_max_size">
		<title><varname>contact_max_size</varname> (integer)</title>
		<para>
		Max size of URIs in <quote>Contact:</quote> header.
		</para>
		<para>
		The size of URIs in <quote>Contact:</quote> headers are checked to be
		lower or equal to this value.
		A warning is logged and a 400 Bad Request is sent in response to REGISTER
		requests with contact URIs that are longer than this value.
		</para>
		<para>
		If a database is used then you must make sure that your database model supports
		strings of the configured size in the column <quote>contact</quote> of the table
		specified in <quote>save()</quote> function.
		</para>
		<para>
		<emphasis>
			Default value is 512.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>contact_max_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "contact_max_size", 1024)
...
		</programlisting>
		</example>
	</section>

	<section id="registrar.p.event_callback">
		<title><varname>event_callback</varname> (str)</title>
		<para>
			The name of the function in the KEMI configuration file (embedded
			scripting language such as Lua, Python, ...) to be executed instead
			of event_route[...] blocks.
		</para>
		<para>
			The function receives a string parameter with the name of the event.
            The only possible value currently is 'usrloc:contact-expired'.
		</para>
		<para>
		<emphasis>
			Default value is 'empty' (no function is executed for events).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>event_callback</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "event_callback", "ksr_registrar_event")
...
-- event callback function implemented in Lua
function ksr_registrar_event(evname)
    KSR.info( "Expired contact for " .. KSR.pv.getw("$ulc(exp=>aor)") .. "\n");
	return 1;
end
...
        </programlisting>
		</example>
	</section>
	<section id="registrar.p.lookup_filter_mode">
		<title><varname>lookup_filter_mode</varname> (int)</title>
		<para>
			Control what filters should be applied to lookup(...) operations.
			It can be a combination (sum) of the next values:
		</para>
		<itemizedlist>
		<listitem>
			<para>
				<emphasis>1</emphasis> - apply the branch flags filter - return
				only contact records with branch flags matching at least one set
				inside xavp specified by xavp_cfg parameter with inner name
				rlf_bflags - e.g., $xavp(reg=&gt;rlf_bflags).
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>2</emphasis> - apply the active tcp connection filter
				- return only contact records that have the associated TCP/TLS/WSS
				connection active. UDP and SCTP contacts are not filtered, all
				are returned.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is NULL (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>xavp_cfg</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "xavp_cfg", "reg")
modparam("registrar", "lookup_filter_mode", 1)
...
request_route {
    ...
    $xavp(reg=&gt;rlf_bflags) = 8;
    if(lookup("location")) { ... }
    ...
}
...
		</programlisting>
		</example>
	</section>


	<section id="registrar.p.use_expired_contacts">
		<title><varname>use_expired_contacts</varname> (int)</title>

		<para>
			Allow/Disallow the usage of the expired contacts.
		</para>

		<itemizedlist>
		<listitem>
			<para>
				<emphasis>0</emphasis> Disallow the usage of the expired contacts.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>1</emphasis> Allow the usage of the expired contacts.
			</para>
		</listitem>
		</itemizedlist>

		<para>
		<emphasis>
			Default value is 0 (Disallow).
		</emphasis>
		</para>

		<example>
		<title>Set <varname>use_expired_contacts</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "use_expired_contacts", 1)
...

kamcmd cfg.set_now_int registrar use_expired_contacts 1
kamcmd cfg.set_now_int registrar use_expired_contacts 0
		</programlisting>
		</example>
	</section>
	</section>


	<section>
	<title>Functions</title>
	<section id="registrar.f.save">
		<title>
		<function moreinfo="none">save(domain, [, flags [, uri]])</function>
		</title>
		<para>
		The function processes a <emphasis>REGISTER</emphasis> message. It can add, remove or
		modify location records (in usrloc) depending on Contact and Expires header fields in the
		REGISTER message. On success and when called from the REQUEST_ROUTE,
		<quote>200 OK</quote> will be returned listing all contacts that are currently in
		the location database. As a side effect, also branch flags are
        stored in usrloc. On an error, an error message will be sent 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 the registrar.
			If a database is used then this must be name of the table which
			stores the contacts.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>flags</emphasis> (optional) - the value may be a bitwise
			OR of the following flags:
			</para>
			<itemizedlist>
				<listitem>
					<para><emphasis>0x01</emphasis> - save the contacts only
					in memory cache with no DB operation;
					</para>
				</listitem>
				<listitem>
					<para><emphasis>0x02</emphasis> - do not generate a SIP
						reply to the current REGISTER request. When used in
						ONREPLY_ROUTE, this parameter is obsolete.</para>
				</listitem>
				<listitem>
					<para><emphasis>0x04</emphasis> - 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).</para>
				</listitem>
				<listitem>
					<para><emphasis>0x08</emphasis> - Do not apply
					<emphasis>expires_range</emphasis> or
					<emphasis>default_expires_range</emphasis> to this
					registration.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>0x10</emphasis> - prepare the headers for
					reply, used only if flag 0x02 is set.
					</para>
				</listitem>
			</itemizedlist>
			<para>The flags may be given in decimal or hexadecimal format.</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> (optional - flags param has to be set and
			can be 0 for default behavior) - SIP URI to do be used instead of To
			header URI. It can be a dynamic string with pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>Return codes:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>-2</emphasis> - error, too many contacts for AOR.
			</para>
			<para>
			<emphasis>-1</emphasis> - error.
			</para>
			<para>
			<emphasis>1</emphasis> - contacts inserted.
			</para>
			<para>
			<emphasis>2</emphasis> - contacts updated.
			</para>
			<para>
			<emphasis>3</emphasis> - contacts deleted.
			</para>
			<para>
			<emphasis>4</emphasis> - contacts returned.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and REPLY_ROUTE.
		</para>
		<example>
		<title><function>save</function> usage</title>
		<programlisting format="linespecific">
...
save("location");
save("location", "0x01");
save("location", "0x00", "sip:test@kamailio.org");
...
</programlisting>
		</example>
	</section>

	<section id="registrar.f.lookup">
		<title>
		<function moreinfo="none">lookup(domain [, uri])</function>
		</title>
		<para>
		The lookup function extracts username and/or domain 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).
        As a side effect, also branch flags are restored from usrloc.
		</para>
		<para>
		If the <varname>method_filtering</varname> option is enabled and
        request is initial request without to-tag, the
        <function>lookup</function> function
		will return only the contacts that support the method of the
		processed request.
		</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>
		<listitem>
			<para>
			<emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
			of R-URI. It can be a dynamic string with pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>Return codes:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>1</emphasis> - contacts found and returned.
			</para>
			<para>
			<emphasis>-1</emphasis> - no contact found.
			</para>
			<para>
			<emphasis>-2</emphasis> - contacts found, but method not supported.
			</para>
			<para>
			<emphasis>-3</emphasis> - internal error during processing.
			</para>
		</listitem>
		</itemizedlist>

		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>lookup</function> usage</title>
		<programlisting format="linespecific">
...
lookup("location");
			switch ($retcode) {:1

    case -1:
    case -3:
        sl_send_reply("404", "Not Found");
        exit;
    case -2:
        sl_send_reply("405", "Not Found");
        exit;
};
...
</programlisting>
		</example>
	</section>

	<section id="registrar.f.lookup_to_dset">
		<title>
		<function moreinfo="none">lookup_to_dset(domain [, uri])</function>
		</title>
		<para>
			Similar to lookup(...), but push the location contacts to destination
			set, without changing the R-URI (first branch not changed, it creates
			additional branches). For the meaning of the parameters and the return
			codes, see the documentation for lookup(...) function.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>lookup_to_dset</function> usage</title>
		<programlisting format="linespecific">
...
lookup_to_dset("location");
...
</programlisting>
		</example>
	</section>

	<section id="registrar.f.lookup_branches">
		<title>
		<function moreinfo="none">lookup_branches(domain)</function>
		</title>
		<para>
		The function performs lookup(domain) on r-uri and additional
		branches (only branches that have no other attributes set than uri).
		</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>
		<para>Return codes are propagated from the <function>lookup(domain)</function> function.
		</para>

		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>lookup_branches</function> usage</title>
		<programlisting format="linespecific">
...
lookup_branches("location");
...
</programlisting>
		</example>
	</section>

	<section id="registrar.f.lookup_xavp">
		<title>
		<function moreinfo="none">lookup_xavp(ultable, uri, rxname, cxname)</function>
		</title>
		<para>
			Similar to lookup(...), but store the location record attributes
			in XAVPs. Note that not all contact record fields are stored
		</para>
		<para>Meaning of the parameters:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>ultable</emphasis> - name of the usrloc table that is used
			for the lookup.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> - the URI to be searched in location table.
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis>rxname</emphasis> - name of the XAVP to store record
				attributes. These are:
			</para>
			<itemizedlist>
			<listitem>
				<para>
				<emphasis>aor</emphasis> - the address of record.
				</para>
			</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para>
				<emphasis>cxname</emphasis> - name of the XAVP to store content
				attributes, name mapping is done from the perspective of using
				them to send out SIP requests. These are:
			</para>
			<itemizedlist>
			<listitem>
				<para>
				<emphasis>uri</emphasis> - the contact address.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>socket</emphasis> - the socket of the contact record.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>dsturi</emphasis> - the destination uri of the contact
				record (the received field in location contact).
				</para>
			</listitem>
			</itemizedlist>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>lookup_xavp</function> usage</title>
		<programlisting format="linespecific">
...
lookup_xavp("location", "$fu", "rul", "cul");
xinfo("aor: $xavp(rul=&gt;aor)\n");
xinfo("number of contacts: $xavp(rul&gt;count)\n");
xinfo("first contact record - uri: $xavp(cul&gt;uri)\n");
xinfo("first contact record - socket: $xavp(cul&gt;socket)\n");
...
</programlisting>
		</example>
	</section>

	<section id="registrar.f.registered">
		<title>
		<function moreinfo="none">registered(domain [, uri [, match_option [, match_action]]])</function>
		</title>
		<para>
		The function returns true if the AOR in the URI is
		registered, false otherwise.  The function does not modify the
		message being processed, it neither rewrites the Request-URI if a
		contact is found nor append branches. If uri parameter is not
		provided, then it considered to be the Request-URI for SIP requests
		and To-URI for SIP replies.
		</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>
		<listitem>
			<para>
			<emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
			of Request/To-URI. It can be a dynamic string with pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>match_option</emphasis> (optional) - flag parameter to restrict
			contact search. use xavp_cfg to set the values to compare to.
			</para>
            <para>flag values is as follows:</para>
			<itemizedlist>
				<listitem>
					<para>1 - match_callid</para>
				</listitem>
				<listitem>
					<para>2 - match_received</para>
				</listitem>
				<listitem>
					<para>4 - match_contact</para>
				</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para>
			<emphasis>match_action</emphasis> (optional) - actions to perform when match is positive.
			</para>
            <para>flag values is as follows:</para>
			<itemizedlist>
				<listitem>
					<para>1 - restore the xavps associated with the matched contact</para>
				</listitem>
				<listitem>
					<para>2 - skip adding the matched location record attributes to xavp_rcd
					(e.g., the ruid, contact, received, ...)</para>
				</listitem>
			</itemizedlist>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>registered</function> usage</title>
		<programlisting format="linespecific">
...
if (registered("location")) {
	sl_send_reply("100", "Trying");
	...
};
...
$xavp(regcfg=>match_received) = $su;
if (registered("location","$rz:$Au", 2)) {
	sl_send_reply("100", "Trying");
	...
};
...

</programlisting>
		</example>
	</section>

	<section id="registrar.f.add_sock_hdr">
		<title>
		<function moreinfo="none">add_sock_hdr(hdr_name)</function>
		</title>
		<para>
		Adds a new header to the current REGISTER request with
		<quote>hdr_name</quote> which contains the description of the
		received socket (proto:ip:port)
		</para>
		<para>
		This makes sense only in multiple replicated servers scenarios.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>hdr_name</emphasis> - header name to be used, it can be
			a static string or contain variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>add_sock_hdr</function> usage</title>
		<programlisting format="linespecific">
...
add_sock_hdr("Sock-Info");
...
</programlisting>
		</example>
	</section>
	<section id="registrar.f.unregister">
		<title>
		<function moreinfo="none">unregister(domain, uri[, ruid])</function>
		</title>
		<para>
		The function removes contacts associated with 'uri' from the location
		database. If 'ruid' is provided a specific contact is removed,
		if 'ruid' is not provided all the current contacts are removed.
		If 'ruid' is provided and the <quote>usrloc</quote> module is
		using <quote>db_mode=3</quote>, 'uri' does not need to be given and can be
		empty string.
		</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 or contact addresses.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> - The SIP URI address of the user
			which to remove the contact addresses for. It can contain
			pseudo-variables that are evaluated at runtime.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>ruid</emphasis> - The record unique ID for a
			specific contact to be removed. It can contain
			pseudo-variables that are evaluated at runtime.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<para>
		Return values:
		</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>0</emphasis> - Successfully deleted contact(s)
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>-1</emphasis> - Failed to extract or parse address of record from argument
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>-2</emphasis> - Error in unregistering user
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>-3</emphasis> - Contacts for AOR not found
			</para>
		</listitem>
		</itemizedlist>
		<example>
		<title><function>unregister</function> usage</title>
		<programlisting format="linespecific">
...
unregister("location", "$ru");
unregister("location", "sip:user@kamailio.org");
unregister("location", "$ru", "$ulc(caller=>ruid)");
unregister("location", "", "$ruid");
...
</programlisting>
		</example>
	</section>
	<section id="registrar.f.reg_fetch_contacts">
		<title>
		<function moreinfo="none">reg_fetch_contacts(domain, uri, profile)</function>
		</title>
		<para>
			The function fetches the contacts for 'uri' from table 'domain'
			to pseudo-variable $ulc(profile).
		</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 of contact addresses.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> - The SIP URI address of the user
			which to fetch the contact addresses for. It can contain
			pseudo-variables that are evaluated at runtime.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
			that will store the fetched contacts. It is a static string.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>reg_fetch_contacts</function> usage</title>
		<programlisting format="linespecific">
...
reg_fetch_contacts("location", "$ru", "callee");
reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
...
</programlisting>
		</example>
	</section>
	<section id="registrar.f.reg_free_contacts">
		<title>
		<function moreinfo="none">reg_free_contacts(profile)</function>
		</title>
		<para>
			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.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
			that stores fetched contacts. It is a static string.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>reg_free_contacts</function> usage</title>
		<programlisting format="linespecific">
...
reg_free_contacts("callee");
...
</programlisting>
		</example>
	</section>
	<section id="registrar.f.reg_send_reply">
		<title>
		<function moreinfo="none">reg_send_reply()</function>
		</title>
		<para>
			The function sends the SIP reply that is normally sent by
			save(...), but that was skipped due to flag 0x2. It must be used
			after save(..., "0x2"). Practically it allows saving registration
			to location table, do other operations and then send the reply.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>reg_send_reply</function> usage</title>
		<programlisting format="linespecific">
...
save("location", "0x2");
...
reg_send_reply();
...
</programlisting>
		</example>
	</section>
	<section id="registrar.f.reg_from_user">
		<title>
		<function moreinfo="none">reg_from_user(ultable, uri, mode)</function>
		</title>
		<para>
			The function returns true if the SIP message comes from the user
			identified by 'uri' parameter by matching the associated location
			records. The matching is done with the field 'received' if it is set,
			otherwise with the contact address.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>ultable</emphasis> - user location table (e.g., 'location')
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>uri</emphasis> - SIP URI to identify the location records
			to match against.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>mode</emphasis> - matching mode (int) - host part (IP address)
			is matched always. If mode has bit 1 set (value 1), then the port is
			matched as well. If mode has bit 2 set (value 2), then the protocol
			is matched as well.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>reg_from_user</function> usage</title>
		<programlisting format="linespecific">
...
if(reg_from_user("location", "sip:alice@server.com", "0")) {
    # message coming from where 'alice' sent before a REGISTER request
}
...
</programlisting>
		</example>
	</section>

	</section>

<section>
	<title>Event Routes</title>
	<section>
		<title><varname>event_route[usrloc:contact-expired]</varname></title>
		<para>
		Executed when a contact in location table has expired. The variable
		$ulc(exp=&gt;...) is filled with the attributes of the expired contact.
		</para>
		<example>
		<title><function>event_route[usrloc:contact-expired]</function> usage</title>
		<programlisting format="linespecific">
...
event_route[usrloc:contact-expired] {
    xlog("expired contact for $ulc(exp=>aor)\n");
}
...
</programlisting>
		</example>

	</section>
</section>

<section>
	<title>Statistics</title>
	<section>
		<title><varname>max_expires</varname></title>
		<para>
		Value of max_expires parameter.
		</para>
	</section>
	<section>
		<title><varname>max_contacts</varname></title>
		<para>
		The value of max_contacts parameter.
		</para>
	</section>
	<section>
		<title><varname>default_expires</varname></title>
		<para>
		The value of default_expires parameter.
		</para>
	</section>
	<section>
		<title><varname>accepted_regs</varname></title>
		<para>
		Number of accepted registrations.
		</para>
	</section>
	<section>
		<title><varname>rejected_regs</varname></title>
		<para>
		Number of rejected registrations.
		</para>
	</section>

</section>

	<section>
	<title>Pseudo Variables</title>

		<section>
			<title><varname>$ulc(profile=>attr)</varname></title>
			<para>
				Access the attributes of contact addresses stored in
				'profile'. It must be used after a call of
				<quote>reg_fetch_contacts()</quote>.
			</para>
			<para>
				The <quote>profile</quote> has to be one of the values used
				with <quote>reg_fetch_contacts()</quote>.
			</para>
			<para>
			The <quote>attr</quote> can be:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>aor</emphasis> - address of record
				</para>
				</listitem>
				<listitem>
				<para><emphasis>domain</emphasis> - used location domain/table name
				</para>
				</listitem>
				<listitem>
				<para><emphasis>aorhash</emphasis> - hash id for the record
				</para>
				</listitem>
				<listitem>
				<para><emphasis>addr</emphasis> - contact address
				</para>
				</listitem>
				<listitem>
				<para><emphasis>path</emphasis> - path vector
				</para>
				</listitem>
				<listitem>
				<para><emphasis>received</emphasis> - received address
				</para>
				</listitem>
				<listitem>
				<para><emphasis>expires</emphasis> - expires value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>callid</emphasis> - call-id header value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>q</emphasis> - the q value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>cseq</emphasis> - the cseq value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>flags</emphasis> - flags value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>cflags</emphasis> - cflags value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>user_agent</emphasis> - user agent
				</para>
				</listitem>
				<listitem>
				<para><emphasis>socket</emphasis> - local socket
				</para>
				</listitem>
				<listitem>
				<para><emphasis>modified</emphasis> - last modified time
				</para>
				</listitem>
				<listitem>
				<para><emphasis>methods</emphasis> - methods value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>count</emphasis> - number of contacts
				</para>
				</listitem>
				<listitem>
				<para><emphasis>ruid</emphasis> - record unique ID
				</para>
				</listitem>
				<listitem>
				<para><emphasis>regid</emphasis> - reg-id value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>instance</emphasis> - instance value
				</para>
				</listitem>
				<listitem>
				<para><emphasis>conid</emphasis> - TCP socket internal connection ID ($null if UDP)
				</para>
				</listitem>
				<listitem>
				<para><emphasis>server_id</emphasis> - server_id value
				</para>
				</listitem>
			</itemizedlist>
			<para>
				The pseudo-variable accepts positive index value to access
				a specific contact record.
			</para>

			<example>
			<title><function moreinfo="none">$ulc(name)</function> usage</title>
<programlisting format="linespecific">
...
if(reg_fetch_contacts("location", "$fu", "caller"))
{
  xlog("caller=&gt;aor: $(ulc(caller=&gt;aor))\n");
  xlog("caller=&gt;domain: $(ulc(caller=&gt;domain))\n");
  xlog("caller=&gt;aorhash $(ulc(caller=&gt;aorhash))\n");
  xlog("caller=&gt;count $(ulc(caller=&gt;count))\n");
  $var(i) = 0;
  while($var(i) &lt; $(ulc(caller=&gt;count)))
  {
    xlog("--- contact [$var(i)]\n");
    xlog("caller=&gt;addr:       $(ulc(caller=&gt;addr)[$var(i)])\n");
    xlog("caller=&gt;path:       $(ulc(caller=&gt;path)[$var(i)])\n");
    xlog("caller=&gt;received:   $(ulc(caller=&gt;received)[$var(i)])\n");
    xlog("caller=&gt;expires:    $(ulc(caller=&gt;expires)[$var(i)])\n");
    xlog("caller=&gt;callid:     $(ulc(caller=&gt;callid)[$var(i)])\n");
    xlog("caller=&gt;regid:      $(ulc(caller=&gt;regid)[$var(i)])\n");
    xlog("caller=&gt;q:          $(ulc(caller=&gt;q)[$var(i)])\n");
    xlog("caller=&gt;cseq:       $(ulc(caller=&gt;cseq)[$var(i)])\n");
    xlog("caller=&gt;flags:      $(ulc(caller=&gt;flags)[$var(i)])\n");
    xlog("caller=&gt;cflags:     $(ulc(caller=&gt;cflags)[$var(i)])\n");
    xlog("caller=&gt;user_agent: $(ulc(caller=&gt;user_agent)[$var(i)])\n");
    xlog("caller=&gt;socket:     $(ulc(caller=&gt;socket)[$var(i)])\n");
    xlog("caller=&gt;modified:   $(ulc(caller=&gt;modified)[$var(i)])\n");
    xlog("caller=&gt;methods:    $(ulc(caller=&gt;methods)[$var(i)])\n");
    $var(i) = $var(i) + 1;
  }
}
...
				 </programlisting>
			</example>
		</section>
	</section>

</chapter>

