Functions visible to all files that include the library header file. More...

Collaboration diagram for Public 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

Functions visible to all files that include the library header file.

Function Documentation

◆ snap_init()

int16_t snap_init	(	snap_frame_t *	frame,
		uint8_t *	buffer,
		const uint16_t	maxSize
	)

Initialize the frame structure.

A frame structure should be initialized before passing it to other functions. On success, store the buffer pointer and size, and clear the other frame variables. On error, the structure remains unchanged.

Parameters

[out]	frame	Pointer to the frame structure.
[in]	buffer	Pointer to the array that will store the frame bytes.
[in]	maxSize	Maximum number of bytes that can be stored in the buffer. It must be a value from SNAP_MIN_SIZE_FRAME to SNAP_MAX_SIZE_FRAME. If necessary, it will be limited to SNAP_MAX_SIZE_FRAME without generating error.

Return values

>0	Return the actual maxSize used.
SNAP_ERROR_NULL_FRAME	Error: Frame pointer is NULL.
SNAP_ERROR_NULL_BUFFER	Error: Buffer pointer is NULL.
SNAP_ERROR_SHORT_BUFFER	Error: maxSize is less than the minimum allowed (SNAP_MIN_SIZE_FRAME).

◆ snap_reset()

void snap_reset ( snap_frame_t * frame )

Reset the frame size and status. The other variables of the frame remain unchanged.

This function should be called after decoding a frame, prior to decoding a new frame. After executing this function, the frame will be considered empty, even though the buffer still holds the previous frame bytes.

Parameters

[out] frame Pointer to the frame structure.

◆ snap_decode()

int8_t snap_decode	(	snap_frame_t *	frame,
		const uint8_t	newByte
	)

Detect, decode, validate and store a frame, one byte at a time.

All input bytes before a sync byte will be ignored. When a new byte is inserted into the buffer, the frame size and status are updated accordingly. All input bytes after a valid frame or any error will be ignored. Prior to decoding a new frame, the frame status must be SNAP_STATUS_IDLE. This can be achieved with snap_reset(). See snap_status_t for more details.

Parameters

[in,out]	frame	Pointer to the frame structure.
[in]	newByte	Byte to be decoded and inserted into the frame buffer.

Returns: Frame status after the process. It can be any value from snap_status_t.

Here is the call graph for this function:

◆ snap_encapsulate()

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.

Parameters

[in,out]	frame	Pointer to the frame structure.
[in,out]	fields	Pointer to the structure that contains every data needed to build the frame. Fields that do not match the frame format will be ignored. The NDB value is always ignored because it will be calculated from the data size. If data pointer is NULL or data size is zero, the frame will have no payload. It is safe to use the same array as data and frame buffer (safe copy).

Returns: Frame status after the process (value from snap_status_t).

Return values

SNAP_STATUS_VALID	Frame created successfully. Frame size is updated to match the new frame.
SNAP_STATUS_ERROR_OVERFLOW	Error: Frame does not fit in the buffer. Buffer remains unchanged. Frame size is changed to zero.

Here is the call graph for this function:

◆ snap_getField()

int16_t snap_getField	(	const snap_frame_t *	frame,
		void *	fieldContent,
		const uint8_t	fieldType
	)

Get the content of a selected frame field.

Parameters

[in]	frame	Pointer to the frame structure.
[out]	fieldContent	Pointer to the variable that will store the field value. In case of error, the variable remains unchanged. To get the header, the pointer must point to a snap_header_t. To get the destination address, source address, hash value or protocol flags, the pointer must point to a uint32_t. To get the data/payload, the pointer must point to an array of uint8_t (it must be large enough to hold all the bytes).
[in]	fieldType	Selects the field whose content should be returned. It must be a value from snap_fieldType_t.

Return values

>0	Return the size (bytes) of the field.
SNAP_ERROR_UNKNOWN_FORMAT	Error: Frame header is not complete.
SNAP_ERROR_FRAME_FORMAT	Error: Frame format does not have the requested field.
SNAP_ERROR_SHORT_FRAME	Error: Frame format has the requested field, but it is incomplete or empty.
SNAP_ERROR_FIELD_TYPE	Error: Invalid field type value.

Here is the caller graph for this function:

◆ snap_calculateHash()

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.

Parameters

[in]	frame	Pointer to the frame structure.
[out]	hash	Pointer to the variable that will store the hash value. In case of error, the variable remains unchanged.

Return values

>0	Return the size (bytes) of the hash value.
SNAP_ERROR_UNKNOWN_FORMAT	Error: Frame header is not complete.
SNAP_ERROR_FRAME_FORMAT	Error: Frame format does not have a hash value.
SNAP_ERROR_SHORT_FRAME	Error: Frame format has a hash value, but it is incomplete or empty.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ snap_removePaddingBytes()

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

If the payload has 8 bytes or less, the frame is not supposed to have padding bytes, hence nothing will be done.

Parameters

[out]	data	Pointer to the full payload of the frame.
[in]	size	Number of bytes in the payload (including the padding bytes).
[in]	paddingAfter	Position of the padding bytes in the payload. `true:` Padding after data. WARNING: If the actual data ends with padding bytes, they also will be discarded. `false:` Padding before data. WARNING: If the actual data starts with padding bytes, they also will be discarded.

Returns: Number of actual data bytes (excluding padding bytes).

◆ snap_getNdbFromDataSize()

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

Parameters

[in] dataSize Number of data bytes. It must be a value from 0 to 512.

Returns: NDB value (snap_hdb1_ndb_t). It will be a value from 0 to 14.

Here is the caller graph for this function:

◆ snap_getDataSizeFromNdb()

uint16_t snap_getDataSizeFromNdb ( const uint8_t ndb )

Get the number of data bytes based on the NDB bits of the HDB1 byte.

Parameters

[in] ndb NDB value (snap_hdb1_ndb_t). It must be a value from 0 to 14.

Returns: Number of data bytes (including padding bytes).

Here is the caller graph for this function:

◆ snap_getHashSizeFromEdm()

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.

Parameters

[in] edm EDM value (snap_hdb1_edm_t). Only 3 bits (LSb) will be considered.

Returns: Hash value size. It will be a value from 0 to 4.

Here is the caller graph for this function:

◆ snap_calculateChecksum8()

uint8_t snap_calculateChecksum8	(	const uint8_t *	data,
		const uint16_t	size
	)

Calculate the 8-bit checksum of a byte array.

Parameters

[in]	data	Pointer to the byte array used in the calculation.
[in]	size	Number of bytes used in the calculation.

Returns: Result.

Here is the caller graph for this function:

◆ snap_calculateCrc8()

uint8_t snap_calculateCrc8	(	const uint8_t *	data,
		const uint16_t	size
	)

Calculate the 8-bit CRC of a byte array.

This "weak" function can be overridden by a user implementation, especially when a hardware implementation is available. If the macro SNAP_CRC8_TABLE is defined, this function will use a 256-byte lookup table to speed up the calculation. If the macro SNAP_DISABLE_WEAK is defined, this function becomes a "strong" definition, so the only way to override it is to define the macro SNAP_OVERRIDE_CRC8. The algorithm can be described according to the Rocksoft^tm Model CRC Algorithm by Ross Williams:

Name	Width	Poly	Init	RefIn	RefOut	XorOut	Check
CRC-8/MAXIM-DOW	8	0x31	0x00	True	True	0x00	0xA1

Parameters

[in]	data	Pointer to the byte array used in the calculation.
[in]	size	Number of bytes used in the calculation.

Returns: Result.

Here is the caller graph for this function:

◆ snap_calculateCrc16()

uint16_t snap_calculateCrc16	(	const uint8_t *	data,
		const uint16_t	size
	)

Calculate the 16-bit CRC of a byte array.

This "weak" function can be overridden by a user implementation, especially when a hardware implementation is available. If the macro SNAP_CRC16_TABLE is defined, this function will use a 512-byte lookup table to speed up the calculation. If the macro SNAP_DISABLE_WEAK is defined, this function becomes a "strong" definition, so the only way to override it is to define the macro SNAP_OVERRIDE_CRC16. The algorithm can be described according to the Rocksoft^tm Model CRC Algorithm by Ross Williams:

Name	Width	Poly	Init	RefIn	RefOut	XorOut	Check
CRC-16/XMODEM	16	0x1021	0x0000	False	False	0x0000	0x31C3

Parameters

[in]	data	Pointer to the byte array used in the calculation.
[in]	size	Number of bytes used in the calculation.

Returns: Result.

Here is the caller graph for this function:

◆ snap_calculateCrc32()

uint32_t snap_calculateCrc32	(	const uint8_t *	data,
		const uint16_t	size
	)

Calculate the 32-bit CRC of a byte array.

This "weak" function can be overridden by a user implementation, especially when a hardware implementation is available. If the macro SNAP_CRC32_TABLE is defined, this function will use a 1024-byte lookup table to speed up the calculation. If the macro SNAP_DISABLE_WEAK is defined, this function becomes a "strong" definition, so the only way to override it is to define the macro SNAP_OVERRIDE_CRC32. The algorithm can be described according to the Rocksoft^tm Model CRC Algorithm by Ross Williams:

Name	Width	Poly	Init	RefIn	RefOut	XorOut	Check
CRC-32/ISO-HDLC	32	0x04C11DB7	0xFFFFFFFF	True	True	0xFFFFFFFF	0xCBF43926

Parameters

[in]	data	Pointer to the byte array used in the calculation.
[in]	size	Number of bytes used in the calculation.

Returns: Result.

Here is the caller graph for this function:

◆ snap_calculateUserHash()

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.

This "weak" function is supposed to be overridden by a user implementation. It will be selected and called automatically by the function snap_calculateHash() when the EDM value is equal to SNAP_HDB1_EDM_USER_SPECIFIED. If the macro SNAP_DISABLE_WEAK is defined, this function becomes a "strong" definition, so the only way to override it is to define the macro SNAP_OVERRIDE_USER_HASH.

Parameters

[in]	data	Pointer to the byte array used in the calculation.
[in]	size	Number of bytes used in the calculation.

Returns: Result.

Here is the caller graph for this function:

Functions that require a frame structure (snap_frame_t)

Functions that do NOT require a frame structure

Detailed Description

Function Documentation

◆ snap_init()

◆ snap_reset()

◆ snap_decode()

◆ snap_encapsulate()

◆ snap_getField()

◆ snap_calculateHash()

◆ snap_removePaddingBytes()

◆ snap_getNdbFromDataSize()

◆ snap_getDataSizeFromNdb()

◆ snap_getHashSizeFromEdm()

◆ snap_calculateChecksum8()

◆ snap_calculateCrc8()

◆ snap_calculateCrc16()

◆ snap_calculateCrc32()

◆ snap_calculateUserHash()