Functions for managing Universally Unique Identifiers (UUIDs) and data hashes. More...

Data Structures
struct	roc_uuid_string
	Printable version of a roc_uuid. More...

struct	roc_hash_string
	Printable version of a roc_hash. More...

struct	roc_uuid
	128-bit universally unique identifier. More...

struct	roc_hash
	160-bit data hash. More...

Macros
#define	ROC_NO_TIMESTAMP 0xFFFFFFFFFFFFFFFF
	Default value for roc_template::timestamp, indicating the template was generated from a still image. More...

Typedefs
typedef struct roc_uuid_string	roc_uuid_string
	Printable version of a roc_uuid. More...

typedef struct roc_hash_string	roc_hash_string
	Printable version of a roc_hash. More...

typedef struct roc_uuid	roc_uuid
	128-bit universally unique identifier. More...

typedef roc_uuid	roc_template_id
	Unique identifier for a template.

typedef roc_uuid	roc_person_id
	Unique identifier for a person, the set of templates for the same identity.

typedef roc_uuid	roc_group_id
	Unique identifier for a group, the set of people for which membership is the same.

typedef roc_uuid	roc_camera_id
	Unique identifier for a camera. More...

typedef roc_uuid *	roc_uuid_array

typedef roc_uuid_array	roc_person_id_array
	A dynamically allocated array of roc_person_id. More...

typedef struct roc_hash	roc_hash
	160-bit data hash. More...

typedef roc_hash	roc_media_id
	roc_hash_calc_sha1 of the (encoded) source media file. More...

typedef roc_hash	roc_archive_id
	roc_hash_calc_sha1 of the (encoded) recorded output media file. More...

typedef uint64_t	roc_time
	Time in milliseconds.

Functions
roc_uuid_string	roc_uuid_to_string (roc_uuid uuid)
	Convert a UUID to a string. More...

const char *	roc_uuid_string_cast (const roc_uuid_string *uuid)
	Helper function for printing roc_uuid_string in languages that can't handle fixed-length character arrays intelligently. More...

roc_uuid	roc_uuid_from_string (const char *str)
	Obtain a UUID from a string. More...

roc_uuid	roc_uuid_get_random ()
	Initialize a roc_uuid to a random value. More...

roc_hash_string	roc_hash_to_string (roc_hash hash)
	Convert a hash to a string. More...

const char *	roc_hash_string_cast (const roc_hash_string *hash)
	Helper function for printing roc_hash_string in languages that can't handle fixed-length character arrays intelligently. More...

roc_hash	roc_hash_from_string (const char *str)
	Convert a string to a roc_hash. More...

roc_hash	roc_hash_calc_sha1 (const uint8_t *input_byte_array, size_t length)
	Compute the `SHA-1` hash of a data buffer. More...

roc_hash	roc_hash_calc_sha1_file (const char *file_path)
	Compute a `SHA-1` hash of a file. More...

roc_hash	roc_hash_get_random ()
	Initialize a roc_hash from a random value. More...

unsigned int	qHash (const roc_uuid &a)
	For Qt qHash interoperability.

roc_uuid	roc_uuid_from_bytes (const uint8_t *input_byte_array, size_t length)
	Initialize a roc_uuid from a byte array. More...

roc_uuid	roc_uuid_from_int (uint64_t val)
	Obtain a roc_uuid from an integer value. More...

uint64_t	roc_uuid_to_int (roc_uuid uuid)
	Obtain an integer value from a roc_uuid. More...

roc_uuid	roc_uuid_get_null ()
	Obtain a roc_uuid set to all zeros. More...

bool	roc_uuid_is_null (roc_uuid uuid)
	Check if a roc_uuid is all zeros. More...

bool	roc_uuid_is_equal (roc_uuid a, roc_uuid b)
	Compare two UUIDs for equality. More...

bool	roc_uuid_is_less_than (roc_uuid a, roc_uuid b)
	Compare two UUIDs for order. More...

void	roc_free_uuid_array (roc_uuid_array *uuid_array)
	Deallocate a roc_uuid_array. More...

roc_hash	roc_hash_from_bytes (const uint8_t *input_byte_array, size_t length)
	Initialize a roc_hash from a byte array. More...

roc_hash	roc_hash_get_null ()
	Obtain a roc_hash set to all zeros. More...

bool	roc_hash_is_null (roc_hash hash)
	Check if a roc_hash is all zeros. More...

bool	roc_hash_is_equal (roc_hash a, roc_hash b)
	Compare two hashes for equality. More...

bool	roc_hash_is_less_than (roc_hash a, roc_hash b)
	Compare two hashes for order. More...

roc_hash	roc_hash_from_uuid (roc_uuid uuid)
	Obtain a hash from a UUID. More...

roc_uuid	roc_hash_to_uuid (roc_hash hash)
	Convert from a roc_hash to a roc_uuid. More...

Detailed Description

Functions for managing Universally Unique Identifiers (UUIDs) and data hashes.

Construct UUIDs with roc_uuid_get_random and convert them to/from strings with roc_uuid_to_string / roc_uuid_from_string.

Construct hashes with roc_hash_calc_sha1 and convert them to/from strings with roc_hash_to_string / roc_hash_from_string.

Data Structure Documentation

◆ roc_uuid_string

struct roc_uuid_string

Printable version of a roc_uuid.

The string format is the UUID RFC 4122 style {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} where x is a hex digit.

These strings are fixed-length and thus do not need to be manually freed.

Data Fields
char	data[39]	NULL-terminated string.

◆ roc_hash_string

struct roc_hash_string

Printable version of a roc_hash.

Hexadecimal format. These strings are fixed-length and thus do not need to be manually freed.

Data Fields
char	data[41]	NULL-terminated string.

◆ roc_uuid

struct roc_uuid

128-bit universally unique identifier.

See also: roc_uuid_get_random

Public Member Functions
bool	operator== (const roc_uuid &other) const

bool	operator!= (const roc_uuid &other) const

bool	operator< (const roc_uuid &other) const

	operator bool () const

Data Fields
uint8_t	data [16]
	Internal 128-bit data buffer.

Member Function Documentation

◆ operator==()

bool roc_uuid::operator== ( const roc_uuid & other ) const

inline

See also: roc_uuid_is_equal.

◆ operator!=()

bool roc_uuid::operator!= ( const roc_uuid & other ) const

inline

Negation of roc_uuid_is_equal.

◆ operator<()

bool roc_uuid::operator< ( const roc_uuid & other ) const

inline

See also: roc_uuid_is_less_than.

◆ operator bool()

roc_uuid::operator bool ( ) const

inline

Negation of roc_uuid_is_null.

◆ roc_hash

struct roc_hash

160-bit data hash.

See also: roc_hash_calc_sha1

Public Member Functions
bool	operator== (const roc_hash &other) const

bool	operator!= (const roc_hash &other) const
	Negation of roc_hash_is_equal.

bool	operator< (const roc_hash &other) const

	operator bool () const
	Negation of roc_hash_is_null.

Data Fields
uint8_t	data [20]
	Internal 160-bit data buffer.

Member Function Documentation

◆ operator==()

bool roc_hash::operator== ( const roc_hash & other ) const

inline

See also: roc_hash_is_equal.

◆ operator<()

bool roc_hash::operator< ( const roc_hash & other ) const

inline

See also: roc_hash_is_less_than.

Macro Definition Documentation

◆ ROC_NO_TIMESTAMP

#define ROC_NO_TIMESTAMP 0xFFFFFFFFFFFFFFFF

Default value for roc_template::timestamp, indicating the template was generated from a still image.

Equal to 2^64 - 1.

Typedef Documentation

◆ roc_uuid_string

typedef struct roc_uuid_string roc_uuid_string

Printable version of a roc_uuid.

The string format is the UUID RFC 4122 style {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} where x is a hex digit.

These strings are fixed-length and thus do not need to be manually freed.

◆ roc_hash_string

typedef struct roc_hash_string roc_hash_string

Printable version of a roc_hash.

Hexadecimal format. These strings are fixed-length and thus do not need to be manually freed.

◆ roc_uuid

typedef struct roc_uuid roc_uuid

128-bit universally unique identifier.

See also: roc_uuid_get_random

◆ roc_camera_id

typedef roc_uuid roc_camera_id

Unique identifier for a camera.

See also: roc_media_id roc_archive_id

◆ roc_uuid_array

typedef roc_uuid* roc_uuid_array

A dynamically allocated array of roc_uuid.

Free after use with roc_free_uuid_array.

◆ roc_person_id_array

typedef roc_uuid_array roc_person_id_array

A dynamically allocated array of roc_person_id.

Free after use with roc_free_uuid_array.

◆ roc_hash

typedef struct roc_hash roc_hash

160-bit data hash.

See also: roc_hash_calc_sha1

◆ roc_media_id

typedef roc_hash roc_media_id

roc_hash_calc_sha1 of the (encoded) source media file.

See also: roc_archive_id roc_camera_id

◆ roc_archive_id

typedef roc_hash roc_archive_id

roc_hash_calc_sha1 of the (encoded) recorded output media file.

See also: roc_media_id roc_camera_id

Function Documentation

◆ roc_uuid_to_string()

roc_uuid_string roc_uuid_to_string ( roc_uuid uuid )

Convert a UUID to a string.

Example: roc_uuid uuid = ...;
roc_uuid_string str = roc_uuid_to_string(uuid);

Parameters

[in] uuid Binary UUID representation to convert from.

Remarks: This function is thread-safe.

See also: roc_uuid_from_string roc_uuid_string_cast

◆ roc_uuid_string_cast()

const char* roc_uuid_string_cast ( const roc_uuid_string * uuid )

Helper function for printing roc_uuid_string in languages that can't handle fixed-length character arrays intelligently.

Remarks: This function is thread-safe.

See also: roc_uuid_to_string

◆ roc_uuid_from_string()

roc_uuid roc_uuid_from_string ( const char * str )

Obtain a UUID from a string.

The string format should be as defined in roc_uuid_string. If the conversion fails, the result will be roc_uuid_get_null.

Example: const char *str = ...;
roc_uuid uuid = roc_uuid_from_string(str);

Parameters

[in] str String UUID representation to convert from.

Remarks: This function is thread-safe.

See also: roc_uuid_to_string

◆ roc_uuid_get_random()

roc_uuid roc_uuid_get_random ( )

Initialize a roc_uuid to a random value.

Example: roc_uuid uuid = roc_uuid_get_random();

Remarks: This function is thread-safe.

◆ roc_hash_to_string()

roc_hash_string roc_hash_to_string ( roc_hash hash )

Convert a hash to a string.

Example: roc_hash hash = ...;
roc_hash_string str = roc_hash_to_string(hash);

Parameters

[in] hash Binary hash representation to convert from.

Remarks: This function is thread-safe.

See also: roc_hash_from_string

◆ roc_hash_string_cast()

const char* roc_hash_string_cast ( const roc_hash_string * hash )

Helper function for printing roc_hash_string in languages that can't handle fixed-length character arrays intelligently.

Remarks: This function is thread-safe.

See also: roc_hash_from_string

◆ roc_hash_from_string()

roc_hash roc_hash_from_string ( const char * str )

Convert a string to a roc_hash.

If the conversion fails, the result will be roc_hash_get_null.

Note: str must be a 40 character hexadecimal string, as produced by roc_hash_to_string.

Example: const char *str = ...;
roc_hash hash = roc_hash_from_string(str);

Parameters

[in] str 40-character hexadecimal representation to convert from.

Remarks: This function is reentrant.

See also: roc_hash_to_string

◆ roc_hash_calc_sha1()

roc_hash roc_hash_calc_sha1	(	const uint8_t *	input_byte_array,
		size_t	length
	)

Compute the SHA-1 hash of a data buffer.

If length is 0, the returned hash will be roc_hash_get_null.

Example: const uint8_t *input_byte_array = ...;
size_t length = ...;
roc_hash hash = roc_hash_calc_sha1(input_byte_array, length);

Parameters

[in]	input_byte_array	Data buffer to compute the hash of.
[in]	length	Length of `input_byte_array` in bytes.

Remarks: This function is reentrant.

See also: roc_hash_calc_sha1_file

◆ roc_hash_calc_sha1_file()

roc_hash roc_hash_calc_sha1_file ( const char * file_path )

Compute a SHA-1 hash of a file.

If file_path does not exist, can't be read, or the file is empty then the returned hash will be roc_hash_get_null.

Example: const char *file_path = ...;
roc_hash hash = roc_hash_get_sha1_file(file_path);

Parameters

[in] file_path File to compute the hash of.

Remarks: This function is reentrant.

See also: roc_hash_calc_sha1

◆ roc_hash_get_random()

roc_hash roc_hash_get_random ( )

Initialize a roc_hash from a random value.

Example: roc_hash hash = roc_hash_get_random();

Remarks: This function is thread-safe.

◆ roc_uuid_from_bytes()

roc_uuid roc_uuid_from_bytes	(	const uint8_t *	input_byte_array,
		size_t	length
	)

Initialize a roc_uuid from a byte array.

Initializes the UUID by copying the leading bytes of input_byte_array. If length is less than sixteen, the remaining bytes in uuid will be set to zero. If length is greater than sixteen, the trailing bytes of input_byte_array will be ignored.

Parameters

[in]	input_byte_array	Value to initialize the roc_uuid to.
[in]	length	Length of `input_byte_array`.

Remarks: This function is reentrant.

◆ roc_uuid_from_int()

roc_uuid roc_uuid_from_int ( uint64_t val )

Obtain a roc_uuid from an integer value.

The leading eight bytes of the returned roc_uuid are set to val.

Example: uint64_t val = ...;
roc_uuid uuid = roc_uuid_from_int(val);

Parameters

[in] val Integer value to set the leading bytes of uuid to.

Remarks: This function is thread-safe.

See also: roc_uuid_to_int

◆ roc_uuid_to_int()

uint64_t roc_uuid_to_int ( roc_uuid uuid )

Obtain an integer value from a roc_uuid.

Returns the leading eight bytes of uuid as an unsigned integer.

Example: roc_uuid uuid = ...;
uint64_t val = roc_uuid_to_int(uuid);

Parameters

[in] uuid UUID to return the the leading bytes of of.

Remarks: This function is thread-safe.

See also: roc_uuid_from_int

◆ roc_uuid_get_null()

roc_uuid roc_uuid_get_null ( )

Obtain a roc_uuid set to all zeros.

Example: roc_uuid uuid = roc_uuid_get_null();

Remarks: This function is thread-safe.

See also: roc_uuid_is_null

◆ roc_uuid_is_null()

bool roc_uuid_is_null ( roc_uuid uuid )

Check if a roc_uuid is all zeros.

Example: roc_uuid uuid = ...;
if (roc_uuid_is_null(uuid)) ...;

Parameters

[in] uuid UUID to check for all zeros.

Remarks: This function is thread-safe.

See also: roc_uuid_get_null

◆ roc_uuid_is_equal()

bool roc_uuid_is_equal	(	roc_uuid	a,
		roc_uuid	b
	)

Compare two UUIDs for equality.

Example: roc_uuid a = ...;
roc_uuid b = ...;
if (roc_uuid_is_equal(a, b)) ...;

Parameters

[in]	a	First UUID to compare for equality.
[in]	b	Second UUID to compare for equality.

Remarks: This function is thread-safe.

See also: roc_uuid_is_less_than

◆ roc_uuid_is_less_than()

bool roc_uuid_is_less_than	(	roc_uuid	a,
		roc_uuid	b
	)

Compare two UUIDs for order.

Returns true is

a < b

, false otherwise.

Example: roc_uuid a = ...;
roc_uuid b = ...;
if (roc_uuid_is_less_than(a, b)) ...;

Parameters

[in]	a	First UUID to compare for order.
[in]	b	Second UUID to compare for order.

Remarks: This function is thread-safe.

See also: roc_uuid_is_equal

◆ roc_free_uuid_array()

void roc_free_uuid_array ( roc_uuid_array * uuid_array )

Deallocate a roc_uuid_array.

Parameters

[in] uuid_array Array to deallocate.

Remarks: This function is reentrant.

◆ roc_hash_from_bytes()

roc_hash roc_hash_from_bytes	(	const uint8_t *	input_byte_array,
		size_t	length
	)

Initialize a roc_hash from a byte array.

Initializes the hash by copying the leading bytes of input_byte_array. If length is less than twenty, the remaining bytes in hash will be set to zero. If length is greater than twenty, the trailing bytes of input_byte_array will be ignored.

Parameters

[in]	input_byte_array	Value to set the roc_hash to.
[in]	length	Length of `input_byte_array`.

Remarks: This function is reentrant.

◆ roc_hash_get_null()

roc_hash roc_hash_get_null ( )

Obtain a roc_hash set to all zeros.

Example: roc_hash hash = roc_hash_get_null();

Remarks: This function is thread-safe.

See also: roc_hash_is_null

◆ roc_hash_is_null()

bool roc_hash_is_null ( roc_hash hash )

Check if a roc_hash is all zeros.

Example: roc_hash hash = ...;
if (roc_hash_is_null(hash)) ...;

Parameters

[in] hash Hash to check for all zeros.

Remarks: This function is thread-safe.

See also: roc_hash_is_equal

◆ roc_hash_is_equal()

bool roc_hash_is_equal	(	roc_hash	a,
		roc_hash	b
	)

Compare two hashes for equality.

Example: roc_hash a = ...;
roc_hash b = ...;
if (roc_hash_is_equal(a, b)) ...;

Parameters

[in]	a	First hash to compare for equality.
[in]	b	Second hash to compare for equality.

Remarks: This function is thread-safe.

See also: roc_hash_is_less_than

◆ roc_hash_is_less_than()

bool roc_hash_is_less_than	(	roc_hash	a,
		roc_hash	b
	)

Compare two hashes for order.

Returns true is

a < b

, false otherwise.

Example: roc_hash a = ...;
roc_hash b = ...;
if (roc_hash_is_less_than(a, b)) ...;

Parameters

[in]	a	First hash to compare for order.
[in]	b	Second hash to compare for order.

Remarks: This function is thread-safe.

See also: roc_hash_is_equal

◆ roc_hash_from_uuid()

roc_hash roc_hash_from_uuid ( roc_uuid uuid )

Obtain a hash from a UUID.

Sets the leading sixteen bytes of the resulting hash to uuid, and the trailing four bytes to zero.

Parameters

[in] uuid UUID to convert.

Remarks: This function is thread-safe.

See also: roc_hash_to_uuid

◆ roc_hash_to_uuid()

roc_uuid roc_hash_to_uuid ( roc_hash hash )

Convert from a roc_hash to a roc_uuid.

Sets the resulting UUID to the leading 16 bytes of hash.

Parameters

[in] hash Hash to convert.

Remarks: This function is thread-safe.

See also: roc_hash_from_uuid

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ roc_uuid_string

◆ roc_hash_string

◆ roc_uuid

Public Member Functions

Data Fields

Member Function Documentation

◆ operator==()

◆ operator!=()

◆ operator<()

◆ operator bool()

◆ roc_hash

Public Member Functions

Data Fields

Member Function Documentation

◆ operator==()

◆ operator<()

Macro Definition Documentation

◆ ROC_NO_TIMESTAMP

Typedef Documentation

◆ roc_uuid_string

◆ roc_hash_string

◆ roc_uuid

◆ roc_camera_id

◆ roc_uuid_array

◆ roc_person_id_array

◆ roc_hash

◆ roc_media_id

◆ roc_archive_id

Function Documentation

◆ roc_uuid_to_string()

◆ roc_uuid_string_cast()

◆ roc_uuid_from_string()

◆ roc_uuid_get_random()

◆ roc_hash_to_string()

◆ roc_hash_string_cast()

◆ roc_hash_from_string()

◆ roc_hash_calc_sha1()

◆ roc_hash_calc_sha1_file()

◆ roc_hash_get_random()

◆ roc_uuid_from_bytes()

◆ roc_uuid_from_int()

◆ roc_uuid_to_int()

◆ roc_uuid_get_null()

◆ roc_uuid_is_null()

◆ roc_uuid_is_equal()

◆ roc_uuid_is_less_than()

◆ roc_free_uuid_array()

◆ roc_hash_from_bytes()

◆ roc_hash_get_null()

◆ roc_hash_is_null()

◆ roc_hash_is_equal()

◆ roc_hash_is_less_than()

◆ roc_hash_from_uuid()

◆ roc_hash_to_uuid()