<!-- Auth_radius 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>
	gflags module (global flags) keeps a bitmap of flags in shared memory
	and may be used to change behaviour of server based on value of the flags.
	Example:
	<programlisting format="linespecific">
	if (is_gflag("1")) {
		t_relay("udp:10.0.0.1:5060");
	} else {
		t_relay("udp:10.0.0.2:5060");
	}
	</programlisting>
	</para>
	<para>
	The benefit of this module is the value of the switch flags
	can be manipulated by external applications such as web interface
	or command line tools. The size of bitmap is 32.
	</para>
	<para>
	The module exports external commands that can be used to change
	the global flags via Management Interface. The MI commands are:
	<quote>set_gflag</quote>, <quote>reset_gflag</quote> and
	<quote>is_gflag</quote>.
	</para>
	</section>

	<section>
	<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>none</emphasis></para>
		</listitem>
		</itemizedlist>
	</para>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>initial</varname> (integer)</title>
		<para>
		The initial value of global flags bitmap.
		</para>
		<para>
		Default value is <quote>0</quote>.
		</para>
		<example>
		<title><varname>initial</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("gflags", "initial", 15)
		</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title><function moreinfo="none">set_gflag(flag)</function></title>
		<para>
		Set the bit at the position <quote>flag</quote> in global flags.
		</para>
		<para>
		<quote>flag</quote> can have a value from the range 1..31.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">set_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
set_gflag("4");
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">reset_gflag(flag)</function></title>
		<para>
		Reset the bit at the position <quote>flag</quote> in global flags.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">reset_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
reset_gflag("4");
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">is_gflag(flag)</function></title>
		<para>
		Check if bit at the position <quote>flag</quote> in global flags is
		set.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">is_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
if(is_gflag("4"))
{
	log("global flag 4 is set\n");
} else {
	log("global flag 4 is not set\n");
};
...
</programlisting>
		</example>
	</section>

	</section>

	<section>
		<title><acronym>MI</acronym> Commands</title>
		<section>
			<title><function moreinfo="none">set_gflag</function></title>
			<para>
			Set the value of some flags to 1. The function accepts one 
			parameter which is the flag bitmap/mask specifing the flags to be
			set.
			</para>
			<para>
			The paremeter value must be a number in decimal or hexa format
			</para>
			<example>
			<title><function moreinfo="none">set_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ openserctl fifo set_gflag 1
$ openserctl fifo set_gflag 0x3
...
</programlisting>
			</example>

		</section>
		<section>
			<title><function moreinfo="none">reset_gflag</function></title>
			<para>
			Reset the value of some flags to 0. The function accepts one 
			parameter which is the flag bitmap/mask specifing the flags to be
			reset.
			</para>
			<para>
			The paremeter value must be a number in decimal or hexa format
			</para>
			<example>
			<title>
				<function moreinfo="none">reset_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ openserctl fifo reset_gflag 1
$ openserctl fifo reset_gflag 0x3
...
</programlisting>
			</example>
		</section>
		<section>
			<title><function moreinfo="none">is_gflag</function></title>
			<para>
			Return the status of a set of flags. The function accepts one 
			parameter which is the flag bitmap/mask specifing the flags to be
			checked.
			</para>
			<para>
			The function returns TRUE if all the flags from the set are set
			and FALSE if at least one is not set.
			</para>
			<example>
			<title><function moreinfo="none">set_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ openserctl fifo is_gflag 1
$ openserctl fifo is_gflag 0x3
...
</programlisting>
			</example>
		</section>
		<section>
			<title><function moreinfo="none">get_gflags</function></title>
			<para>
			Return the bitmap with all flags. The function gets no 
			parameters and returns the bitmap in hexa and decimal format.
			</para>
			<example>
			<title>
				<function moreinfo="none">get_gflags</function> usage</title>
			<programlisting format="linespecific">
...
$ openserctl fifo get_gflags
0x3039
12345
...
</programlisting>
			</example>
		</section>
	</section>

</chapter>

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