Asterisk - The Open Source Telephony Project GIT-master-2de1a68
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
29struct ast_uuid;
30
31/*!
32 * \brief Initialize the UUID system
33 */
34void 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 */
45struct 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 */
55char *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 */
66char *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 */
78struct 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 */
90struct 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 */
101int 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 */
108void 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 */
117int 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_uuid_generate(void)
Generate a UUID.
Definition: uuid.c:123
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_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
int ast_uuid_is_nil(struct ast_uuid *uuid)
Check if a UUID is a nil UUID (all 0s)
Definition: uuid.c:187
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141
char * ast_uuid_to_str(struct ast_uuid *uuid, char *buf, size_t size)
Convert a UUID to a string.
Definition: uuid.c:134