registrar_user.sgml

性能优秀的SIP Proxy

	<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>
		<title><varname>sock_flag</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		This make sens 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>
		<title><varname>sock_hdr_name</varname> (string)</title>
		<para>
		Header which contains a socket description (proto:IP:port) to overide
		the the received socket info. The heaer will be read only if the
		flag sock_flag is set.
		</para>
		<para>
		This make sens only in multiple replicated servers scenarios.
		</para>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sock_hdr_namer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_branch_flags</varname> (integer)</title>
		<para>
		If enabled (has a non zero value), the NAT flag for the additional
		branches will be pushed in branch flags (in dset/branch array).
		Otherwise it will be pushed in the message flags. In both cases, the
		NAT flag for the RURI will be push into message flags.
		</para>
		<para>
		This make sens to be enabled only if branch route will be used.
		</para>
		<para>
		<emphasis>
			Default value is 0 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_branch_flags</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "use_branch_flags", 1)
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>method_filtering</varname> (integer)</title>
		<para>
		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.
		</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>
		<title><varname>use_path</varname> (integer)</title>
		<para>
		If set to 1, the Path header is handled according to the parameter 
		<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>
		<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 of 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>
		<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>
		<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 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>

	<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>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<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 name of the table which 
			stores the contacts.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<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 updates only the memory 
		cache, even if DB support (any type) is enabled.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>domain</emphasis> - Logical domain within registrar 
			(Ex: <quote>location</quote>).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>save_memory</function> usage</title>
		<programlisting format="linespecific">
...
save_memory("location");
...
</programlisting>
		</example>
	</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>
		If the method_filtering option is enabled, the lookup 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>
		</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 ($?) {
    case -1:
    case -3:
        sl_send_reply("404", "Not Found");
        exit;
    case -2:
        sl_send_reply("405", "Not Found");
        exit;
};
...
</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>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>registered</function> usage</title>
		<programlisting format="linespecific">
...
if (registered("location")) {
	sl_send_reply("100", "Trying");
	...
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">add_sock_hdr(hdr_name)</function>
		</title>
		<para>
		Adds to the current REGISTER request a new header with 
		<quote>hdr_name</quote> which contains the description of the
		received socket (proto:ip:port)
		</para>
		<para>
		This make sens 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.
			</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>
</chapter>

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