lwpa_rootlayerpdu

Overview

Parse or pack a Root Layer PDU block.

#include "lwpa_rootlayerpdu.h"

Data Structures
struct	TcpPreamble
	Holds the information contained in an ACN TCP Preamble. More...
struct	UdpPreamble
	Holds the information contained in an ACN UDP Preamble. More...
struct	RootLayerPdu
	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	RLP_HEADER_SIZE_NORMAL_LEN   22
	Size of a Root Layer PDU header when the length is less than 4096.
#define	RLP_HEADER_SIZE_EXT_LEN   23
	Size of the Root Layer PDU header when the length is 4096 or greater.

Typedefs
typedef struct TcpPreamble	TcpPreamble
	Holds the information contained in an ACN TCP Preamble.
typedef struct UdpPreamble	UdpPreamble
	Holds the information contained in an ACN UDP Preamble.
typedef struct RootLayerPdu	RootLayerPdu
	Holds the information contained in an ACN Root Layer PDU.

Functions
bool	parse_tcp_preamble (const uint8_t *buf, size_t buflen, TcpPreamble *preamble)
	Parse an ACN TCP Preamble. More...
bool	parse_udp_preamble (const uint8_t *buf, size_t buflen, UdpPreamble *preamble)
	Parse an ACN UDP Preamble. More...
bool	parse_root_layer_header (const uint8_t *buf, size_t buflen, RootLayerPdu *pdu, RootLayerPdu *last_pdu)
	Parse only the header of a Root Layer PDU. More...
bool	parse_root_layer_pdu (const uint8_t *buf, size_t buflen, RootLayerPdu *pdu, LwpaPdu *last_pdu)
	Parse a Root Layer PDU. More...
size_t	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	pack_udp_preamble (uint8_t *buf, size_t buflen)
	Pack an ACN UDP Preamble into a buffer. More...
size_t	root_layer_buf_size (const RootLayerPdu *pdu_block, size_t num_pdus)
	Get the buffer size to allocate for a Root Layer PDU block. More...
size_t	pack_root_layer_header (uint8_t *buf, size_t buflen, const RootLayerPdu *pdu)
	Pack only the header of a Root Layer PDU block into a buffer. More...
size_t	pack_root_layer_block (uint8_t *buf, size_t buflen, const RootLayerPdu *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	VECTOR_ROOT_SDT   ACN_PROTOCOL_SDT
#define	VECTOR_ROOT_DRAFT_E131_DATA   ACN_PROTOCOL_DRAFT_E131_DATA
#define	VECTOR_ROOT_E131_DATA   ACN_PROTOCOL_E131_DATA
#define	VECTOR_ROOT_E131_EXTENDED   ACN_PROTOCOL_E131_EXTENDED
#define	VECTOR_ROOT_LLRP   ACN_PROTOCOL_LLRP
#define	VECTOR_ROOT_BROKER   ACN_PROTOCOL_BROKER
#define	VECTOR_ROOT_RPT   ACN_PROTOCOL_RPT
#define	VECTOR_ROOT_EPT   ACN_PROTOCOL_EPT

Function Documentation

pack_root_layer_block()

size_t pack_root_layer_block	(	uint8_t *	buf,
		size_t	buflen,
		const RootLayerPdu *	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 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 RootLayerPdu representing the PDU block to pack.
[in]	num_pdus	Number of RootLayerPdu 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 root_layer_buf_size(); this is because this function performs more optimizations related to PDU inheritance.

pack_root_layer_header()

size_t pack_root_layer_header	(	uint8_t *	buf,
		size_t	buflen,
		const RootLayerPdu *	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 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).

pack_tcp_preamble()

size_t 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).

pack_udp_preamble()

size_t 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).

parse_root_layer_header()

bool parse_root_layer_header	(	const uint8_t *	buf,
		size_t	buflen,
		RootLayerPdu *	pdu,
		RootLayerPdu *	last_pdu
	)

Parse only the header of a 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).

parse_root_layer_pdu()

bool parse_root_layer_pdu	(	const uint8_t *	buf,
		size_t	buflen,
		RootLayerPdu *	pdu,
		LwpaPdu *	last_pdu
	)

Parse a Root Layer PDU.

Parse a Root Layer PDU from a Root Layer PDU block. Fills in the root_layer_pdu structure with the parsed PDU information, and stores state data in a pdu 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 parse_udp_preamble() or parse_tcp_preamble()), buf points to the data starting after the preamble and buflen is the length parsed from the preamble...

LwpaPdu pdu = PDU_INIT; // Must initialize this!!
bool res = false;
do
{
    RootLayerPdu cur;
    res = 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).

parse_tcp_preamble()

bool parse_tcp_preamble	(	const uint8_t *	buf,
		size_t	buflen,
		TcpPreamble *	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).

parse_udp_preamble()

bool parse_udp_preamble	(	const uint8_t *	buf,
		size_t	buflen,
		UdpPreamble *	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).

root_layer_buf_size()

size_t root_layer_buf_size	(	const RootLayerPdu *	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 pack_root_layer_block(), given an array of struct root_layer_pdu.

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.