EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
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]bufBuffer into which to pack the Root Layer PDU block.
[in]buflenSize in bytes of buf.
[in]pdu_blockArray of AcnRootLayerPdu representing the PDU block to pack.
[in]num_pdusNumber 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]bufBuffer into which to pack the Root Layer PDU header.
[in]buflenSize in bytes of buf. Buffer should be at least of size ACN_RLP_HEADER_SIZE_EXT_LEN.
[in]pduPDU 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]bufBuffer into which to pack the preamble.
[in]buflenSize in bytes of buf. Buffer should be at least of length ACN_TCP_PREAMBLE_SIZE.
[in]rlp_block_lenFull 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]bufBuffer into which to pack the preamble.
[in]buflenSize 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]bufRoot Layer Protocol buffer.
[in]buflenSize in bytes of buf.
[in]pduStruct to contain parsed PDU header.
[in]last_pduThe 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
{
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);
#define ACN_PDU_INIT
Default AcnPdu initializer values; must be used to intialize an AcnPdu when parsing the first PDU in ...
Definition: acn_pdu.h:172
bool acn_parse_root_layer_pdu(const uint8_t *buf, size_t buflen, AcnRootLayerPdu *pdu, AcnPdu *last_pdu)
Parse an ACN Root Layer PDU.
Definition: acn_rlp.c:222
Holds state data used when parsing multiple PDUs in a PDU block.
Definition: acn_pdu.h:162
Holds the information contained in an ACN Root Layer PDU.
Definition: acn_rlp.h:96
Parameters
[in]bufRoot Layer Protocol buffer.
[in]buflenSize in bytes of buf.
[out]pduStruct to contain parsed PDU.
[in,out]last_pduState 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]bufReceived TCP buffer.
[in]buflenSize in bytes of buf.
[out]preambleStruct 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]bufReceived UDP buffer.
[in]buflenSize in bytes of buf.
[out]preambleStruct 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_blockArray of structs representing a Root Layer PDU block.
[in]num_pdusSize of the pdu_block array.
Returns
Buffer size to allocate.