EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
uuid (UUIDs)

Overview

Type and helper functions for a Universally Unique Identifier (UUID).

UUIDs (per RFC 4122) are used in several libraries supported by EtcPal. This module contains a type for a UUID and functions to generate, inspect and manipulate them.

#include "etcpal/uuid.h"

The basic UUID type is quite simple - an array of 16 data bytes. Functions are provided to generate every current UUID type except Version 2, which is very rarely used. Additionally, etcpal_generate_os_preferred_uuid() generates the UUID type preferred by the underlying OS, and etcpal_generate_device_uuid() generates a special type of V5 UUID which can be used to identify embedded devices.

Generation of V1 and V4 UUIDs require EtcPal to be compiled with OS abstraction support (the default in most situations).

The basic form of UUID generation is:

{
// uuid now contains a valid Version 1 UUID.
}
@ kEtcPalErrOk
The call was successful, no error occurred.
Definition: error.h:51
etcpal_error_t etcpal_generate_v1_uuid(EtcPalUuid *uuid)
Generate a Version 1 UUID.
Definition: uuid.c:152
The UUID type.
Definition: uuid.h:93

Note: Not all UUID types are available on all systems. V3, V5 and Device UUIDs are guaranteed to be available in all ports of EtcPal, but V1, V4 and os_preferred UUIDs are generally not available on embedded systems:

EtcPal Platform V1 V3 V4 V5 os_preferred device
FreeRTOS No Yes No Yes No Yes
Linux Yes Yes Yes Yes Yes Yes
macOS Yes Yes Yes Yes Yes Yes
MQX No Yes No Yes No Yes
Windows Yes Yes Yes Yes Yes Yes

You can also convert UUIDs to and from strings:

etcpal_string_to_uuid("39713ce1-2320-46aa-b602-4977be36e155", &uuid);
etcpal_uuid_to_string(&uuid, str_buf);
bool etcpal_uuid_to_string(const EtcPalUuid *uuid, char *buf)
Create a string representation of a UUID.
Definition: uuid.c:61
bool etcpal_string_to_uuid(const char *str, EtcPalUuid *uuid)
Create a UUID from a string representation.
Definition: uuid.c:85
#define ETCPAL_UUID_STRING_BYTES
The maximum number of bytes required to hold an ASCII string representation of a UUID.
Definition: uuid.h:121

Data Structures

struct  EtcPalUuid
 The UUID type. More...
 

Macros

#define ETCPAL_UUID_BYTES   16u
 The number of bytes that make up a UUID.
 
#define ETCPAL_UUID_CMP(uuid1ptr, uuid2ptr)   memcmp((uuid1ptr)->data, (uuid2ptr)->data, ETCPAL_UUID_BYTES)
 Compare two UUIDs. More...
 
#define ETCPAL_UUID_IS_NULL(uuidptr)   (memcmp((uuidptr)->data, kEtcPalNullUuid.data, ETCPAL_UUID_BYTES) == 0)
 Determine if a UUID is null. More...
 
#define ETCPAL_UUID_STRING_BYTES   37
 The maximum number of bytes required to hold an ASCII string representation of a UUID.
 
#define ETCPAL_UUID_DEV_STR_MAX_LEN   32
 The maximum length of a device string used as an input to etcpal_generate_device_uuid().
 

Typedefs

typedef struct EtcPalUuid EtcPalUuid
 The UUID type.
 

Functions

bool etcpal_uuid_to_string (const EtcPalUuid *uuid, char *buf)
 Create a string representation of a UUID. More...
 
bool etcpal_string_to_uuid (const char *str, EtcPalUuid *uuid)
 Create a UUID from a string representation. More...
 
etcpal_error_t etcpal_generate_v1_uuid (EtcPalUuid *uuid)
 Generate a Version 1 UUID. More...
 
etcpal_error_t etcpal_generate_v3_uuid (const EtcPalUuid *ns, const void *name, size_t name_len, EtcPalUuid *uuid)
 Generate a Version 3 UUID. More...
 
etcpal_error_t etcpal_generate_v4_uuid (EtcPalUuid *uuid)
 Generate a Version 4 UUID. More...
 
etcpal_error_t etcpal_generate_v5_uuid (const EtcPalUuid *ns, const void *name, size_t name_len, EtcPalUuid *uuid)
 Generate a Version 5 UUID. More...
 
etcpal_error_t etcpal_generate_os_preferred_uuid (EtcPalUuid *uuid)
 Generate the preferred UUID version of the underlying OS. More...
 
etcpal_error_t etcpal_generate_device_uuid (const char *dev_str, const uint8_t *mac_addr, uint32_t uuid_num, EtcPalUuid *uuid)
 Generate a UUID from a combination of a custom string and MAC address. More...
 

Variables

const EtcPalUuid kEtcPalNullUuid
 A null (all 0's) UUID, used by ETCPAL_UUID_IS_NULL() for comparison.
 

Macro Definition Documentation

◆ ETCPAL_UUID_CMP

#define ETCPAL_UUID_CMP (   uuid1ptr,
  uuid2ptr 
)    memcmp((uuid1ptr)->data, (uuid2ptr)->data, ETCPAL_UUID_BYTES)

Compare two UUIDs.

Parameters
uuid1ptrPointer to first EtcPalUuid to compare.
uuid2ptrPointer to second EtcPalUuid to compare.
Returns
< 0: uuid1ptr is less than uuid2ptr
0: uuid1ptr is equal to uuid2ptr
> 0: uuid1ptr is greater than uuid2ptr

◆ ETCPAL_UUID_IS_NULL

#define ETCPAL_UUID_IS_NULL (   uuidptr)    (memcmp((uuidptr)->data, kEtcPalNullUuid.data, ETCPAL_UUID_BYTES) == 0)

Determine if a UUID is null.

A UUID is said to be 'null' when it is made up of all 0's.

Parameters
uuidptrPointer to UUID to null-check.
Returns
true (UUID is null) or false (UUID is not null).

Function Documentation

◆ etcpal_generate_device_uuid()

etcpal_error_t etcpal_generate_device_uuid ( const char *  dev_str,
const uint8_t *  mac_addr,
uint32_t  uuid_num,
EtcPalUuid uuid 
)

Generate a UUID from a combination of a custom string and MAC address.

This function is for use by embedded devices that want to create UUIDs representing themselves, and create the same UUIDs each time. It creates a Version 5 UUID (defined in RFC 4122) within a constant, hardcoded namespace. The UUID output is deterministic for each combination of dev_str, mac_addr and uuid_num inputs.

The namespace UUID used is: 57323103-db01-44b3-bafa-abdee3f37c1a

Parameters
[in]dev_strThe device-specific string, such as the model name. This should never change on the device. It also allows different programs running on the device to generate different UUID sets.
[in]mac_addrThe device's MAC address; must be an array of 6 bytes.
[in]uuid_numComponent number. By changing this number, multiple unique UUIDs can be generated for the same device string-MAC address combination.
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.

◆ etcpal_generate_os_preferred_uuid()

etcpal_error_t etcpal_generate_os_preferred_uuid ( EtcPalUuid uuid)

Generate the preferred UUID version of the underlying OS.

This function uses the underlying OS API to create a UUID of the recommended type per the underlying OS API. In practice, this is often a V4 UUID, although this is not guaranteed.

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.
kEtcPalErrNotImpl: This UUID generation method is not available on this platform.
kEtcPalErrSys: An internal library of system call error occurred.

◆ etcpal_generate_v1_uuid()

etcpal_error_t etcpal_generate_v1_uuid ( EtcPalUuid uuid)

Generate a Version 1 UUID.

This function uses the underlying OS API to create a UUID that is based on a combination of a local MAC address and the current system time. This method guarantees UUID uniqueness across space and time. Some OSes have deprecated this method because it creates a UUID that is traceable to the MAC address of the machine on which it was generated. If this type of security is a concern, etcpal_generate_v4_uuid() should be preferred. If you want to generate UUIDs that are deterministic for a combination of inputs you provide, see etcpal_generate_v3_uuid(), etcpal_generate_v5_uuid() or etcpal_generate_device_uuid().

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.
kEtcPalErrNotImpl: This UUID generation method is not available on this platform.
kEtcPalErrSys: An internal library of system call error occurred.

◆ etcpal_generate_v3_uuid()

etcpal_error_t etcpal_generate_v3_uuid ( const EtcPalUuid ns,
const void *  name,
size_t  name_len,
EtcPalUuid uuid 
)

Generate a Version 3 UUID.

Version 3 UUIDs are "name-based"; they deterministically convert a combination of a "namespace" and "name" to a UUID. A namespace is another UUID of any type which represents a space within which UUIDs generated from different names are unique. A name is opaque data of any length. The same combination of namespace and name will always produce the same Version 3 UUID.

Version 3 UUIDs use the MD5 hashing algorithm to convert their inputs into a UUID. Prefer using etcpal_generate_v5_uuid(), which uses the SHA-1 algorithm instead, if backward compatibility is not an issue.

Parameters
[in]nsUUID to use as a namespace.
[in]nameThe name to convert into a UUID - opaque data.
[in]name_lenThe length in bytes of name.
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.

◆ etcpal_generate_v4_uuid()

etcpal_error_t etcpal_generate_v4_uuid ( EtcPalUuid uuid)

Generate a Version 4 UUID.

This function uses the underlying OS API to create a UUID that is based on random data. The quality of the random data used may differ across platforms. If you want to generate UUIDs that are deterministic for a combination of inputs you provide, see etcpal_generate_v3_uuid().

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.
kEtcPalErrNotImpl: This UUID generation method is not available on this platform.
kEtcPalErrSys: An internal library of system call error occurred.

◆ etcpal_generate_v5_uuid()

etcpal_error_t etcpal_generate_v5_uuid ( const EtcPalUuid ns,
const void *  name,
size_t  name_len,
EtcPalUuid uuid 
)

Generate a Version 5 UUID.

Version 5 UUIDs are "name-based"; they deterministically convert a combination of a "namespace" and "name" to a UUID. A namespace is another UUID of any type which represents a space within which UUIDs generated from different names are unique. A name is opaque data of any length. The same combination of namespace and name will always produce the same Version 5 UUID.

Version 5 UUIDs use the SHA-1 hashing algorithm to convert their inputs into a UUID.

etcpal_generate_device_uuid() provides a specialized form of this function which embedded devices can use to create UUIDs representing themselves.

Parameters
[in]nsUUID to use as a namespace.
[in]nameThe name to convert into a UUID - opaque data.
[in]name_lenThe length in bytes of name.
[out]uuidUUID to fill in with the generation result.
Returns
kEtcPalErrOk: UUID generated successfully.
kEtcPalErrInvalid: Invalid argument provided.

◆ etcpal_string_to_uuid()

bool etcpal_string_to_uuid ( const char *  str,
EtcPalUuid uuid 
)

Create a UUID from a string representation.

Parses a string-represented UUID and fills in a EtcPalUuid structure with the result. The input should be of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (hexadecimal letters can be upper- or lowercase).

Parameters
[in]strThe null-terminated string to convert.
[out]uuidUUID to fill in with the parse result.
Returns
true (parse successful) or false (parse failure).

◆ etcpal_uuid_to_string()

bool etcpal_uuid_to_string ( const EtcPalUuid uuid,
char *  buf 
)

Create a string representation of a UUID.

The resulting string will be of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase is used for hexadecimal letters per RFC 4122 and common convention).

Parameters
[in]uuidUUID to convert to a string.
[out]bufCharacter buffer to which to write the resulting string. To avoid undefined behavior, this buffer must be at least of size ETCPAL_UUID_STRING_BYTES.
Returns
true (conversion successful) or false (invalid argument).