registrar_user.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.7.2.1 $</revnumber>
		<date>$Date: 2005/06/22 23:12:07 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>The module contains REGISTER processing logic.</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>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
		&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>default_expires</varname> (integer)</title>
	    <para>
		If the processed message contains neither Expires <acronym>HFs</acronym> 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).
	    </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>
	    <title><varname>default_q</varname> (integer)</title>
	    <para>
		The parameter represents default q value for new contacts. Because ser doesn't
		support float parameter types, the value in the parameter is divided by 100 and
		stored as float. For example, if you want default_q to be 0.38, use value 38 here.
	    </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", 100)
...
</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 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 contact and the rest will be left unprocessed.
	    </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>
	    <title><varname>case_sensitive</varname> (integer)</title>
	    <para>
		If set to 1 then <acronym>AOR</acronym> comparison will be case sensitive, if set to
		0 then <acronym>AOR</acronym> comparison will be case insensitive--This is recommended.
	    </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>
	    <title><varname>desc_time_order</varname> (integer)</title>
	    <para>
		If set to 1 then all contacts will be ordered in descending modification time
		order. In this case the most recently updated/created contact will be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>desc_time_order</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "desc_time_order", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>nat_flag</varname> (integer)</title>
	    <para>
		The number of the NAT-flag. This is the flag which is set when
		the originator of a message is behind NAT. This flag will be
		saved in the user location database when save function is
		executed and recovered later by lookup function.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>nat_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "nat_flag", 6)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>realm_prefix</varname> (string)</title>
	    <para>
		The prefix to be stripped from the beginning of hostname
		part. This is useful when dealing with user agents that do not
		allow to specify different hostname part and outbound
		server. Such user agents would typically resolve a domain using
		SRV and put the hostname obtained from SRV in From and To
		header field of REGISTER message. For example, if SRV for
		iptel.org points to sip.iptel.org then such user agents would
		create From: sip:[e-mail] and in this case this
		parameter can be used to strip "sip." prefix.
	    </para>
	    <para>
		<emphasis>
		    Default value is "".
		</emphasis>
	    </para>
	</section>


	<section>
	    <title><varname>min_expires</varname> (integer)</title>
	    <para>
		The minimum expires value of a Contact, values lower than this minimum will be
		automatically set to the minimum. Value 0 disables the checking.
	    </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>
	    <title><varname>max_expires</varname> (integer)</title>
	    <para>
		The maximum expires value of a Contact, values higher than this maximum will be
		automatically set to the maximum. Value 0 disables the checking.
	    </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>
	    <title><varname>received_param</varname> (integer)</title>
	    <para>
		The name of the parameter that will be appended to Contacts of 200 OK when the
		received URI was set by nathelper module.
	    </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>
	    <title><varname>received_avp</varname> (integer)</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 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 42.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>received_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "received_avp", 43)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>use_domain</varname> (integer)</title>
	    <para>
		If set to 1 then the registrar will use username@domain as address of record. If
		the variable is set to 0 then only username will be used as the address of record.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "use_domain", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <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. Value 0 disables the check.
	    </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>
	    <title><varname>retry_after</varname> (integer)</title>
	    <para>
		The registrar can generate 5xx reply to REGISTER 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.
	    </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>
    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">save(domain)</function>
	    </title>
	    <para>
		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,
		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.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>domain</emphasis> - Logical domain within registrar. If database
			is used then this must be name of the table which stores the contacts.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>save</function> usage</title>
		<programlisting format="linespecific">
...
save("location");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">save_noreply(domain)</function>
	    </title>
	    <para>
		Same as <function>save()</function> but it doesn't send a reply.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>domain</emphasis> - Logical domain within registrar. If database is
			used then this must be na e of the table which stores the contacts.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>save_noreply</function> usage</title>
		<programlisting format="linespecific">
...
save_noreply("location");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">save_memory(domain)</function>
	    </title>
	    <para>
		Same as <function>save()</function> but it does update the
		memory cache only. The contents of the database will be not
		updated. This is useful for REGISTER replication where two
		machines updating the same database would generate a
		conflict. In such a scenario one machine could update the
		database, replicate the message to the other machine and that
		one would only update memory cache.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>domain</emphasis> - Logical domain within registrar. If database is
			used then this must be na e of the table which stores the contacts.
		    </para>
		</listitem>
	    </itemizedlist>
	</section>

	<section>
	    <title>
		<function moreinfo="none">lookup(domain)</function>
	    </title>
	    <para>
		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).
	    </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>
	    <example>
		<title><function>lookup</function> usage</title>
		<programlisting format="linespecific">
...
lookup("location");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">registered(domain)</function>
	    </title>
	    <para>
		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.
	    </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>
	    <example>
		<title><function>registered</function> usage</title>
		<programlisting format="linespecific">
...
if (registered("location")) {
    sl_send_reply("100", "Trying");
    ...
};
...
</programlisting>
	    </example>
	</section>
    </section>
</chapter>

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