Add UUID support to Asterisk.

This provides a common API for dealing with unique identifiers.
The API provides methods to create, parse, copy, and stringify UUIDs.

An accompanying unit test is provided that tests all operations.

(closes issue ASTERISK-20726)
reported by Matt Jordan

Review: https://reviewboard.asterisk.org/r/2217



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@377846 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/autoconfig.h.in

@@ -848,19 +848,19 @@
 /* Define to 1 if you have the `strtoq' function. */
 #undef HAVE_STRTOQ
 
-/* Define to 1 if `ifr_ifru.ifru_hwaddr' is member of `struct ifreq'. */
+/* Define to 1 if `ifr_ifru.ifru_hwaddr' is a member of `struct ifreq'. */
 #undef HAVE_STRUCT_IFREQ_IFR_IFRU_IFRU_HWADDR
 
-/* Define to 1 if `uid' is member of `struct sockpeercred'. */
+/* Define to 1 if `uid' is a member of `struct sockpeercred'. */
 #undef HAVE_STRUCT_SOCKPEERCRED_UID
 
-/* Define to 1 if `st_blksize' is member of `struct stat'. */
+/* Define to 1 if `st_blksize' is a member of `struct stat'. */
 #undef HAVE_STRUCT_STAT_ST_BLKSIZE
 
-/* Define to 1 if `cr_uid' is member of `struct ucred'. */
+/* Define to 1 if `cr_uid' is a member of `struct ucred'. */
 #undef HAVE_STRUCT_UCRED_CR_UID
 
-/* Define to 1 if `uid' is member of `struct ucred'. */
+/* Define to 1 if `uid' is a member of `struct ucred'. */
 #undef HAVE_STRUCT_UCRED_UID
 
 /* Define to 1 if you have the mISDN Supplemental Services library. */
@@ -1138,6 +1138,9 @@
 /* Define to the one symbol short name of this package. */
 #undef PACKAGE_TARNAME
 
+/* Define to the home page for this package. */
+#undef PACKAGE_URL
+
 /* Define to the version of this package. */
 #undef PACKAGE_VERSION
 

include/asterisk/uuid.h

@@ -0,0 +1,107 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012, Digium, Inc.
+ *
+ * Mark Michelson <mmmichelson@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ * \brief Universally unique identifier support
+ */
+
+#ifndef _ASTERISK_UUID_H
+#define _ASTERISK_UUID_H
+
+/* Size of an RFC 4122 UUID string plus terminating null byte */
+#define AST_UUID_STR_LEN 37
+
+struct ast_uuid;
+
+/*!
+ * \brief Initialize the UUID system
+ */
+void ast_uuid_init(void);
+
+/*!
+ * \brief Generate a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \retval NULL Generation failed
+ * \retval non-NULL heap-allocated UUID
+ */
+struct ast_uuid *ast_uuid_generate(void);
+
+/*!
+ * \brief Convert a UUID to a string
+ *
+ * \param uuid The UUID to convert to a string
+ * \param[out] buf The buffer where the UUID string will be stored
+ * \param size The size of the buffer. Must be at least AST_UUID_STR_LEN.
+ * \returns The UUID string (a pointer to buf)
+ */
+char *ast_uuid_to_str(const struct ast_uuid *uuid, char *buf, size_t size);
+
+/*!
+ * \brief Convert a string to a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \param str The string to convert to a UUID
+ * \retval NULL Failed to convert
+ * \retval non-NULL The heap-allocated converted UUID
+ */
+struct ast_uuid *ast_str_to_uuid(const char *str);
+
+/*!
+ * \brief Make a copy of a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \param src The source UUID to copy
+ * \retval NULL Failed to copy
+ * \retval non-NULL The heap-allocated duplicate UUID
+ */
+struct ast_uuid *ast_uuid_copy(const struct ast_uuid *src);
+
+/*!
+ * \brief Compare two UUIDs
+ *
+ * \param left First UUID to compare
+ * \param right Second UUID to compare
+ * \retval <0 left is lexicographically less than right
+ * \retval 0 left and right are the same
+ * \retval >0 left is lexicographically greater than right
+ */
+int ast_uuid_compare(const struct ast_uuid *left, const struct ast_uuid *right);
+
+/*!
+ * \brief Clear a UUID by setting it to be a nil UUID (all 0s)
+ *
+ * \param uuid UUID to clear
+ */
+void ast_uuid_clear(struct ast_uuid *uuid);
+
+/*!
+ * \brief Check if a UUID is a nil UUID (all 0s)
+ *
+ * \param uuid UUID to check
+ * \retval 0 The UUID is not nil
+ * \retval non-zero The UUID is nil
+ */
+int ast_uuid_is_nil(const struct ast_uuid *uuid);
+#endif