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.

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.

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:

Buffered Receiver

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.

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

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

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

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

Modules

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ brawcap_buffer_packet_count_t

◆ brawcap_buffer_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()