avpops_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 1,095 行 · 第 1/3 页

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
			<revnumber>$Revision: 1.22 $</revnumber>
			<date>$Date: 2006/05/29 13:46:09 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>


	<section>
		<title>Overview</title>
		<para>
		AVPops (AVP-operations) modules implements a set of script
		functions which allow access and manipulation of user AVPs
		(preferences) and pseudo-variables. AVPs are a powerful tool
		for implementing services/preferences per user/domain. Now they
		are usable directly from configuration script. Functions for
		interfacing DB resources (loading/storing/removing), functions
		for swapping information between AVPs and SIP messages, function for 
		testing/checking the value of an AVP.
		</para>
		<para>
		An up-to-date tutorial providing more information (detailed
		explanations and commented examples) can be found on Voice Sistem
		documentation web page at http://voice-system.ro/docs/avpops .
		</para>
	</section>
	<section>
		<title>Dependencies</title>
		<section>
			<title>&openser; Modules</title>
			<para>
			The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>Optionally a database module</emphasis>
			</para>
			</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
				The following libraries or applications must be installed 
				before running &openser; with this module loaded:
				<itemizedlist>
				<listitem>
				<para>
					<emphasis>None</emphasis>
				</para>
				</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section>
		<title>AVP naming format</title>
		<para>
		The format of the parameters specifying an AVP in functions exported
		by this module is:
			<emphasis role="bold">$avp(avp_flags:avp_name)</emphasis> or
			<emphasis role="bold">$avp(avp_alias)</emphasis>.
		</para>
		<itemizedlist>
		<listitem>
		<para>
			<emphasis>avp_flags</emphasis> = type_flags [script_flags]; type_flags = 'I' | 'i' | 'S' | 's'; script_flags = 0..255
		</para>
		<para>
		'I' or 'i' means that the type of avp name is integer (ID)
		</para>
		<para>
		'S' or 's' means that the type of avp name is string
		</para>
		<para>
		The type flag is mandatory.
		</para>
		<para>
		script_flags must be an 8 bit unsigned number, therefore can be set
		up to 8 flags. If no script flag is provided, the name will
		match all AVPs, regardless they have or not a script flag set (preserves
		the compatibility with the old naming schema).
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>avp_name</emphasis> = string | integer
		</para>
		<para>
		string - might be any alphanumeric string, wich contain following
		characters: [a-z] [A-Z] [0-9] '_'
		</para>
		<para>
		integer - might be an unsigned integer, greater than zero, up to 2^16-1
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>avp_alias</emphasis> = string
		</para>
		<para>
		string - might be any alphanumeric string, wich contain following
		characters: [a-z] [A-Z] [0-9] '_'
		</para>
		</listitem>
		</itemizedlist>
			<example>
				<title>AVP naming examples</title>
				<programlisting format="linespecific">
...
$avp(i:11) - the AVP identified by integer 11
$avp(s:foo) - the AVP identified by the string 'foo'
$avp(bar) - the AVP identified by the AVP alias 'bar'
$avp(i3:123) - the AVP identified by the integer 123 which has script flags 1
    and 2 set
...
				</programlisting>
			</example>
	</section>
	<section>
		<title>Exported Parameters</title>
		<section>
			<title><varname>avp_url</varname> (string)</title>
			<para>
			DB URL for database connection.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default value being NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>avp_url</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","avp_url","mysql://user:passwd@host/database")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>db_url</varname> (string)</title>
			<para>
			This parameter has the same meaning as <quote>avp_url</quote>
			parameter.
			</para>
		</section>
		<section>
			<title><varname>avp_table</varname> (string)</title>
			<para>
			DB table to be used.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default value being NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>avp_table</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","avp_table","avptable")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>avp_aliases</varname> (string)</title>
			<para>
			Contains a multiple definition of aliases for AVP names.
			</para>
			<para>
			<para>
				<emphasis>
					This parameter is optional.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>avp_aliases</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","avp_aliases","uuid=I:660;email=s:email_addr;fwd=i:753")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>use_domain</varname> (integer)</title>
			<para>
				If the domain part of the an URI should be used for 
				identifying an AVP in DB operations.
			</para>
			<para>
				<emphasis>Default value is 0 (no).
				</emphasis>
			</para>
			<example>
				<title>Set <varname>use_domain</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("avpops","use_domain",1)
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>uuid_column</varname> (string)</title>
			<para>
				Name of column containing the uuid (unique user id).
			</para>
			<para>
				<emphasis>Default value is <quote>uuid</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>uuid_column</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","uuid_column","uuid")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>username_column</varname> (string)</title>
			<para>
				Name of column containing the username.
			</para>
			<para>
				<emphasis>Default value is <quote>username</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>username_column</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","username_column","username")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>domain_column</varname> (string)</title>
			<para>
				Name of column containing the domain name.
			</para>
			<para>
				<emphasis>Default value is <quote>domain</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>domain_column</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("avpops","domain_column","domain")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>attribute_column</varname> (string)</title>
			<para>
				Name of column containing the attribute name (AVP name).
			</para>
			<para>
				<emphasis>Default value is <quote>attribute</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>attribute_column</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("avpops","attribute_column","attribute")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>value_column</varname> (string)</title>
			<para>
				Name of column containing the AVP value.
			</para>
			<para>
				<emphasis>Default value is <quote>value</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>value_column</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("avpops","value_column","value")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>type_column</varname> (string)</title>
			<para>
				Name of column containing the AVP type.
			<para>
				<emphasis>Default value is <quote>type</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>type_column</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("avpops","type_column","type")
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>db_scheme</varname> (string)</title>
			<para>
				Definition of a DB schemeto be used for non-standard
				access to Database information.
			<para>
				<emphasis>Default value is <quote>NULL</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>db_scheme</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("avpops","db_scheme",
"scheme1:table=subscriber;uuid_column=uuid;value_column=first_name")
...
				</programlisting>
			</example>
		</section>
	</section>


	<section>
		<title>Exported Functions</title>
		<section>
			<title>
				<function moreinfo="none">avp_db_load(source,name)
				</function>
			</title>
			<para>
			Loads from DB into memory the AVPs corresponding to the given
			<emphasis>source</emphasis>. If given, it sets the script flags
			for loaded AVPs.
			</para>
			<para>Meaning of the parameters is as follows:</para>
			<itemizedlist>
			<listitem>
				<para><emphasis>source</emphasis> - what info is used for 
				identifying the AVPs. Parameter syntax:
				<itemizedlist>