Asterisk - The Open Source Telephony Project  GIT-master-a24979a
uuid.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012, Digium, Inc.
5  *
6  * Mark Michelson <mmmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief Universally unique identifier support
21  */
22 
23 #ifndef _ASTERISK_UUID_H
24 #define _ASTERISK_UUID_H
25 
26 /* Size of an RFC 4122 UUID string plus terminating null byte */
27 #define AST_UUID_STR_LEN (36 + 1)
28 
29 struct ast_uuid;
30 
31 /*!
32  * \brief Initialize the UUID system
33  */
34 void ast_uuid_init(void);
35 
36 /*!
37  * \brief Generate a UUID
38  *
39  * This function allocates memory on the heap. The returned
40  * pointer must be freed using ast_free()
41  *
42  * \retval NULL Generation failed
43  * \retval non-NULL heap-allocated UUID
44  */
45 struct ast_uuid *ast_uuid_generate(void);
46 
47 /*!
48  * \brief Convert a UUID to a string
49  *
50  * \param uuid The UUID to convert to a string
51  * \param[out] buf The buffer where the UUID string will be stored
52  * \param size The size of the buffer. Must be at least AST_UUID_STR_LEN.
53  * \return The UUID string (a pointer to buf)
54  */
55 char *ast_uuid_to_str(struct ast_uuid *uuid, char *buf, size_t size);
56 
57 /*!
58  * \brief Generate a UUID string.
59  * \since 12.0.0
60  *
61  * \param buf The buffer where the UUID string will be stored
62  * \param size The size of the buffer. Must be at least AST_UUID_STR_LEN.
63  *
64  * \return The UUID string (a pointer to buf)
65  */
66 char *ast_uuid_generate_str(char *buf, size_t size);
67 
68 /*!
69  * \brief Convert a string to a UUID
70  *
71  * This function allocates memory on the heap. The returned
72  * pointer must be freed using ast_free()
73  *
74  * \param str The string to convert to a UUID
75  * \retval NULL Failed to convert
76  * \retval non-NULL The heap-allocated converted UUID
77  */
78 struct ast_uuid *ast_str_to_uuid(char *str);
79 
80 /*!
81  * \brief Make a copy of a UUID
82  *
83  * This function allocates memory on the heap. The returned
84  * pointer must be freed using ast_free()
85  *
86  * \param src The source UUID to copy
87  * \retval NULL Failed to copy
88  * \retval non-NULL The heap-allocated duplicate UUID
89  */
90 struct ast_uuid *ast_uuid_copy(struct ast_uuid *src);
91 
92 /*!
93  * \brief Compare two UUIDs
94  *
95  * \param left First UUID to compare
96  * \param right Second UUID to compare
97  * \retval <0 left is lexicographically less than right
98  * \retval 0 left and right are the same
99  * \retval >0 left is lexicographically greater than right
100  */
101 int ast_uuid_compare(struct ast_uuid *left, struct ast_uuid *right);
102 
103 /*!
104  * \brief Clear a UUID by setting it to be a nil UUID (all 0s)
105  *
106  * \param uuid UUID to clear
107  */
108 void ast_uuid_clear(struct ast_uuid *uuid);
109 
110 /*!
111  * \brief Check if a UUID is a nil UUID (all 0s)
112  *
113  * \param uuid UUID to check
114  * \retval 0 The UUID is not nil
115  * \retval non-zero The UUID is nil
116  */
117 int ast_uuid_is_nil(struct ast_uuid *uuid);
118 #endif
const char * str
Definition: app_jack.c:147
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
Definition: uuid.c:39
int ast_uuid_compare(struct ast_uuid *left, struct ast_uuid *right)
Compare two UUIDs.
Definition: uuid.c:177
void ast_uuid_init(void)
Initialize the UUID system.
Definition: uuid.c:192
struct ast_uuid * ast_str_to_uuid(char *str)
Convert a string to a UUID.
Definition: uuid.c:149
struct ast_uuid * ast_uuid_copy(struct ast_uuid *src)
Make a copy of a UUID.
Definition: uuid.c:166
void ast_uuid_clear(struct ast_uuid *uuid)
Clear a UUID by setting it to be a nil UUID (all 0s)
Definition: uuid.c:182
struct ast_uuid * ast_uuid_generate(void)
Generate a UUID.
Definition: uuid.c:123
char * ast_uuid_to_str(struct ast_uuid *uuid, char *buf, size_t size)
Convert a UUID to a string.
Definition: uuid.c:134
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141
int ast_uuid_is_nil(struct ast_uuid *uuid)
Check if a UUID is a nil UUID (all 0s)
Definition: uuid.c:187