uuid: new module to generate unique strings using libuuid

- new class of variables exported - $uuid(type)
- type can be:
	- g - generic/default uuid generation
	- r - random uuid generation
	- t - time based uuid generation
	- s - time safe uuid generation

modules/uuid/Makefile

@@ -0,0 +1,23 @@
+#
+# WARNING: do not run this directly, it should be run by the master Makefile
+
+include ../../Makefile.defs
+auto_gen=
+NAME=uuid.so
+
+ifeq ($(CROSS_COMPILE),)
+	BUILDER = $(shell which pkg-config)
+endif
+
+ifneq ($(BUILDER),)
+	DEFS += $(shell $(BUILDER) --cflags uuid)
+	LIBS += $(shell $(BUILDER) --libs uuid)
+else
+	DEFS +=-I$(LOCALBASE)/include -I$(SYSBASE)/include
+	LIBS+=-L$(LOCALBASE)/lib -L$(SYSBASE)/lib -luuid
+endif
+
+
+DEFS+=-DKAMAILIO_MOD_INTERFACE
+
+include ../../Makefile.modules

modules/uuid/README

@@ -0,0 +1,81 @@
+UUID Module
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+Edited by
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+   Copyright © 2014 asipto.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Usage
+
+   List of Examples
+
+   1.1. $uuid(type) usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Usage
+
+1. Overview
+
+   This module exports the $uuid(type) class of variables that return
+   unique values using libuuid functions.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * none.
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * libuuid - OSSP uuid - Universally Unique Identifier (UUID) Library
+
+3. Usage
+
+   Following variables can be used:
+     * $uuid(g) - return the UUID value using uuid_generate().
+     * $uuid(r) - return the UUID value using uuid_generate_random().
+     * $uuid(t) - return the UUID value using uuid_generate_time().
+     * $uuid(s) - 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().
+
+   Example 1.1. $uuid(type) usage
+...
+$var(uuid) = $uuid(g);
+xdbg("generated uuid is [$var(uuid)]\n");
+add_rr_param(";uuid=$var(uuid)");
+...

modules/uuid/doc/Makefile

@@ -0,0 +1,4 @@
+docs = uuid.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module

modules/uuid/doc/uuid.xml

@@ -0,0 +1,37 @@
+<?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 "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>UUID Module</title>
+	<productname class="trade">kamailio.org</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<email>[email protected]</email>
+	    </author>
+	    <editor>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<email>[email protected]</email>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2014</year>
+	    <holder>asipto.com</holder>
+	</copyright>
+    </bookinfo>
+    <toc></toc>
+    
+    <xi:include href="uuid_admin.xml"/>
+    
+    
+</book>

modules/uuid/doc/uuid_admin.xml

@@ -0,0 +1,102 @@
+<?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 "../../../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 libuuid functions.
+	</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>
+			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>
+

modules/uuid/uuid_mod.c

@@ -0,0 +1,178 @@
+/**
+ * Copyright (C) 2014 Daniel-Constantin Mierla (asipto.com)
+ *
+ * This file is part of Kamailio, a free SIP server.
+ *
+ * This file is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version
+ *
+ *
+ * This file is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ */
+
+#include <stdio.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <uuid/uuid.h>
+
+#include "../../sr_module.h"
+#include "../../dprint.h"
+#include "../../ut.h"
+#include "../../pvar.h"
+
+MODULE_VERSION
+
+static int  mod_init(void);
+static int  child_init(int);
+static void mod_destroy(void);
+
+static uuid_t _k_uuid_val;
+static char   _k_uuid_str[40];
+
+int pv_get_uuid(sip_msg_t *msg, pv_param_t *param,
+		pv_value_t *res);
+int pv_parse_uuid_name(pv_spec_p sp, str *in);
+
+static pv_export_t mod_pvs[] = {
+	{ {"uuid", (sizeof("uuid")-1)}, PVT_OTHER, pv_get_uuid,
+		0, pv_parse_uuid_name, 0, 0, 0},
+
+	{ {0, 0}, 0, 0, 0, 0, 0, 0, 0 }
+};
+
+static cmd_export_t cmds[]={
+	{0, 0, 0, 0, 0, 0}
+};
+
+static param_export_t params[]={
+	{0, 0, 0}
+};
+
+struct module_exports exports = {
+	"uuid",
+	DEFAULT_DLFLAGS, /* dlopen flags */
+	cmds,
+	params,
+	0,
+	0,              /* exported MI functions */
+	mod_pvs,        /* exported pseudo-variables */
+	0,              /* extra processes */
+	mod_init,       /* module initialization function */
+	0,              /* response function */
+	mod_destroy,    /* destroy function */
+	child_init      /* per child init function */
+};
+
+
+
+/**
+ * init module function
+ */
+static int mod_init(void)
+{
+	uuid_generate(_k_uuid_val);
+
+	_k_uuid_str[0] = '\0';
+	uuid_unparse_lower(_k_uuid_val, _k_uuid_str);
+	LM_DBG("uuid initialized - probing value [%s]\n", _k_uuid_str);
+	uuid_clear(_k_uuid_val);
+	_k_uuid_str[0] = '\0';
+
+	return 0;
+}
+
+/**
+ * @brief Initialize async module children
+ */
+static int child_init(int rank)
+{
+	if (rank!=PROC_MAIN)
+		return 0;
+
+	return 0;
+}
+/**
+ * destroy module function
+ */
+static void mod_destroy(void)
+{
+	uuid_generate(_k_uuid_val);
+	uuid_clear(_k_uuid_val);
+}
+
+/**
+ * parse the name of the $uuid(name)
+ */
+int pv_parse_uuid_name(pv_spec_p sp, str *in)
+{
+	if(sp==NULL || in==NULL || in->len<=0)
+		return -1;
+	switch(in->s[0])
+	{
+		case 'g':
+		case 'G':
+			sp->pvp.pvn.u.isname.name.n = 0;
+			break;
+		case 'r':
+		case 'R':
+			sp->pvp.pvn.u.isname.name.n = 1;
+			break;
+		case 't':
+		case 'T':
+			sp->pvp.pvn.u.isname.name.n = 2;
+			break;
+		case 's':
+		case 'S':
+			sp->pvp.pvn.u.isname.name.n = 3;
+			break;
+		default:
+			sp->pvp.pvn.u.isname.name.n = 0;
+	}
+	sp->pvp.pvn.type = PV_NAME_INTSTR;
+	sp->pvp.pvn.u.isname.type = 0;
+
+	return 0;
+}
+
+/**
+ * return the value of $uuid(name)
+ */
+int pv_get_uuid(sip_msg_t *msg, pv_param_t *param,
+		pv_value_t *res)
+{
+	if(param==NULL)
+		return -1;
+	switch(param->pvn.u.isname.name.n)
+	{
+		case 1:
+			uuid_generate_random(_k_uuid_val);
+		break;
+		case 2:
+			uuid_generate_time(_k_uuid_val);
+		break;
+		case 3:
+#ifndef __OS_darwin
+			if(uuid_generate_time_safe(_k_uuid_val))
+				return pv_get_null(msg, param, res);
+#else
+			uuid_generate_time(_k_uuid_val);
+#endif
+		break;
+		default:
+			uuid_generate(_k_uuid_val);
+	}
+	uuid_unparse_lower(_k_uuid_val, _k_uuid_str);
+	return pv_get_strzval(msg, param, res, _k_uuid_str);
+}