acn_rlp (ACN Root Layer Protocol)

Overview

Parse or pack an ACN Root Layer PDU block.

#include "etcpal/acn_rlp.h"

This module handles building and parsing the ACN Root Layer Protocol, as defined in ANSI E1.17, ACN Architecture document, § 2.6. This protocol is also used by sACN (ANSI E1.31) and RDMnet (ANSI E1.33).

Data Structures
struct	AcnTcpPreamble
	Holds the information contained in an ACN TCP Preamble. More...
struct	AcnUdpPreamble
	Holds the information contained in an ACN UDP Preamble. More...
struct	AcnRootLayerPdu
	Holds the information contained in an ACN Root Layer PDU. More...

Macros
#define	ACN_TCP_PREAMBLE_SIZE   16
	Size of an ACN family TCP preamble.
#define	ACN_UDP_PREAMBLE_SIZE   16
	Size of an ACN family UDP preamble.
#define	ACN_RLP_HEADER_SIZE_NORMAL_LEN   22
	Size of a Root Layer PDU header when the length is less than 4096.
#define	ACN_RLP_HEADER_SIZE_EXT_LEN   23
	Size of the Root Layer PDU header when the length is 4096 or greater.

Typedefs
typedef struct AcnTcpPreamble	AcnTcpPreamble
	Holds the information contained in an ACN TCP Preamble.
typedef struct AcnUdpPreamble	AcnUdpPreamble
	Holds the information contained in an ACN UDP Preamble.
typedef struct AcnRootLayerPdu	AcnRootLayerPdu
	Holds the information contained in an ACN Root Layer PDU.

Functions
bool	acn_parse_tcp_preamble (const uint8_t *buf, size_t buflen, AcnTcpPreamble *preamble)
	Parse an ACN TCP Preamble. More...
bool	acn_parse_udp_preamble (const uint8_t *buf, size_t buflen, AcnUdpPreamble *preamble)
	Parse an ACN UDP Preamble. More...
bool	acn_parse_root_layer_header (const uint8_t *buf, size_t buflen, AcnRootLayerPdu *pdu, AcnRootLayerPdu *last_pdu)
	Parse only the header of an ACN Root Layer PDU. More...
bool	acn_parse_root_layer_pdu (const uint8_t *buf, size_t buflen, AcnRootLayerPdu *pdu, AcnPdu *last_pdu)
	Parse an ACN Root Layer PDU. More...
size_t	acn_pack_tcp_preamble (uint8_t *buf, size_t buflen, size_t rlp_block_len)
	Pack an ACN TCP Preamble into a buffer. More...
size_t	acn_pack_udp_preamble (uint8_t *buf, size_t buflen)
	Pack an ACN UDP Preamble into a buffer. More...
size_t	acn_root_layer_buf_size (const AcnRootLayerPdu *pdu_block, size_t num_pdus)
	Get the buffer size to allocate for a Root Layer PDU block. More...
size_t	acn_pack_root_layer_header (uint8_t *buf, size_t buflen, const AcnRootLayerPdu *pdu)
	Pack only the header of a Root Layer PDU block into a buffer. More...
size_t	acn_pack_root_layer_block (uint8_t *buf, size_t buflen, const AcnRootLayerPdu *pdu_block, size_t num_pdus)
	Pack a Root Layer PDU block into a buffer. More...

Protocol Vectors
Each ACN family protocol is defined by a protocol vector in a Root Layer PDU. These values occupy the vector field of a RootLayerPdu to identify the contents of its data segment.
#define	ACN_VECTOR_ROOT_SDT   ACN_PROTOCOL_SDT
#define	ACN_VECTOR_ROOT_DRAFT_E131_DATA   ACN_PROTOCOL_DRAFT_E131_DATA
#define	ACN_VECTOR_ROOT_E131_DATA   ACN_PROTOCOL_E131_DATA
#define	ACN_VECTOR_ROOT_E131_EXTENDED   ACN_PROTOCOL_E131_EXTENDED
#define	ACN_VECTOR_ROOT_LLRP   ACN_PROTOCOL_LLRP
#define	ACN_VECTOR_ROOT_BROKER   ACN_PROTOCOL_BROKER
#define	ACN_VECTOR_ROOT_RPT   ACN_PROTOCOL_RPT
#define	ACN_VECTOR_ROOT_EPT   ACN_PROTOCOL_EPT

Function Documentation

acn_pack_root_layer_block()

size_t acn_pack_root_layer_block	(	uint8_t *	buf,
		size_t	buflen,
		const AcnRootLayerPdu *	pdu_block,
		size_t	num_pdus
	)

Pack a Root Layer PDU block into a buffer.

The required buffer size can be calculated in advance using acn_root_layer_buf_size().

Parameters

[out]	buf	Buffer into which to pack the Root Layer PDU block.
[in]	buflen	Size in bytes of buf.
[in]	pdu_block	Array of AcnRootLayerPdu representing the PDU block to pack.
[in]	num_pdus	Number of AcnRootLayerPdu that make up the pdu_block array.

Returns

Number of bytes packed (success) or 0 (failure). Note that this might be less than the value returned by acn_root_layer_buf_size(); this is because this function performs more optimizations related to PDU inheritance.

acn_pack_root_layer_header()

size_t acn_pack_root_layer_header	(	uint8_t *	buf,
		size_t	buflen,
		const AcnRootLayerPdu *	pdu
	)

Pack only the header of a Root Layer PDU block into a buffer.

This can be useful when working with stream sockets.

Parameters

[out]	buf	Buffer into which to pack the Root Layer PDU header.
[in]	buflen	Size in bytes of buf. Buffer should be at least of size ACN_RLP_HEADER_SIZE_EXT_LEN.
[in]	pdu	PDU for which to pack the header into a buffer.

Returns

Number of bytes packed (success) or 0 (failure).

acn_pack_tcp_preamble()

size_t acn_pack_tcp_preamble	(	uint8_t *	buf,
		size_t	buflen,
		size_t	rlp_block_len
	)

Pack an ACN TCP Preamble into a buffer.

All ACN protocol family packets sent over TCP must start with a TCP Preamble.

Parameters

[out]	buf	Buffer into which to pack the preamble.
[in]	buflen	Size in bytes of buf. Buffer should be at least of length ACN_TCP_PREAMBLE_SIZE.
[in]	rlp_block_len	Full length in bytes of the Root Layer PDU block that will come after this TCP preamble.

Returns

Number of bytes packed (success) or 0 (failure).

acn_pack_udp_preamble()

size_t acn_pack_udp_preamble	(	uint8_t *	buf,
		size_t	buflen
	)

Pack an ACN UDP Preamble into a buffer.

All ACN protocol family packets sent over UDP must start with a UDP Preamble.

Parameters

[out]	buf	Buffer into which to pack the preamble.
[in]	buflen	Size in bytes of buf. Buffer should be at least of length ACN_UDP_PREAMBLE_SIZE.

Returns

Number of bytes packed (success) or 0 (failure).

acn_parse_root_layer_header()

bool acn_parse_root_layer_header	(	const uint8_t *	buf,
		size_t	buflen,
		AcnRootLayerPdu *	pdu,
		AcnRootLayerPdu *	last_pdu
	)

Parse only the header of an ACN Root Layer PDU.

This can be useful when working with stream sockets.

Parameters

[in]	buf	Root Layer Protocol buffer.
[in]	buflen	Size in bytes of buf.
[in]	pdu	Struct to contain parsed PDU header.
[in]	last_pdu	The last PDU structure that was parsed by this function, or NULL for the first PDU in the block.

Returns

true (PDU was parsed successfully) or false (parse error or no more PDUs in the block).

acn_parse_root_layer_pdu()

bool acn_parse_root_layer_pdu	(	const uint8_t *	buf,
		size_t	buflen,
		AcnRootLayerPdu *	pdu,
		AcnPdu *	last_pdu
	)

Parse an ACN Root Layer PDU.

Parse a Root Layer PDU from a Root Layer PDU block. Fills in the AcnRootLayerPdu structure with the parsed PDU information, and stores state data in a AcnPdu structure for parsing the next PDU in the block, if there is one.

Example usage:

After parsing an ACN protocol family preamble (perhaps by using acn_parse_udp_preamble() or acn_parse_tcp_preamble()), buf points to the data starting after the preamble and buflen is the length parsed from the preamble...

AcnPdu pdu = ACN_PDU_INIT; // Must initialize this!!
bool res = false;
do
{
  AcnRootLayerPdu cur;
  res = acn_parse_root_layer_pdu(buf, buflen, &cur, &pdu);
  if (res)
  {
    // Example application handler function that forwards the pdu appropriately based on
    // vector
    handle_root_layer_pdu(&cur);
  }
} while (res);

Parameters

[in]	buf	Root Layer Protocol buffer.
[in]	buflen	Size in bytes of buf.
[out]	pdu	Struct to contain parsed PDU.
[in,out]	last_pdu	State data for future calls.

Returns

true (PDU was parsed successfully) or false (parse error or no more PDUs in the block).

acn_parse_tcp_preamble()

bool acn_parse_tcp_preamble	(	const uint8_t *	buf,
		size_t	buflen,
		AcnTcpPreamble *	preamble
	)

Parse an ACN TCP Preamble.

Determine whether this byte buffer, received over TCP, starts with an ACN TCP Preamble and thus contains an ACN protocol family packet. For best results, wait until you receive at least ACN_TCP_PREAMBLE_SIZE bytes before calling this function.

Parameters

[in]	buf	Received TCP buffer.
[in]	buflen	Size in bytes of buf.
[out]	preamble	Struct to contain parsed preamble information.

Returns

true (preamble was parsed successfully) or false (buffer too short or buffer does not contain a valid TCP preamble).

acn_parse_udp_preamble()

bool acn_parse_udp_preamble	(	const uint8_t *	buf,
		size_t	buflen,
		AcnUdpPreamble *	preamble
	)

Parse an ACN UDP Preamble.

Determine whether this received UDP datagram contains an ACN protocol family packet by determining whether it starts with the ACN UDP preamble.

Parameters

[in]	buf	Received UDP buffer.
[in]	buflen	Size in bytes of buf.
[out]	preamble	Struct to contain parsed preamble information.

Returns

true (preamble was parsed successfully) or false (buffer too short or buffer does not contain a valid UDP preamble).

acn_root_layer_buf_size()

size_t acn_root_layer_buf_size	(	const AcnRootLayerPdu *	pdu_block,
		size_t	num_pdus
	)

Get the buffer size to allocate for a Root Layer PDU block.

Calculate the buffer size to allocate for a future call to acn_pack_root_layer_block(), given an array of AcnRootLayerPdu.

Parameters

[in]	pdu_block	Array of structs representing a Root Layer PDU block.
[in]	num_pdus	Size of the pdu_block array.

Returns

Buffer size to allocate.