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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>Various checks related to &sip; &uri;.</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>a &ser; database module (optional)</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Exported Parameters</title>

	<section>
		<title><varname>db_url</varname> (string)</title>
		<para>
		&url; of the database to be used.
		</para>
		<para>
		If the db_url string is empty, the DB backend will be disabled - some
		function may operated without DB support.
		</para>
		<para>
		<emphasis>
			Default value is <quote>DEFAULT_RODB_URL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "db_url", "mysql://username:password@localhost/openser")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>uri_table</varname> (string)</title>
		<para>
		Table containing list of allowed &uri;s for each user.
		</para>
		<para>
		<emphasis>
			Default value is <quote>uri</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uri_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "uri_table", "uri")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>uri_user_column</varname> (string)</title>
		<para>
		Column holding usernames in the &uri; table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uri_user_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "uri_user_column", "username")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>uri_domain_column</varname> (string)</title>
		<para>
		Column holding domain in the &uri; table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uri_domain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "uri_domain_column", "domain")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>uri_uriuser_column</varname> (string)</title>
		<para>
		Column holding &uri; username in the &uri; table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>uri_user</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uri_uriuser_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "uri_uriuser_column", "uri_user")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>subscriber_table</varname> (string)</title>
		<para>
		Name of the subscriber table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>subscriber</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>subscriber_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "subscriber_table", "subscriber")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>subscriber_user_column</varname> (string)</title>
		<para>
		Column holding username in subscriber table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>subscriber_user_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "subscriber_user_column", "username")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>subscriber_domain_column</varname> (string)</title>
		<para>
		Column holding domains in the subscriber table.
		</para>
		<para>
		<emphasis>
			Default value is <quote>domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>subscriber_domain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "subscriber_domain_column", "domain")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_uri_table</varname> (integer)</title>
		<para>
		Specify if the <quote>uri</quote> table should be used for checkings
		instead of <quote>subscriber</quote> table. Non 0 value means true.
		</para>
		<para>
		If enabled, setting a non-null db_url is mandatory.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0 (false)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_uri_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "use_uri_table", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_domain</varname> (integer)</title>
		<para>
		Specify if the domain part of the URI should be used to identify the
		users (along with username). Useful in multi domain setup. Non 0 value
		means true.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0 (false)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uri_db", "use_domain", 1)
...
</programlisting>
		</example>
	</section>

	</section>
	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">check_to()</function>
		</title>
		<para>
		Check To username against &uri; table (if use_uri_table is set) or
		digest credentials (no DB backend required).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>check_to</function> usage</title>
		<programlisting format="linespecific">
...
if (check_to()) {
	...
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">check_from()</function>
		</title>
		<para>
		Check From username against &uri; table (if use_uri_table is set) or
		digest credentials (no DB backend required).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>check_from</function> usage</title>
		<programlisting format="linespecific">
...
if (check_from()) {
	...
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">does_uri_exist()</function>
		</title>
		<para>
		Check if username in the request &uri; belongs to an existing user.
		</para>
		<para>
		As the checking is done against &uri; table (if use_uri_table is set) 
		or subscriber table, setting a non-null db_url is mandatory.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>does_uri_exist</function> usage</title>
		<programlisting format="linespecific">
...
if (does_uri_exist()) {
	...
};
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("uri_db.sgml" "Book" "chapter")
End:
-->
