uuid.h File Reference

Universally unique identifier support. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	AST_UUID_STR_LEN   (36 + 1)

Functions
struct ast_uuid *	ast_str_to_uuid (char *str)
	Convert a string to a UUID. More...
void	ast_uuid_clear (struct ast_uuid *uuid)
	Clear a UUID by setting it to be a nil UUID (all 0s) More...
int	ast_uuid_compare (struct ast_uuid *left, struct ast_uuid *right)
	Compare two UUIDs. More...
struct ast_uuid *	ast_uuid_copy (struct ast_uuid *src)
	Make a copy of a UUID. More...
struct ast_uuid *	ast_uuid_generate (void)
	Generate a UUID. More...
char *	ast_uuid_generate_str (char *buf, size_t size)
	Generate a UUID string. More...
void	ast_uuid_init (void)
	Initialize the UUID system. More...
int	ast_uuid_is_nil (struct ast_uuid *uuid)
	Check if a UUID is a nil UUID (all 0s) More...
char *	ast_uuid_to_str (struct ast_uuid *uuid, char *buf, size_t size)
	Convert a UUID to a string. More...

Detailed Description

Universally unique identifier support.

Definition in file uuid.h.

Macro Definition Documentation

AST_UUID_STR_LEN

#define AST_UUID_STR_LEN   (36 + 1)

Definition at line 27 of file uuid.h.

Referenced by add_msid_to_stream(), ast_datastores_alloc_datastore(), ast_rtcp_generate_sdes(), ast_rtcp_write(), ast_rtp_read(), ast_sip_publish_client_alloc_datastore(), ast_sip_session_alloc_datastore(), ast_sorcery_alloc(), AST_TEST_DEFINE(), ast_uuid_to_str(), ast_websocket_uri_cb(), asterisk_daemon(), bridge_base_init(), bridge_moh_create(), build_entity_id(), endpoint_lookup(), exchangecal_write_event(), generate_exchange_uuid(), handle_show_settings(), mock_retrieve_multiple(), playback_create(), sorcery_memory_cache_thrash_retrieve(), sorcery_memory_cache_thrash_update(), and stir_shaken_add_origid().

Function Documentation

ast_str_to_uuid()

struct ast_uuid* ast_str_to_uuid

(

char *

str

)

Convert a string to a UUID.

This function allocates memory on the heap. The returned pointer must be freed using ast_free()

Parameters

str	The string to convert to a UUID

Return values

NULL	Failed to convert
non-NULL	The heap-allocated converted UUID

Definition at line 151 of file uuid.c.

References ast_free, ast_log, ast_malloc, LOG_WARNING, NULL, and ast_uuid::uu.

Referenced by AST_TEST_DEFINE(), and is_valid_uuid().

{
 struct ast_uuid *uuid = ast_malloc(sizeof(*uuid));
 int res;

 if (!uuid) {
 return NULL;
 }
 res = uuid_parse(str, uuid->uu);
 if (res) {
 ast_log(LOG_WARNING, "Unable to convert string %s into a UUID\n", str);
 ast_free(uuid);
 return NULL;
 }
 return uuid;
}

ast_uuid_clear()

void ast_uuid_clear

(

struct ast_uuid *

uuid

)

Clear a UUID by setting it to be a nil UUID (all 0s)

Parameters

uuid	UUID to clear

Definition at line 184 of file uuid.c.

References ast_uuid::uu.

Referenced by AST_TEST_DEFINE().

{
 uuid_clear(uuid->uu);
}

ast_uuid_compare()

int ast_uuid_compare	(	struct ast_uuid *	left,
		struct ast_uuid *	right
	)

Compare two UUIDs.

Parameters

left	First UUID to compare
right	Second UUID to compare

Return values

<0	left is lexicographically less than right
0	left and right are the same
>0	left is lexicographically greater than right

Definition at line 179 of file uuid.c.

References ast_uuid::uu.

Referenced by AST_TEST_DEFINE().

{
 return uuid_compare(left->uu, right->uu);
}

ast_uuid_copy()

struct ast_uuid* ast_uuid_copy

(

struct ast_uuid *

src

)

Make a copy of a UUID.

This function allocates memory on the heap. The returned pointer must be freed using ast_free()

Parameters

src	The source UUID to copy

Return values

NULL	Failed to copy
non-NULL	The heap-allocated duplicate UUID

Definition at line 168 of file uuid.c.

References ast_malloc, NULL, and ast_uuid::uu.

Referenced by AST_TEST_DEFINE().

{
 struct ast_uuid *dst = ast_malloc(sizeof(*dst));

 if (!dst) {
 return NULL;
 }
 uuid_copy(dst->uu, src->uu);
 return dst;
}

ast_uuid_generate()

struct ast_uuid* ast_uuid_generate

(

void

)

Generate a UUID.

This function allocates memory on the heap. The returned pointer must be freed using ast_free()

Return values

NULL	Generation failed
non-NULL	heap-allocated UUID

Definition at line 125 of file uuid.c.

References ast_malloc, generate_uuid(), and NULL.

Referenced by AST_TEST_DEFINE().

{
 struct ast_uuid *uuid = ast_malloc(sizeof(*uuid));

 if (!uuid) {
 return NULL;
 }
 generate_uuid(uuid);
 return uuid;
}

ast_uuid_generate_str()

char* ast_uuid_generate_str	(	char *	buf,
		size_t	size
	)

Generate a UUID string.

Since

12.0.0

Parameters

buf	The buffer where the UUID string will be stored
size	The size of the buffer. Must be at least AST_UUID_STR_LEN.

Returns

The UUID string (a pointer to buf)

Definition at line 143 of file uuid.c.

References ast_uuid_to_str(), and generate_uuid().

Referenced by add_msid_to_stream(), ast_datastores_alloc_datastore(), ast_rtp_new(), ast_sip_publish_client_alloc_datastore(), ast_sip_session_alloc_datastore(), ast_sorcery_alloc(), AST_TEST_DEFINE(), ast_websocket_uri_cb(), asterisk_daemon(), bridge_base_init(), build_entity_id(), generate_exchange_uuid(), mock_retrieve_multiple(), playback_create(), sorcery_config_open(), and stir_shaken_add_origid().

{
 struct ast_uuid uuid;

 generate_uuid(&uuid);
 return ast_uuid_to_str(&uuid, buf, size);
}

ast_uuid_init()

void ast_uuid_init

(

void

)

Initialize the UUID system.

Definition at line 194 of file uuid.c.

References ast_debug, ast_log, dev_urandom_fd, has_dev_urandom, LOG_WARNING, and ast_uuid::uu.

Referenced by asterisk_daemon().

{
 /* This requires some explanation.
 *
 * libuuid generates UUIDs based on random number generation. This involves
 * opening a handle to /dev/urandom or /dev/random in order to get random
 * data for the UUIDs.
 *
 * This is thread-safe, to a point. The problem is that the first attempt
 * to generate a UUID will result in opening the random number handle. Once
 * the handle is opened, all further generation is thread safe. This
 * first generation can be potentially risky if multiple threads attempt
 * to generate a UUID at the same time, though, since there is no thread
 * synchronization used within libuuid. To get around this potential
 * issue, we go ahead and generate a UUID up front so that the underlying
 * work is done before we start requesting UUIDs for real.
 *
 * Think of this along the same lines as initializing a singleton.
 */
 uuid_t uu;
 int dev_urandom_fd;

 dev_urandom_fd = open("/dev/urandom", O_RDONLY);
 if (dev_urandom_fd < 0) {
 ast_log(LOG_WARNING, "It appears your system does not have /dev/urandom on it. This\n"
 "means that UUID generation will use a pseudorandom number generator. Since\n"
 "the thread-safety of your system's random number generator cannot\n"
 "be guaranteed, we have to synchronize UUID generation. This may result\n"
 "in decreased performance. It is highly recommended that you set up your\n"
 "system to have /dev/urandom\n");
 } else {
 has_dev_urandom = 1;
 close(dev_urandom_fd);
 }
 uuid_generate_random(uu);

 ast_debug(1, "UUID system initiated\n");
}

ast_uuid_is_nil()

int ast_uuid_is_nil

(

struct ast_uuid *

uuid

)

Check if a UUID is a nil UUID (all 0s)

Parameters

uuid	UUID to check

Return values

0	The UUID is not nil
non-zero	The UUID is nil

Definition at line 189 of file uuid.c.

References ast_uuid::uu.

Referenced by AST_TEST_DEFINE().

{
 return uuid_is_null(uuid->uu);
}

ast_uuid_to_str()

char* ast_uuid_to_str	(	struct ast_uuid *	uuid,
		char *	buf,
		size_t	size
	)

Convert a UUID to a string.

Parameters

	uuid	The UUID to convert to a string
[out]	buf	The buffer where the UUID string will be stored
	size	The size of the buffer. Must be at least AST_UUID_STR_LEN.

Returns

The UUID string (a pointer to buf)

Definition at line 136 of file uuid.c.

References ast_assert, ast_str_to_lower(), AST_UUID_STR_LEN, and ast_uuid::uu.

Referenced by AST_TEST_DEFINE(), and ast_uuid_generate_str().

{
 ast_assert(size >= AST_UUID_STR_LEN);
 uuid_unparse(uuid->uu, buf);
 return ast_str_to_lower(buf);
}