<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

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

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module exports the $uuid(type) class of variables that return
		unique values using functions from the libuuid library. UUIDs are
		used in the +sip.instance media feature tag in SIP, but can also
		be used for other purposes, like defining a unique session ID for a
		group of SIP dialogs.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libuuid</emphasis> - OSSP uuid - Universally Unique
				Identifier (UUID) Library
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
		<title>Usage</title>
		<para>
			The following variables can be used:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>$uuid(g)</emphasis> - return the UUID value using
				uuid_generate().
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>$uuid(r)</emphasis> - return the UUID value using
				uuid_generate_random().
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>$uuid(t)</emphasis> - return the UUID value using
				uuid_generate_time().
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>$uuid(s)</emphasis> - return the UUID value using
				uuid_generate_time_safe(). If the generation was not safe,
				the variable returns $null. The function is not available
				on Mac OS X - the value is the one returned by
				uuid_generate_time().
			</para>
			</listitem>
			</itemizedlist>
		</para>
		<example>
		<title><function>$uuid(type)</function> usage</title>
		<programlisting format="linespecific">
...
$var(uuid) = $uuid(g);
xdbg("generated uuid is [$var(uuid)]\n");
add_rr_param(";uuid=$var(uuid)");
...
</programlisting>
	    </example>

	</section>
</chapter>

