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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		Domain module implements checks that based on domain table determine 
		if a host part of an <acronym>URI</acronym> is <quote>local</quote> or 
		not.  A <quote>local</quote> domain is one that the proxy is responsible 
		for.
	</para>
	<para>
		Domain module operates in caching or non-caching mode depending on 
		value of module parameter <parameter moreinfo="none">db_mode</parameter>.
		In caching mode domain module reads the contents of domain table into 
		cache memory when the module is loaded.  After that domain table is 
		re-read only when module is given domain_reload fifo command.  Any
		changes in domain table must thus be followed by 
		<quote>domain_reload</quote> command in order to reflect them in 
		module behavior. In non-caching mode domain module always queries domain
		table in the database.
	</para>
	<para>
		Caching is implemented using a hash table. The size of the hash table 
		is given by HASH_SIZE constant defined in domain_mod.h. 
		Its <quote>factory default</quote> value is 128.
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<para>
		The module depends on the following modules (in the other words the 
		listed modules must be loaded before this module):
		<itemizedlist>
		<listitem>
			<para><emphasis>database</emphasis> -- Any database module</para>
		</listitem>
		</itemizedlist>
	</para>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section>
		<title><varname>db_url</varname> (string)</title>
		<para>
		This is <acronym>URL</acronym> of the database to be used.
		</para>
		<para>
		Default value is 
			<quote>mysql://opensipsro:opensipsro@localhost/opensips</quote>
		</para>
		<example>
		<title>Setting db_url parameter</title>
		<programlisting format="linespecific">
modparam("domain", "db_url", "mysql://ser:pass@db_host/ser")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>db_mode</varname> (integer)</title>
		<para>
		Database mode: 0 means non-caching, 1 means caching.
		</para>
		<para>
		Default value is 0 (non-caching).
		</para>
		<example>
		<title>db_mode example</title>
		<programlisting format="linespecific">
modparam("domain", "db_mode", 1)   # Use caching
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>domain_table</varname> (string)</title>
		<para>
		Name of table containing names of local domains that the proxy is 
		responsible for. Local users must have in their sip uri a host part 
		that is equal to one of these domains.
		</para>
		<para>
		Default value is <quote>domain</quote>.
		</para>
		<example>
		<title>Setting domain_table parameter</title>
		<programlisting format="linespecific">
modparam("domain", "domain_table", "new_name")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>domain_col</varname> (string)</title>
		<para>
		Name of column containing domains in domain table.
		</para>
		<para>
		Default value is <quote>domain</quote>.
		</para>
		<example>
		<title>Setting domain_col parameter</title>
		<programlisting format="linespecific">
modparam("domain", "domain_col", "domain_name")
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>attrs_col</varname> (string)</title>
		<para>
		Name of column containing attributes in domain table.
		</para>
		<para>
		Default value is <quote>attrs</quote>.
		</para>
		<example>
		<title>Setting attrs_col parameter</title>
		<programlisting format="linespecific">
modparam("domain", "attrs_col", "attributes")
</programlisting>
		</example>
	</section>
	
	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_is_from_local" xreflabel="is_from_local()">
		<title><function moreinfo="none">is_from_local([attrs_var])</function></title>
		<para>
		Checks based on domain table if host part of From header uri is
		one of the local domains that the proxy is responsible for.
		The argument is optional and if present it should contain a writable
		variable that will be populated with the attributes from the
		database.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title>is_from_local usage</title>
		<programlisting format="linespecific">
...
if (is_from_local()) {
	...
};
...
if (is_from_local($var(attrs))) {
	xlog("Domain attributes are $var(attrs)\n");
	...
};
...
		</programlisting>
		</example>
	</section>
	<section id="func_is_uri_host_local" xreflabel="is_uri_host_local()">
		<title><function moreinfo="none">is_uri_host_local([attrs_var])</function></title>
		<para>
		If called from route or failure route block, checks
		based on domain table if host part of Request-URI is one
		of the local domains that the proxy is responsible for.
		If called from branch route, the test is made on host
		part of URI of first branch, which thus must have been
		appended to the transaction before is_uri_host_local()
		is called.
		The argument is optional and if present it should contain a writable
		variable that will be populated with the attributes from the
		database.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>is_uri_host_local usage</title>
		<programlisting format="linespecific">
...
if (is_uri_host_local()) {
	...
};
...
if (is_uri_host_local($var(attrs))) {
	xlog("Domain attributes are $var(attrs)\n");
	...
};
		</programlisting>
		</example>
	</section>
	<section id="func_is_domain_local" xreflabel="is_domain_local()">
		<title><function moreinfo="none">is_domain_local(domain, [attrs_var])</function></title>
		<para>
		This function checks if the domain contained in the first parameter is local.
		</para>
		<para>
		This function is a generalized form of the is_from_local()
		and is_uri_host_local() functions, being able to completely
		replace them and also extends them by allowing the domain to
		be taken from any of the above mentioned sources.
                The following equivalences exist:
		</para>
		<itemizedlist>
		<listitem><para>
			is_domain_local($rd) is same as is_uri_host_local()
		</para></listitem>
		<listitem><para>
			is_domain_local($fd) is same as is_from_local()
		</para></listitem>
		</itemizedlist>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>domain</emphasis> (string)
			</para></listitem>
			<listitem><para>
				<emphasis>attrs_var</emphasis> (var, optional) - a writable
				variable that will be populated with the attributes from the
				database.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title>is_domain_local usage</title>
		<programlisting format="linespecific">
...
if (is_domain_local($rd)) {
	...
};
if (is_domain_local($fd)) {
	...
};
if (is_domain_local($avp(some_avp_alias))) {
	...
};
if (is_domain_local($avp(850))) {
	...
};
if (is_domain_local($avp(some_avp))) {
	...
};
if (is_domain_local($avp(some_avp), $avp(attrs))) {
	xlog("Domain attributes are $avp(attrs)\n");
	...
};
...
		</programlisting>
		</example>
	</section>
	</section>
	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_domain_reload" xreflabel="domain_reload">
		<title><function moreinfo="none">domain_reload</function></title>
		<para>
		Causes domain module to re-read the contents of domain table
		into cache memory.
		</para>
		<para>
		Name: <emphasis>domain_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		opensips-cli -x mi domain_reload
		</programlisting>
		
	</section>
	<section id="mi_domain_dump" xreflabel="domain_dump">
		<title><function moreinfo="none">domain_dump</function></title>
		<para>
		Causes domain module to dump hash indexes and domain names in
		its cache memory.
		</para>
		<para>
		Name: <emphasis>domain_dump</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		opensips-cli -x mi domain_dump
		</programlisting>
	</section>
	</section>
	<section>
	<title>Known Limitations</title>
	<para>
		There is an unlikely race condition on domain list update.  If a 
		process uses a table, which is reloaded at the same time twice 
		through <acronym>FIFO</acronym>, the second reload will delete the 
		original table still in use by the process.
	</para>
	</section>
</chapter>

