Header file of the libSNAP library. Refer to the library documentation for details. More...

#include <stdint.h>
#include <stdbool.h>

Include dependency graph for snap.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	snap_header_t
	Bit field that stores every field of the frame header. It defines the format of the frame. More...

struct	snap_fields_t
	Structure that stores every data necessary to build a new frame (i.e. every field value and size, except the hash bytes). More...

struct	snap_frame_t
	This is the main structure of the library, used in frame decoding, encapsulation, and decapsulation. More...

Macros
Error codes returned from functions
#define	SNAP_ERROR_NULL_FRAME (-1)
	Null frame pointer.

#define	SNAP_ERROR_NULL_BUFFER (-2)
	Null buffer pointer.

#define	SNAP_ERROR_SHORT_BUFFER (-3)
	Buffer size is smaller than the minimum frame size allowed.

#define	SNAP_ERROR_UNKNOWN_FORMAT (-4)
	Frame header is not complete, hence it is impossible to know the frame format.

#define	SNAP_ERROR_FRAME_FORMAT (-5)
	Frame format does not have the requested field. Check the frame format (header bytes).

#define	SNAP_ERROR_SHORT_FRAME (-6)
	Frame format has the requested field, but it is incomplete or empty.

#define	SNAP_ERROR_FIELD_TYPE (-7)
	Invalid field type value. It must be a value from snap_fieldType_t.

Bit mask and position of HDB2 fields
#define	SNAP_HDB2_DAB_MASK (0x03U)
	Bit mask of the DAB bits in the HDB2 byte.

#define	SNAP_HDB2_DAB_POS (6U)
	Position of the DAB bits (LSb) in the HDB2 byte.

#define	SNAP_HDB2_SAB_MASK (0x03U)
	Bit mask of the SAB bits in the HDB2 byte.

#define	SNAP_HDB2_SAB_POS (4U)
	Position of the SAB bits (LSb) in the HDB2 byte.

#define	SNAP_HDB2_PFB_MASK (0x03U)
	Bit mask of the PFB bits in the HDB2 byte.

#define	SNAP_HDB2_PFB_POS (2U)
	Position of the PFB bits (LSb) in the HDB2 byte.

#define	SNAP_HDB2_ACK_MASK (0x03U)
	Bit mask of the ACK bits in the HDB2 byte.

#define	SNAP_HDB2_ACK_POS (0U)
	Position of the ACK bits (LSb) in the HDB2 byte.

Bit mask and position of HDB1 fields
#define	SNAP_HDB1_CMD_MASK (0x01U)
	Bit mask of the CMD bit in the HDB1 byte.

#define	SNAP_HDB1_CMD_POS (7U)
	Position of the CMD bit in the HDB1 byte.

#define	SNAP_HDB1_EDM_MASK (0x07U)
	Bit mask of the EDM bits in the HDB1 byte.

#define	SNAP_HDB1_EDM_POS (4U)
	Position of the EDM bits (LSb) in the HDB1 byte.

#define	SNAP_HDB1_NDB_MASK (0x0FU)
	Bit mask of the NDB bits in the HDB1 byte.

#define	SNAP_HDB1_NDB_POS (0U)
	Position of the NDB bits (LSb) in the HDB1 byte.

Header content
#define	SNAP_GET_BITS(integer, mask, pos) (((unsigned int)(integer) >> (pos)) & (mask))
	Get a subset of bits from an integer. More...

#define	SNAP_HDB2(pByteArray) ((pByteArray)[SNAP_INDEX_HDB2])
	Get the HDB2 byte of a frame. More...

#define	SNAP_HDB1(pByteArray) ((pByteArray)[SNAP_INDEX_HDB1])
	Get the HDB1 byte of a frame. More...

#define	SNAP_HDB2_DAB(pByteArray) (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_DAB_MASK, SNAP_HDB2_DAB_POS))
	Get the DAB bits of a frame. More...

#define	SNAP_HDB2_SAB(pByteArray) (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_SAB_MASK, SNAP_HDB2_SAB_POS))
	Get the SAB bits of a frame. More...

#define	SNAP_HDB2_PFB(pByteArray) (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_PFB_MASK, SNAP_HDB2_PFB_POS))
	Get the PFB bits of a frame. More...

#define	SNAP_HDB2_ACK(pByteArray) (SNAP_GET_BITS(SNAP_HDB2(pByteArray), SNAP_HDB2_ACK_MASK, SNAP_HDB2_ACK_POS))
	Get the ACK bits of a frame. More...

#define	SNAP_HDB1_CMD(pByteArray) (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_CMD_MASK, SNAP_HDB1_CMD_POS))
	Get the CMD bit of a frame. More...

#define	SNAP_HDB1_EDM(pByteArray) (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_EDM_MASK, SNAP_HDB1_EDM_POS))
	Get the EDM bits of a frame. More...

#define	SNAP_HDB1_NDB(pByteArray) (SNAP_GET_BITS(SNAP_HDB1(pByteArray), SNAP_HDB1_NDB_MASK, SNAP_HDB1_NDB_POS))
	Get the NDB bits of a frame. More...

Frame and field sizes
#define	SNAP_SIZE_SYNC (1U)
	Size of the sync field.

#define	SNAP_SIZE_HDB2 (1U)
	Size of the HDB2 field.

#define	SNAP_SIZE_HDB1 (1U)
	Size of the HDB1 field.

#define	SNAP_SIZE_HEADER (SNAP_SIZE_HDB2 + SNAP_SIZE_HDB1)
	Size of the header field.

#define	SNAP_SIZE_DATA(pByteArray) (snap_getDataSizeFromNdb(SNAP_HDB1_NDB(pByteArray)))
	Size of the data field based on the NDB bits. More...

#define	SNAP_SIZE_HASH(pByteArray) (snap_getHashSizeFromEdm(SNAP_HDB1_EDM(pByteArray)))
	Size of the hash field based on the EDM bits. More...

#define	SNAP_MIN_SIZE_FRAME (SNAP_SIZE_SYNC + SNAP_SIZE_HEADER)
	Minimum frame size allowed = 1 (sync) + 2 (header).

#define	SNAP_MAX_SIZE_FRAME (528U)
	Maximum frame size allowed = 1 (sync) + 2 (header) + 3 (destination address) + 3 (source address) + 3 (flags) + 512 (data) + 4 (hash).

#define	SNAP_SIZE_USER_HASH (0U)
	Size of the user hash field (0 to 4 bytes). It is supposed to be defined by the user in the compilation command.

Field indexes
#define	SNAP_INDEX_SYNC (0U)
	Index of the sync byte.

#define	SNAP_INDEX_HDB2 (1U)
	Index of the HDB2 byte.

#define	SNAP_INDEX_HDB1 (2U)
	Index of the HDB1 byte.

#define	SNAP_INDEX_DAB (3U)
	Index of the first (MSB) destination address byte (if there are any).

#define	SNAP_INDEX_SAB(pByteArray) (SNAP_INDEX_DAB + SNAP_HDB2_DAB(pByteArray))
	Index of the first (MSB) source address byte (if there are any), based on the frame header. More...

#define	SNAP_INDEX_PFB(pByteArray) (SNAP_INDEX_SAB(pByteArray) + SNAP_HDB2_SAB(pByteArray))
	Index of the first (MSB) protocol flags byte (if there are any), based on the frame header. More...

#define	SNAP_INDEX_DATA(pByteArray) (SNAP_INDEX_PFB(pByteArray) + SNAP_HDB2_PFB(pByteArray))
	Index of the first data byte (if there are any), based on the frame header. More...

#define	SNAP_INDEX_HASH(pByteArray) (SNAP_INDEX_DATA(pByteArray) + SNAP_SIZE_DATA(pByteArray))
	Index of the first (MSB) hash byte (if there are any), based on the frame header. More...

Miscellaneous values
#define	SNAP_BROADCAST_ADDRESS (0U)
	All nodes in the network should accept a packet that has this value as its destination address. No node should have this value as its local address.

#define	SNAP_SYNC (0x54U)
	Value of the sync byte. It is the first byte of every frame.

#define	SNAP_PADDING (0x00U)
	Value of the byte used in payload padding (when the payload size is greater than the actual data size).

Get frame content
#define	snap_getSync() (SNAP_SYNC)
	Get the value of the sync byte.

#define	snap_getHdb2(pFrame) (SNAP_HDB2((pFrame)->buffer))
	Get the HDB2 byte of a frame. More...

#define	snap_getHdb1(pFrame) (SNAP_HDB1((pFrame)->buffer))
	Get the HDB1 byte of a frame. More...

#define	snap_getDab(pFrame) (SNAP_HDB2_DAB((pFrame)->buffer))
	Get the DAB bits of a frame. More...

#define	snap_getSab(pFrame) (SNAP_HDB2_SAB((pFrame)->buffer))
	Get the SAB bits of a frame. More...

#define	snap_getPfb(pFrame) (SNAP_HDB2_PFB((pFrame)->buffer))
	Get the PFB bits of a frame. More...

#define	snap_getAck(pFrame) (SNAP_HDB2_ACK((pFrame)->buffer))
	Get the ACK bits of a frame. More...

#define	snap_getCmd(pFrame) (SNAP_HDB1_CMD((pFrame)->buffer))
	Get the CMD bit of a frame. More...

#define	snap_getEdm(pFrame) (SNAP_HDB1_EDM((pFrame)->buffer))
	Get the EDM bits of a frame. More...

#define	snap_getNdb(pFrame) (SNAP_HDB1_NDB((pFrame)->buffer))
	Get the NDB bits of a frame. More...

#define	snap_getHeader(pFrame, pHeader) (snap_getField(pFrame, pHeader, SNAP_FIELD_HEADER))
	Get the header of a frame. More...

#define	snap_getDestAddress(pFrame, pDestAddr) (snap_getField(pFrame, pDestAddr, SNAP_FIELD_DEST_ADDRESS))
	Get the destination address of a frame. More...

#define	snap_getSourceAddress(pFrame, pSourceAddr) (snap_getField(pFrame, pSourceAddr, SNAP_FIELD_SOURCE_ADDRESS))
	Get the source address of a frame. More...

#define	snap_getProtocolFlags(pFrame, pFlags) (snap_getField(pFrame, pFlags, SNAP_FIELD_PROTOCOL_FLAGS))
	Get the protocol flags of a frame. More...

#define	snap_getData(pFrame, pData) (snap_getField(pFrame, pData, SNAP_FIELD_DATA))
	Get the data bytes of a frame. More...

#define	snap_getHash(pFrame, pHash) (snap_getField(pFrame, pHash, SNAP_FIELD_HASH))
	Get the hash value of a frame. More...

#define	snap_getDataPtr(pFrame) ((pFrame)->buffer + SNAP_INDEX_DATA((pFrame)->buffer))
	Get the pointer to the first data byte of a frame. More...

#define	snap_getBufferPtr(pFrame) ((pFrame)->buffer)
	Get the pointer to the first byte of a frame. More...

#define	snap_getStatus(pFrame) ((pFrame)->status)
	Get the frame status (it can be any value from snap_status_t). More...

Get field indexes
#define	snap_getSyncIndex() (SNAP_INDEX_SYNC)
	Get the index of the sync byte.

#define	snap_getHdb2Index() (SNAP_INDEX_HDB2)
	Get the index of the HDB2 byte.

#define	snap_getHdb1Index() (SNAP_INDEX_HDB1)
	Get the index of the HDB1 byte.

#define	snap_getHeaderIndex() (SNAP_INDEX_HDB2)
	Get the index of the first header byte (HDB2).

#define	snap_getDestAddrIndex() (SNAP_INDEX_DAB)
	Get the index of the first (MSB) destination address byte (if there are any).

#define	snap_getSourceAddrIndex(pFrame) (SNAP_INDEX_SAB((pFrame)->buffer))
	Get the index of the first (MSB) source address byte (if there are any). More...

#define	snap_getProtFlagsIndex(pFrame) (SNAP_INDEX_PFB((pFrame)->buffer))
	Get the index of the first (MSB) protocol flags byte (if there are any). More...

#define	snap_getDataIndex(pFrame) (SNAP_INDEX_DATA((pFrame)->buffer))
	Get the index of the first data byte (if there are any). More...

#define	snap_getHashIndex(pFrame) (SNAP_INDEX_HASH((pFrame)->buffer))
	Get the index of the first (MSB) data byte (if there are any). More...

Get frame and field sizes
#define	snap_getSyncSize() (SNAP_SIZE_SYNC)
	Get the size of the sync field.

#define	snap_getHdb2Size() (SNAP_SIZE_HDB2)
	Get the size of the HDB2 field.

#define	snap_getHdb1Size() (SNAP_SIZE_HDB1)
	Get the size of the HDB1 field.

#define	snap_getHeaderSize() (SNAP_SIZE_HEADER)
	Get the size of the header field.

#define	snap_getDestAddrSize(pFrame) (SNAP_HDB2_DAB((pFrame)->buffer))
	Get the size of the destination address. More...

#define	snap_getSourceAddrSize(pFrame) (SNAP_HDB2_SAB((pFrame)->buffer))
	Get the size of the source address. More...

#define	snap_getProtFlagsSize(pFrame) (SNAP_HDB2_PFB((pFrame)->buffer))
	Get the size of the protocol flags. More...

#define	snap_getDataSize(pFrame) (SNAP_SIZE_DATA((pFrame)->buffer))
	Get the size of the data field. More...

#define	snap_getHashSize(pFrame) (SNAP_SIZE_HASH((pFrame)->buffer))
	Get the size of the hash field. More...

#define	snap_getFrameSize(pFrame) ((pFrame)->size)
	Get the current size of a frame (it may be incomplete). More...

#define	snap_getBufferSize(pFrame) ((pFrame)->maxSize)
	Get the maximum number of bytes that can be stored in the buffer. More...

#define	snap_getFullFrameSize(pFrame) (SNAP_INDEX_HASH((pFrame)->buffer) + SNAP_SIZE_HASH((pFrame)->buffer))
	Get the size of a frame as if it were complete (based on the header). More...

Enumerations
enum	snap_fieldType_t { SNAP_FIELD_HEADER = 0 , SNAP_FIELD_DEST_ADDRESS = 1 , SNAP_FIELD_SOURCE_ADDRESS = 2 , SNAP_FIELD_PROTOCOL_FLAGS = 3 , SNAP_FIELD_DATA = 4 , SNAP_FIELD_HASH = 5 }
	Values that identify each field of a frame. More...

enum	snap_hdb2_dab_t { SNAP_HDB2_DAB_NO_DEST_ADDRESS = 0 , SNAP_HDB2_DAB_1BYTE_DEST_ADDRESS = 1 , SNAP_HDB2_DAB_2BYTE_DEST_ADDRESS = 2 , SNAP_HDB2_DAB_3BYTE_DEST_ADDRESS = 3 }
	Values for the DAB field of the HDB2 header byte. It defines the number of destination address bytes. More...

enum	snap_hdb2_sab_t { SNAP_HDB2_SAB_NO_SOURCE_ADDRESS = 0 , SNAP_HDB2_SAB_1BYTE_SOURCE_ADDRESS = 1 , SNAP_HDB2_SAB_2BYTE_SOURCE_ADDRESS = 2 , SNAP_HDB2_SAB_3BYTE_SOURCE_ADDRESS = 3 }
	Values for the SAB field of the HDB2 header byte. It defines the number of source address bytes. More...

enum	snap_hdb2_pfb_t { SNAP_HDB2_PFB_NO_PROTOCOL_FLAGS = 0 , SNAP_HDB2_PFB_1BYTE_PROTOCOL_FLAGS = 1 , SNAP_HDB2_PFB_2BYTE_PROTOCOL_FLAGS = 2 , SNAP_HDB2_PFB_3BYTE_PROTOCOL_FLAGS = 3 }
	Values for the PFB field of the HDB2 header byte. It defines the number of protocol specific flags bytes. More...

enum	snap_hdb2_ack_t { SNAP_HDB2_ACK_NOT_REQUESTED = 0 , SNAP_HDB2_ACK_REQUESTED = 1 , SNAP_HDB2_ACK_RESPONSE_ACK = 2 , SNAP_HDB2_ACK_RESPONSE_NACK = 3 }
	Values for the ACK field of the HDB2 header byte. It defines if the sending node requests an ACK/NACK packet in return. It also acts as the actual ACK/NACK response sent from the receiving node. More...

enum	snap_hdb1_cmd_t { SNAP_HDB1_CMD_MODE_DISABLED = 0 , SNAP_HDB1_CMD_MODE_ENABLED = 1 }
	Values for the CMD field of the HDB1 header byte. It indicates whether the command mode is enabled or not. More...

enum	snap_hdb1_edm_t { SNAP_HDB1_EDM_NO_ERROR_DETECTION = 0 , SNAP_HDB1_EDM_3_RETRANSMISSION = 1 , SNAP_HDB1_EDM_8BIT_CHECKSUM = 2 , SNAP_HDB1_EDM_8BIT_CRC = 3 , SNAP_HDB1_EDM_16BIT_CRC = 4 , SNAP_HDB1_EDM_32BIT_CRC = 5 , SNAP_HDB1_EDM_FEC = 6 , SNAP_HDB1_EDM_USER_SPECIFIED = 7 }
	Values for the EDM field of the HDB1 header byte. It defines the error detection method used on the frame. More...

enum	snap_hdb1_ndb_t { SNAP_HDB1_NDB_NO_DATA = 0 , SNAP_HDB1_NDB_1BYTE_DATA = 1 , SNAP_HDB1_NDB_2BYTE_DATA = 2 , SNAP_HDB1_NDB_3BYTE_DATA = 3 , SNAP_HDB1_NDB_4BYTE_DATA = 4 , SNAP_HDB1_NDB_5BYTE_DATA = 5 , SNAP_HDB1_NDB_6BYTE_DATA = 6 , SNAP_HDB1_NDB_7BYTE_DATA = 7 , SNAP_HDB1_NDB_8BYTE_DATA = 8 , SNAP_HDB1_NDB_16BYTE_DATA = 9 , SNAP_HDB1_NDB_32BYTE_DATA = 10 , SNAP_HDB1_NDB_64BYTE_DATA = 11 , SNAP_HDB1_NDB_128BYTE_DATA = 12 , SNAP_HDB1_NDB_256BYTE_DATA = 13 , SNAP_HDB1_NDB_512BYTE_DATA = 14 , SNAP_HDB1_NDB_USER_SPECIFIED = 15 }
	Values for the NDB field of the HDB1 header byte. It defines the number of data/payload bytes. More...

enum	snap_status_t { SNAP_STATUS_IDLE = 0 , SNAP_STATUS_INCOMPLETE = 1 , SNAP_STATUS_VALID = 2 , SNAP_STATUS_ERROR_HASH = -1 , SNAP_STATUS_ERROR_OVERFLOW = -2 }
	Values for the frame status. The frame structure will always be in one of these states. More...

Functions
Functions that require a frame structure (snap_frame_t)
int16_t	snap_init (snap_frame_t frame, uint8_t buffer, const uint16_t maxSize)
	Initialize the frame structure. More...

void	snap_reset (snap_frame_t *frame)
	Reset the frame size and status. The other variables of the frame remain unchanged. More...

int8_t	snap_decode (snap_frame_t *frame, const uint8_t newByte)
	Detect, decode, validate and store a frame, one byte at a time. More...

int8_t	snap_encapsulate (snap_frame_t frame, snap_fields_t fields)
	Encapsulate a new frame into the buffer (if there is enough space). Update the frame status and size according to the result. More...

int16_t	snap_getField (const snap_frame_t frame, void fieldContent, const uint8_t fieldType)
	Get the content of a selected frame field. More...

int8_t	snap_calculateHash (const snap_frame_t frame, uint32_t hash)
	Select the error detection method based on the EDM bits and calculate the hash value of a frame. More...

Functions that do NOT require a frame structure
uint16_t	snap_removePaddingBytes (uint8_t *data, uint16_t size, const bool paddingAfter)
	Remove the padding bytes (SNAP_PADDING) of a frame payload (if there are any). More...

uint8_t	snap_getNdbFromDataSize (const uint16_t dataSize)
	Get the NDB bits of the HDB1 byte based on the number of data bytes (with or without padding bytes). More...

uint16_t	snap_getDataSizeFromNdb (const uint8_t ndb)
	Get the number of data bytes based on the NDB bits of the HDB1 byte. More...

uint8_t	snap_getHashSizeFromEdm (const uint8_t edm)
	Get the hash value size of the frame based on the EDM bits of the HDB1 byte. More...

uint8_t	snap_calculateChecksum8 (const uint8_t *data, const uint16_t size)
	Calculate the 8-bit checksum of a byte array. More...

uint8_t	snap_calculateCrc8 (const uint8_t *data, const uint16_t size)
	Calculate the 8-bit CRC of a byte array. More...

uint16_t	snap_calculateCrc16 (const uint8_t *data, const uint16_t size)
	Calculate the 16-bit CRC of a byte array. More...

uint32_t	snap_calculateCrc32 (const uint8_t *data, const uint16_t size)
	Calculate the 32-bit CRC of a byte array. More...

uint32_t	snap_calculateUserHash (const uint8_t *data, const uint16_t size)
	Calculate the hash value of a byte array using a user-defined algorithm. More...

Detailed Description

Header file of the libSNAP library. Refer to the library documentation for details.

Author: Lucas Jadilo

Data Structures

Macros

Enumerations

Functions

Detailed Description