Packet Buffer Iterator

bRAWcap packet buffer iterators. More...

Typedefs
typedef struct _brawcap_buffer_iterator	brawcap_buffer_iterator_t
	bRAWcap packet buffer iterator object.

Functions
brawcap_status_t	brawcap_buffer_iterator_create (brawcap_buffer_iterator_t **const pIterator, brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t startPosition)
	Creates a new iterator for the specified buffer.
brawcap_status_t	brawcap_buffer_iterator_free (brawcap_buffer_iterator_t *const pIterator)
	Frees the specified iterator. When this function is called the specified iterator becomes invalid and it´s memory will be released.
brawcap_status_t	brawcap_buffer_iterator_next (brawcap_buffer_iterator_t *const pIterator)
	Increments the iterator to the next buffered packet.
brawcap_status_t	brawcap_buffer_iterator_prev (brawcap_buffer_iterator_t *const pIterator)
	Decreases the iterator to the previous buffered packet.
brawcap_packet_t *	brawcap_buffer_iterator_eval (brawcap_buffer_iterator_t *const pIterator)
	Returns the buffered packet for the specified iterator.

Detailed Description

bRAWcap packet buffer iterators.

To create a new packet buffer iterator use brawcap_buffer_iterator_create. If a packet buffer iterator is not required anymore it shall be deleted with brawcap_buffer_iterator_free.

Note

Iterators should only be used as long as the packet buffer for which it was created is still available.

Attention

Packet buffer iterators are not synchronized. This means that if the packet buffer for which the iterator was created is modified meanwhile, the iterator is not updated.

List of examples:

1. Buffered Receiver

Typedef Documentation

brawcap_buffer_iterator_t

typedef struct _brawcap_buffer_iterator brawcap_buffer_iterator_t

#include <brawcap_types_shared.h>

bRAWcap packet buffer iterator object.

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

Function Documentation

brawcap_buffer_iterator_create()

brawcap_status_t brawcap_buffer_iterator_create	(	brawcap_buffer_iterator_t **const	pIterator,
		brawcap_buffer_t *const	pBuffer,
		brawcap_buffer_packet_count_t	startPosition
	)

#include <brawcap.h>

Creates a new iterator for the specified buffer.

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

Parameters

[out]	pIterator	Will contain the new created iterator.
[in]	pBuffer	The buffer for which to create the iterator.
[in]	startPosition	The start position of the iterator (packet buffer index/position). The specified position must be below the number of currently buffered packets, which can be resolved with brawcap_buffer_count.

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	Start position exceeds number of buffered packets.
BRAWCAP_STATUS_ERROR_FAILED	System error occurred (e.g. out of memory).

Examples

07_receive_buffered_receiver_f.c, and 10_transmit_buffered_transmitter_f.c.

brawcap_buffer_iterator_free()

brawcap_status_t brawcap_buffer_iterator_free

(

brawcap_buffer_iterator_t *const

pIterator

)

#include <brawcap.h>

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

Warning

Freeing a iterator is not thread safe and the user is responsible for synchronization.

Parameters

[in]

pIterator

The iterator to be freed.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

07_receive_buffered_receiver_f.c.

brawcap_buffer_iterator_next()

brawcap_status_t brawcap_buffer_iterator_next

(

brawcap_buffer_iterator_t *const

pIterator

)

#include <brawcap.h>

Increments the iterator to the next buffered packet.

Parameters

[in]

pIterator

The iterator to be incremented.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

07_receive_buffered_receiver_f.c.

brawcap_buffer_iterator_prev()

brawcap_status_t brawcap_buffer_iterator_prev

(

brawcap_buffer_iterator_t *const

pIterator

)

#include <brawcap.h>

Decreases the iterator to the previous buffered packet.

Parameters

[in]

pIterator

The iterator to be decremented.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_buffer_iterator_eval()

brawcap_packet_t * brawcap_buffer_iterator_eval

(

brawcap_buffer_iterator_t *const

pIterator

)

#include <brawcap.h>

Returns the buffered packet for the specified iterator.

Parameters

[in]

pIterator

The iterator to read from.

Returns

Pointer	Description
brawcap_packet_t	On success a valid bRAWcap packet object pointer.
NULL	Invalid iterator (e.g. beyond the last or first packet).

Examples

07_receive_buffered_receiver_f.c.