oc_uuid.h File Reference

Generate and work with UUIDs as specified in RFC 4122. More...

#include "oc_export.h"
#include "util/oc_compiler.h"
#include "util/oc_features.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Macros
#define	OC_UUID_ID_SIZE   (16)
	Size of the integer array representation of a UUID. More...
#define	OC_UUID_LEN   (37)
	The length of a UUID string. More...

Functions
void	oc_gen_uuid (oc_uuid_t *uuid)
	Generate a random Universally Unique IDentifier (UUID) More...
void	oc_str_to_uuid (const char *str, oc_uuid_t *uuid)
	Convert a UUID string representation to a 128-bit oc_uuid_t. More...
int	oc_str_to_uuid_v1 (const char *str, size_t str_len, oc_uuid_t *uuid)
	Convert a UUID string representation to a 128-bit oc_uuid_t. More...
bool	oc_uuid_is_empty (oc_uuid_t uuid)
	Check if the uuid is empty. More...
bool	oc_uuid_is_equal (oc_uuid_t first, oc_uuid_t second)
	Compare two uuid values. More...
void	oc_uuid_to_str (const oc_uuid_t *uuid, char *buffer, size_t buflen)
	Convert the 128 bit oc_uuid_t to a string representation. More...
int	oc_uuid_to_str_v1 (const oc_uuid_t *uuid, char *buffer, size_t buflen)
	Convert the 128 bit oc_uuid_t to a string representation. More...

Detailed Description

Generate and work with UUIDs as specified in RFC 4122.

This module implements the generation of version-4 UUIDs based on its specification in RFC 4122, along with routines to convert between their string and binary representations.

Macro Definition Documentation

OC_UUID_ID_SIZE

#define OC_UUID_ID_SIZE   (16)

Size of the integer array representation of a UUID.

OC_UUID_LEN

#define OC_UUID_LEN   (37)

The length of a UUID string.

This is the length of UUID string as specified by RFC 4122.

See also

oc_uuid_to_str

Function Documentation

oc_gen_uuid()

void oc_gen_uuid

(

oc_uuid_t *

uuid

)

Generate a random Universally Unique IDentifier (UUID)

This will return a 128 bit version 4 UUID as specified by RFC 4122.

Version 4 UUID is created using random or pseudo-random numbers

Example

oc_uuid_t device_uuid = { { 0 } };
oc_gen_uuid(&device_uuid);

Parameters

[out]

uuid

the randomly generated UUID

oc_str_to_uuid()

void oc_str_to_uuid	(	const char *	str,
		oc_uuid_t *	uuid
	)

Convert a UUID string representation to a 128-bit oc_uuid_t.

Note

oc_str_to_uuid has a special case that does not conform to RFC 4122 if the first character of the str is '*' then the first byte of the oc_uuid_t will be set to '*' (0x2A) and the other bytes will be set to zero.

Example

oc_uuid_t uuid;
oc_str_to_uuid("1628fbcc-13ce-4e37-b883-1fd8d2ad945d", &uuid);

Parameters

	str	the UUID string
[out]	uuid	the oc_uuid_t to hold the UUID bits (cannot be NULL).

oc_str_to_uuid_v1()

int oc_str_to_uuid_v1	(	const char *	str,
		size_t	str_len,
		oc_uuid_t *	uuid
	)

Convert a UUID string representation to a 128-bit oc_uuid_t.

Parameters

	str	the UUID string (cannot be NULL)
	str_len	the length of the UUID string
[out]	uuid	the oc_uuid_t to hold the UUID bits.

Returns

-1 if the string is not a valid UUID

1 if the string is the special case ("*") UUID value

OC_UUID_ID_SIZE (size of the uuid) if the string is a valid UUID

See also

oc_str_to_uuid

oc_uuid_is_empty()

bool oc_uuid_is_empty

(

oc_uuid_t

uuid

)

Check if the uuid is empty.

An empty uuid is one that has all its bytes set to zero.

Parameters

uuid	A uuid to be checked

Returns

true if the uuid is empty

false Otherwise

oc_uuid_is_equal()

bool oc_uuid_is_equal	(	oc_uuid_t	first,
		oc_uuid_t	second
	)

Compare two uuid values.

Parameters

first	A uuid value (cannot be NULL)
second	A uuid value (cannot be NULL)

Returns

true If the two uuid values are equal

false Otherwise

oc_uuid_to_str()

void oc_uuid_to_str	(	const oc_uuid_t *	uuid,
		char *	buffer,
		size_t	buflen
	)

Convert the 128 bit oc_uuid_t to a string representation.

See also

oc_uuid_to_str_v1

oc_uuid_to_str_v1()

int oc_uuid_to_str_v1	(	const oc_uuid_t *	uuid,
		char *	buffer,
		size_t	buflen
	)

Convert the 128 bit oc_uuid_t to a string representation.

The string representation of the UUID will be as specified in RFC 4122.

Note

oc_uuid_to_str has a special case that does not conform to RFC 4122 if the first byte of oc_uuid_t is set to '*' (0x2A) this will return a string "*".

Example

oc_uuid_t device_uuid = { { 0 } };
oc_gen_uuid(&device_uuid);
char uuid_str[OC_UUID_LEN] = { 0 };
oc_uuid_to_str_v1(&device_uuid, uuid_str, OC_UUID_LEN);

Parameters

	uuid	A oc_uuid_t to convert to a string (cannot be NULL)
[out]	buffer	A char array that will hold the string representation of the UUID (cannot be NULL)
	buflen	The size of the input buffer. It is recommended to always use OC_UUID_LEN for buflen.

Returns

-1 if the buffer is too small to hold the UUID string.

>0 The number of characters written to the buffer, not including the terminating null character.