lcr_user.sgml

性能优秀的SIP Proxy

		name of the AVP contains only digits, the name of the AVP is integer 
		value of the string.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1401</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting <varname>contact_avp</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","contact_avp","1401")

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

<section>
		<title><varname>fr_inv_timer_avp</varname> (string)</title>
		<para>
		Overrides the name of the AVP carrying the Final Response timeout 
		for INVITEs.
		</para>
		<para>
		<emphasis>
			Default value is <quote>fr_inv_timer_avp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting <varname>fr_inv_timer_avp</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","fr_inv_timer_avp","fr_inv_timer_avp")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fr_inv_timer</varname> (integer)</title>
		<para>
		Sets the value of the fist INVITE's Final Response timeout to be used 
		during sequential forwarding:
		</para>
		<para>
		<emphasis>
			Default value is 90.
		</emphasis>
		</para>
		<example>
		<title>Setting <varname>fr_inv_timer</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","fr_inv_timer",90)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fr_inv_timer_next</varname> (integer)</title>
		<para>
		Sets the value of the next INVITE's Final Response timeouts to be used 
		during sequential forwarding:
		</para>
		<para>
		Function next_contacts() sets tm fr_inv_timer to fr_inv_timer_next
		value if, after next contacts, there are still lower qvalue
		contacts available, and to fr_inv_timer value if next contacts are
		the last ones left.
		</para>
		<para>
		<emphasis>
			Default value is 30.
		</emphasis>
		</para>
		<example>
		<title>Setting <varname>fr_inv_timer_next</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","fr_inv_timer_next",30)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>rpid_avp</varname> (string)</title>
		<para>
		Sets the string name of the AVP containing the RPID.
		</para>
		<para>
		<emphasis>
			Default value is <quote>rpid</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting <varname>rpid_avp</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","rpid_avp","rpid")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>db_mode</varname> (integer)</title>
		<para>
		Sets the database mode of operating:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>0</emphasis> : no-caching - a db lookup is 
				performed during each load_gws()
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>1</emphasis> : regexp are used for 
				from_uri; no db lookup is performed during load_gws(), the
				DB content is cached into memory;
			</para>
			</listitem>
		</itemizedlist>
		<para><emphasis>
			Default value is <quote>1</quote>.
		</emphasis></para>
		<example>
		<title>Setting <varname>db_mode</varname> module parameter</title>
		<programlisting format="linespecific">
...
modparam("lcr","db_mode",0)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">load_gws(), load_gws(group-id)</function>
		</title>
		<para>
		Loads URI schemes, addresses, ports, and transports of gateways
		that match user part of Request-URI to gw_uri_avp AVPs (see Overview
		section). If an optional group-id is specified, only gateways belonging
		to this group are loaded.
		Returns 1 or -1 depending on success.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>load_gws</function> usage</title>
		<programlisting format="linespecific">
...
if (!load_gws()) {
	sl_send_reply("500", "Server Internal Error - Cannot load gateways");
	break;
};
...
</programlisting>
		</example>
		<example>
		<title><function>load_gws</function> usage with group-id</title>
		<programlisting format="linespecific">
...
if (!load_gws("1")) {
	sl_send_reply("500", "Server Internal Error - Cannot load gateways from group 1");
	break;
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">next_gw()</function>
		</title>	
		<para>
		If called from a route block, replaces URI scheme, host, port, and
		transport of Request-URI by the values stored in first gw_uri_avp AVP
		and destroys that AVP.  Saves user part of Request-URI into
		ruri_user_avp AVP for use in subsequent next_gw() calls.
		</para>
		<para>
		If called from a failure route block, appends a new branch to
		request, where  URI scheme, host, port, and transport of Request-URI
		is replaced by the values stored in the first gw_uri_avp AVP and
		destroys that AVP.  Request-URI user is taken from ruri_user_avp
		AVP.
		</para>
		<para>
		Returns 1 on success and -1 if there were no gateways left or if an
		error occurred (see syslog).
		</para>
		<para>
		Must be preceded by successful load_gws() call.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>next_gw</function> usage from a route block</title>
		<programlisting format="linespecific">
...
if (!next_gw()) {
	sl_send_reply("503", "Service not available - No gateways");
	break;
};
...
</programlisting>
		</example>
		<example>
		<title><function>next_gw</function> usage from a failure route block
			</title>
		<programlisting format="linespecific">
...
if (!next_gw()) {
	t_reply("503", "Service not available - No more gateways");
	break;
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">from_gw(), from_gw(group-id)</function>
		</title>
		<para>
			Checks if request came from IP address of a gateway. If an
			optional group-id is given, only gateways belonging to this
			group are checked.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>from_gw</function> usage</title>
		<programlisting format="linespecific">
...
if (from_gw()) {
	...
	break;
};
...
</programlisting>
		</example>
		<example>
		<title><function>from_gw</function> usage with group-id</title>
		<programlisting format="linespecific">
...
if (from_gw("1")) {
	...
	break;
};
...
</programlisting>
		</example>
		</section>
		<section>
		<title>
		<function moreinfo="none">to_gw(), to_gw(group-id)</function>
		</title>
		<para>
			Checks if in-dialog request goes to a gateway. If an optional
			group-id is given, only gateways belonging to this group
			are checked.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>to_gw</function> usage</title>
		<programlisting format = "linespecific">
...
if (to_gw()) {
	...
	break;
};
...
</programlisting>
		</example>
		<example>
		<title><function>to_gw</function> usage with group-id</title>
		<programlisting format = "linespecific">
...
if (to_gw("1")) {
	...
	break;
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">load_contacts()</function>
		</title>
		<para>
		Loads contacts in destination set in increasing qvalue order as
		values of lcr_contact AVP.  If all contacts in the destination set
		have the same qvalue, load_contacts() does not do anything thus
		minimizing performance impact of sequential forking capability when
		it is not needed.  Returns 1 if loading of contacts succeeded or
		there was nothing to do.  Returns -1 on error (see syslog).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>load_contacts</function> usage</title>
		<programlisting format = "linespecific">
...
if (!load_contacts()) {
	sl_send_reply("500", "Server Internal Error - Cannot load contacts");
	break;
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">next_contacts()</function>
		</title>
		<para>
		If called from a route block, replaces Request-URI with the first
		lcr_contact AVP value, adds the remaining lcr_contact AVP values 
		with the same qvalue as branches, and destroys those AVPs. It does
		nothing if there are no lcr_contact AVPs.  Returns 1 if there were 
		no errors and -1 if an error occurred (see syslog).
		</para>
		<para>
		If called from a failure route block, adds the first lcr_contact 
		AVP value and all following lcr_contact AVP values with the same 
		qvalue as new branches to request and destroys those AVPs. 
		Returns 1 if new branches were successfully added and -1 on error 
		(see syslog) or if there were no more lcr_contact AVPs.
		</para>
		<para>
		Must be preceded by successful load_contacts() call.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>next_contacts</function> usage from route block
		</title>
		<programlisting format = "linespecific">
...
if (!next_contacts()) {
	sl_send_reply("500", "Server Internal Error");
	break;
} else {
	t_relay();
};
...
</programlisting>
		</example>
		<example>
		<title><function>next_contacts</function> usage from 
			failure route block
		</title>
		<programlisting format = "linespecific">
if (next_contacts()) {
	t_relay();
};
</programlisting>
		</example>
		</section>
	</section>

	<section>
	<title>FIFO Commands</title>
		<section>
		<title><function>lcr_reload</function></title>
		<para>
			Causes lcr module to re-read the contents of gateway table
			into memory.
		</para>
		</section>
		<section>
		<title><function>lcr_dump</function></title>
		<para>
			Causes lcr module to dump the contents of its in-memory gateway
			table. 
		</para>
		</section>
	</section>
	<section>
	<title>Known Limitations</title>
	<para>
		There is an unlikely race condition on lcr reload. If a process uses
		in memory gw table, which is reloaded at the same time twice through
		FIFO, the second reload will delete the original table still in use
		by the process.
	</para>
	</section>

	<section>
	<title>TODO</title>
	<para>
		Function load_gws() currently makes an SQL query for the matching
		gateways.  In order to avoid the query, also lcr table should be
		read into memory and the corresponding query should be rewritten in
		C.
	</para>
	</section>
</chapter>

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