Types and functions for operating with bRAWcap packet buffers. More...

Modules
	Packet Buffer Iterator
	bRAWcap packet buffer iterators.

Macros
#define	BRAWCAP_BUFFER_PACKETS_MAX 100000
	The maximum amount of packets, which can be stored in a packet buffer.

#define	BRAWCAP_BUFFER_PACKETS_MIN 1
	The minimum amount of packets, which a packet buffer must have.

Typedefs
typedef UINT32	brawcap_buffer_packet_count_t
	Type for handling the number of packets which can be stored in a packet buffer.

typedef struct _brawcap_buffer	brawcap_buffer_t
	bRAWcap packet buffer object.

Enumerations
enum	brawcap_buffer_sort_order_t { BRAWCAP_BUFFER_SORT_ORDER_NONE = 0 , BRAWCAP_BUFFER_SORT_ORDER_RISING = 1 , BRAWCAP_BUFFER_SORT_ORDER_FALLING = 2 }
	Buffer sort order. More...

enum	brawcap_buffer_sort_types_t { BRAWCAP_BUFFER_SORT_TYPE_NONE = 0 , BRAWCAP_BUFFER_SORT_TYPE_TIMESTAMP = 1 , BRAWCAP_BUFFER_SORT_TYPE_PAYLOAD = 2 }
	Buffer sort types. More...

enum	brawcap_buffer_sort_endian_t { BRAWCAP_BUFFER_SORT_ENDIAN_BIG = 0 , BRAWCAP_BUFFER_SORT_ENDIAN_LITTLE = 1 }
	Byte order selection for payload sorting. More...

Functions
brawcap_status_t	brawcap_buffer_create (brawcap_buffer_t **const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize, const brawcap_buffer_packet_count_t numPackets)
	Creates a new packet buffer.

brawcap_status_t	brawcap_buffer_free (brawcap_buffer_t *pBuffer)
	Frees the specified packet buffer. When this function is called the specified packet buffer becomes invalid and it´s memory will be released.

brawcap_status_t	brawcap_buffer_clear (brawcap_buffer_t *const pBuffer)
	Clears the specified packet buffer.

brawcap_status_t	brawcap_buffer_add_back (brawcap_buffer_t const pBuffer, const brawcap_packet_t const pPacket)
	Adds the specified packet at the end of the specified packet buffer.

brawcap_status_t	brawcap_buffer_add_front (brawcap_buffer_t const pBuffer, const brawcap_packet_t const pPacket)
	Adds the specified packet at the front of the specified packet buffer.

brawcap_status_t	brawcap_buffer_add_at_index (brawcap_buffer_t const pBuffer, const brawcap_packet_t const pPacket, const brawcap_buffer_packet_count_t index)
	Inserts the specified packet at index/position into the specified packet buffer.

brawcap_status_t	brawcap_buffer_at_index (brawcap_buffer_t const pBuffer, const brawcap_buffer_packet_count_t index, brawcap_packet_t *const pPacket)
	Reads out a buffered packet at the index of the specified packet buffer.

brawcap_status_t	brawcap_buffer_front (brawcap_buffer_t const pBuffer, brawcap_packet_t *const pPacket)
	Reads out the first buffered packet of the specified packet buffer.

brawcap_status_t	brawcap_buffer_back (brawcap_buffer_t const pBuffer, brawcap_packet_t *const pPacket)
	Reads out the last buffered packet of the specified packet buffer.

brawcap_status_t	brawcap_buffer_count (brawcap_buffer_t const pBuffer, brawcap_buffer_packet_count_t const pPacketCount)
	Reads out the number of currently buffered packets in the specified packet buffer.

brawcap_status_t	brawcap_buffer_capacity (brawcap_buffer_t const pBuffer, brawcap_buffer_packet_count_t const pPacketCapacity)
	Reads out the total number of packets which can be buffered by the specified packet buffer. This value represents the packet buffer capacity, which is set during buffer creation.

brawcap_status_t	brawcap_buffer_sort (brawcap_buffer_t *const pBuffer, const brawcap_buffer_sort_order_t order, const brawcap_buffer_sort_types_t type, const brawcap_packet_size_t offset, const brawcap_packet_size_t length, const brawcap_buffer_sort_endian_t endian)
	Sorts packets in a buffer by timestamp or by a payload field.

Detailed Description

Types and functions for operating with bRAWcap packet buffers.

To create a new packet buffer use brawcap_buffer_create. If a packet buffer is not required anymore it shall be deleted with brawcap_buffer_free.

Packet buffers can be used for

Receiving: To use a buffer for receiving on a bRAWcap handle it has to be attached to it. If it shall not be used anymore for receiving it should be detached.
Transmitting: For transmitting a packet buffer, fill up the buffer with packets and than send it on a handle. This will place the buffer into the transmission queue of the specified handle.

Attention: The packet buffer will be locked down after attaching/sending to a specific handle. This means that it cannot be accessed by user application as long as it is pending for transmission or attached for receiving. If the user application tries to access a locked buffer a error will be returned by the specific packet buffer function.

A packet buffer can be accessed if:

It is not attached for receiving.
No transmission is pending.
While receiving - from inside the receive callback.
While transmitting - from inside the transmit callback.

List of examples:

Typedef Documentation

◆ brawcap_buffer_packet_count_t

typedef UINT32 brawcap_buffer_packet_count_t

#include <brawcap_types_shared.h>

Type for handling the number of packets which can be stored in a packet buffer.

The total amount of packets per packet buffer has to be between BRAWCAP_BUFFER_PACKETS_MIN - BRAWCAP_BUFFER_PACKETS_MAX.

◆ brawcap_buffer_t

typedef struct _brawcap_buffer brawcap_buffer_t

#include <brawcap_types_shared.h>

bRAWcap packet buffer object.

The packet buffer object has to be used for each packet buffer module function. Packet buffers can be created and freed.

Enumeration Type Documentation

◆ brawcap_buffer_sort_order_t

enum brawcap_buffer_sort_order_t

#include <brawcap_types_um.h>

Buffer sort order.

This enum defines the sort order for buffer operations.

Enumerator
BRAWCAP_BUFFER_SORT_ORDER_NONE	No sort order.
BRAWCAP_BUFFER_SORT_ORDER_RISING	Rising sort order.
BRAWCAP_BUFFER_SORT_ORDER_FALLING	Falling sort order.

◆ brawcap_buffer_sort_types_t

enum brawcap_buffer_sort_types_t

#include <brawcap_types_um.h>

Buffer sort types.

This enum defines the sort types for buffer operations.

Enumerator
BRAWCAP_BUFFER_SORT_TYPE_NONE	No sorting
BRAWCAP_BUFFER_SORT_TYPE_TIMESTAMP	Sort by receive timestamp
BRAWCAP_BUFFER_SORT_TYPE_PAYLOAD	Sort by payload (specific range/field in packet payload) brawcap_buffer_sort

◆ brawcap_buffer_sort_endian_t

enum brawcap_buffer_sort_endian_t

#include <brawcap_types_um.h>

Byte order selection for payload sorting.

Enumerator
BRAWCAP_BUFFER_SORT_ENDIAN_BIG	Interpret payload bytes as big-endian (network order).
BRAWCAP_BUFFER_SORT_ENDIAN_LITTLE	Interpret payload bytes as little-endian.

Function Documentation

◆ brawcap_buffer_create()

brawcap_status_t brawcap_buffer_create	(	brawcap_buffer_t **const	pBuffer,
		const brawcap_packet_size_t	maxPacketPayloadSize,
		const brawcap_buffer_packet_count_t	numPackets
	)

#include <brawcap.h>

Creates a new packet buffer.

The created buffer can be used for:

Receiving by attaching it.
Transmitting by sending it.

If a buffer is not required anymore it shall be freed.

Parameters

[out]	pBuffer	Will contain the new created packet buffer, afterwards.
[in]	maxPacketPayloadSize	Specifies the max payload byte size for each packet in the buffer. This cannot be changed after buffer creation and controls the memory size required for each packet in the buffer. When trying to set the packet payload of any buffered packet which exceeds this value, it will fail. The value has to be between BRAWCAP_PACKET_SIZE_MIN and BRAWCAP_PACKET_SIZE_MAX.
[in]	numPackets	Specifies how many packets can be stored in the buffer. This value, together with the max packet payload size, will control the total amount of memory required for the packet buffer and cannot be changed after buffer creation. The value has to be between BRAWCAP_BUFFER_PACKETS_MIN and BRAWCAP_BUFFER_PACKETS_MAX.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The specified packet payload or number of packets is invalid.
BRAWCAP_STATUS_ERROR_FAILED	System error occurred (e.g. out of memory).

Examples: 07_receive_buffered_receiver_f.c, 10_transmit_buffered_transmitter_f.c, and 12_buffer_sorting_f.c.

◆ brawcap_buffer_free()

brawcap_status_t brawcap_buffer_free ( brawcap_buffer_t * pBuffer )

#include <brawcap.h>

Frees the specified packet buffer. When this function is called the specified packet buffer becomes invalid and it´s memory will be released.

Warning: Freeing a buffer is not thread safe and the user is responsible for synchronization.

Parameters

[in] pBuffer The packet buffer to be freed.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

Examples: 07_receive_buffered_receiver_f.c, 10_transmit_buffered_transmitter_f.c, and 12_buffer_sorting_f.c.

◆ brawcap_buffer_clear()

brawcap_status_t brawcap_buffer_clear ( brawcap_buffer_t *const pBuffer )

#include <brawcap.h>

Clears the specified packet buffer.

All buffered packets will be cleared. It may be used to reuse a already created packet buffer. For example this can be useful after transmission of the packet buffer has finished. Reusing a buffer improves performance and should be preferred instead of always creating and freeing packet buffers.

Warning: After calling this function all buffered packets in the packet buffer become invalid and shall not be used anymore.

Parameters

[in] pBuffer The packet buffer to be cleared.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

◆ brawcap_buffer_add_back()

brawcap_status_t brawcap_buffer_add_back	(	brawcap_buffer_t *const	pBuffer,
		const brawcap_packet_t *const	pPacket
	)

#include <brawcap.h>

Adds the specified packet at the end of the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to be modified.
[in]	pPacket	The packet to insert into the buffer.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN	The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The packet payload length is to long for the buffer.

Examples: 10_transmit_buffered_transmitter_f.c, and 12_buffer_sorting_f.c.

◆ brawcap_buffer_add_front()

brawcap_status_t brawcap_buffer_add_front	(	brawcap_buffer_t *const	pBuffer,
		const brawcap_packet_t *const	pPacket
	)

#include <brawcap.h>

Adds the specified packet at the front of the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to be modified.
[in]	pPacket	The packet to insert into the buffer.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN	The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The packet payload length is to long for the buffer.

◆ brawcap_buffer_add_at_index()

brawcap_status_t brawcap_buffer_add_at_index	(	brawcap_buffer_t *const	pBuffer,
		const brawcap_packet_t *const	pPacket,
		const brawcap_buffer_packet_count_t	index
	)

#include <brawcap.h>

Inserts the specified packet at index/position into the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to be modified.
[in]	pPacket	The packet to insert into the buffer.
[in]	index	Index at which the packet should be inserted.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN	The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The packet payload length is to long for the buffer.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	The given index is invalid (exceeds buffer).

◆ brawcap_buffer_at_index()

brawcap_status_t brawcap_buffer_at_index	(	brawcap_buffer_t *const	pBuffer,
		const brawcap_buffer_packet_count_t	index,
		brawcap_packet_t **const	pPacket
	)

#include <brawcap.h>

Reads out a buffered packet at the index of the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to read from.
[in]	index	The index of the packet.
[out]	pPacket	Will contain the buffered packet, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_INVALID_PARAM	The given index is invalid (exceeds buffer).

Examples: 12_buffer_sorting_f.c.

◆ brawcap_buffer_front()

brawcap_status_t brawcap_buffer_front	(	brawcap_buffer_t *const	pBuffer,
		brawcap_packet_t **const	pPacket
	)

#include <brawcap.h>

Reads out the first buffered packet of the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to read from.
[out]	pPacket	Will contain the buffered packet, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

◆ brawcap_buffer_back()

brawcap_status_t brawcap_buffer_back	(	brawcap_buffer_t *const	pBuffer,
		brawcap_packet_t **const	pPacket
	)

#include <brawcap.h>

Reads out the last buffered packet of the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to read from.
[out]	pPacket	Will contain the buffered packet, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

◆ brawcap_buffer_count()

brawcap_status_t brawcap_buffer_count	(	brawcap_buffer_t *const	pBuffer,
		brawcap_buffer_packet_count_t *const	pPacketCount
	)

#include <brawcap.h>

Reads out the number of currently buffered packets in the specified packet buffer.

Parameters

[in]	pBuffer	The packet buffer to read from.
[out]	pPacketCount	Will contain the number of buffered packets, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

Examples: 10_transmit_buffered_transmitter_f.c, and 12_buffer_sorting_f.c.

◆ brawcap_buffer_capacity()

brawcap_status_t brawcap_buffer_capacity	(	brawcap_buffer_t *const	pBuffer,
		brawcap_buffer_packet_count_t *const	pPacketCapacity
	)

#include <brawcap.h>

Reads out the total number of packets which can be buffered by the specified packet buffer. This value represents the packet buffer capacity, which is set during buffer creation.

Parameters

[in]	pBuffer	The packet buffer to read from.
[out]	pPacketCapacity	Will contain the total number of packets which can be buffered, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer is still in use/pending (receive/transmit).

◆ brawcap_buffer_sort()

brawcap_status_t brawcap_buffer_sort	(	brawcap_buffer_t *const	pBuffer,
		const brawcap_buffer_sort_order_t	order,
		const brawcap_buffer_sort_types_t	type,
		const brawcap_packet_size_t	offset,
		const brawcap_packet_size_t	length,
		const brawcap_buffer_sort_endian_t	endian
	)

#include <brawcap.h>

Sorts packets in a buffer by timestamp or by a payload field.

Purpose: Provides deterministic ordering for analysis, replay or synchronized transmission preparation.

Modes (type):

TIMESTAMP : Uses packet receive (or transmit) timestamp. Requires packets to be timestamped.
PAYLOAD : Compares a payload slice defined by (offset,length).
NONE : No sorting (function returns success, buffer unchanged).

Order (order): RISING (ascending) or FALLING (descending). NONE => no change.

Payload mode specifics:

Offset origin is the first payload byte (index 0).
Every packet must satisfy offset + length <= captured payload size or the call fails with PARAM_OUT_OF_RANGE.
length == 0 => no-op (treated like NONE).
Endianness (endian) controls multi-byte numeric interpretation for common field sizes (1/2/4/8). For other lengths a byte-wise comparison is performed in the direction implied by endian.

Endianness (endian): BIG = network order; LITTLE = host little-endian. Ignored for timestamp mode or length <= 1.

Stability: Not stable (equal keys may reorder). If stable ordering is required, apply a stable algorithm afterwards.

Usage constraints:

Buffer must not be attached to an active receive or transmit operation (else ERROR_IN_USE).
Provide valid enumeration values; invalid combinations yield ERROR_INVALID_PARAM.

Common use cases:

Prepare buffers for synchronized transmission (sort by timestamp RISING).
Group flows or detect gaps by sorting on protocol header fields (e.g. TCP sequence number slice).

Parameters

[in]	pBuffer	Buffer to sort.
[in]	order	Desired order (ignored if type NONE or length == 0).
[in]	type	Sort key type.
[in]	offset	Payload slice start (payload mode only).
[in]	length	Payload slice length (payload mode only; 0=no-op).
[in]	endian	Endianness for multi-byte payload slice (payload mode only).

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Completed (or no-op).
BRAWCAP_STATUS_ERROR_INVALID_POINTER	pBuffer NULL.
BRAWCAP_STATUS_ERROR_IN_USE	Buffer currently attached / in use.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Offset/length invalid for at least one packet.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Invalid enum value combination.

Examples: 12_buffer_sorting_f.c.

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ brawcap_buffer_packet_count_t

◆ brawcap_buffer_t

Enumeration Type Documentation

◆ brawcap_buffer_sort_order_t

◆ brawcap_buffer_sort_types_t

◆ brawcap_buffer_sort_endian_t

Function Documentation

◆ brawcap_buffer_create()

◆ brawcap_buffer_free()

◆ brawcap_buffer_clear()

◆ brawcap_buffer_add_back()

◆ brawcap_buffer_add_front()

◆ brawcap_buffer_add_at_index()

◆ brawcap_buffer_at_index()

◆ brawcap_buffer_front()

◆ brawcap_buffer_back()

◆ brawcap_buffer_count()

◆ brawcap_buffer_capacity()

◆ brawcap_buffer_sort()