lwpa_cid

Overview

Type and helper functions for the Component IDentifier (CID) used in the ACN family of protocols.

ACN-based protocols use an identifier called a CID to identify a Component, which E1.17 defines as "a distinct endpoint transmitting and receiving ACN data". A CID is simply a UUID which should not change over the lifetime of a device. To this end, functions are provided which help with CID generation.

#include "lwpa_cid.h"

Data Structures
struct	LwpaCid
	The CID type. More...

Macros
#define	CID_BYTES   16u
	The number of bytes that make up a CID.
#define	cidcmp(cid1ptr, cid2ptr)   memcmp((cid1ptr)->data, (cid2ptr)->data, CID_BYTES)
	Compare two CIDs. More...
#define	cid_isnull(cidptr)   (memcmp((cidptr)->data, NULL_CID.data, CID_BYTES) == 0)
	Determine if a CID is null. More...
#define	CID_STRING_BYTES   37
	The maximum number of bytes required to hold an ASCII string representation of a CID.

Typedefs
typedef struct LwpaCid	LwpaCid
	The CID type. More...

Functions
void	cid_to_string (char *buf, const LwpaCid *cid)
	Create a string representation of a CID. More...
bool	string_to_cid (LwpaCid *cid, const char *buf, size_t buflen)
	Create a CID from a string representation. More...
void	generate_cid (LwpaCid *cid, const char *devstr, const uint8_t *macaddr, uint32_t cidnum)
	Generate a CID from a combination of a custom string and MAC address. More...
void	generate_rdm_cid (LwpaCid *cid, const uint8_t *rdmuid)
	Generate a CID from an RDM UID. More...

Variables
const LwpaCid	NULL_CID
	A null (all 0's) CID, used by cid_isnull() for comparison.

Macro Definition Documentation

cid_isnull

#define cid_isnull

(

cidptr

)

(memcmp((cidptr)->data, NULL_CID.data, CID_BYTES) == 0)

Determine if a CID is null.

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

Parameters

cidptr

Pointer to CID to null-check.

Returns

true (CID is null) or false (CID is not null).

cidcmp

#define cidcmp	(		cid1ptr,
			cid2ptr
	)		memcmp((cid1ptr)->data, (cid2ptr)->data, CID_BYTES)

Compare two CIDs.

Parameters

cid1ptr	Pointer to first LwpaCid to compare.
cid2ptr	Pointer to second LwpaCid to compare.

Returns

< 0 (cid1ptr is less than cid2ptr)
0 (cid1ptr is equal to cid2ptr)
> 0 (cid1ptr is greater than cid2ptr)

Typedef Documentation

LwpaCid

typedef struct LwpaCid LwpaCid

The CID type.

Note that this can also be used to identify a DCID, as defined in DDL (or, for that matter, a UUID used for any other purpose).

Function Documentation

cid_to_string()

void cid_to_string	(	char *	buf,
		const LwpaCid *	cid
	)

Create a string representation of a CID.

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

[out]	buf	Character buffer to which to write the resulting string. To avoid undefined behavior, this buffer should be at least of size CID_STRING_BYTES.
[in]	cid	CID to convert to a string.

generate_cid()

void generate_cid	(	LwpaCid *	cid,
		const char *	devstr,
		const uint8_t *	macaddr,
		uint32_t	cidnum
	)

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

This function is for use by devices that want to create their own cids, and create the same CIDs each time. The CID output is deterministic for each combination of devstr, macaddr and cidnum inputs.

Parameters

[out]	cid	CID to fill in with the generation result.
[in]	devstr	The 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 CID sets.
[in]	macaddr	The device's MAC address as an array of 6 bytes.
[in]	cidnum	Component number. By changing this number, multiple unique CIDs can be generated for the same device string- MAC address combination.

generate_rdm_cid()

void generate_rdm_cid	(	LwpaCid *	cid,
		const uint8_t *	rdmuid
	)

Generate a CID from an RDM UID.

This function is used to consistently create the same CID for an RDM device, regardless of the ACN component/location in which the device is being instanced.

Parameters

[out]	cid	CID to fill in with the generation result.
[in]	rdmuid	The 6-byte RDM unique identifier. The first 2 bytes are the manufacturer ID, and the last 4 bytes are the device ID.

string_to_cid()

bool string_to_cid	(	LwpaCid *	cid,
		const char *	buf,
		size_t	buflen
	)

Create a CID from a string representation.

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

Parameters

[out]	cid	CID to fill in with the parse result.
[in]	buf	Character buffer containing the string to convert.
[in]	buflen	Size in bytes of buf.

Returns

true (parse successful) or false (parse failure).