Types and functions for bRAWcap receiving. More...

Modules
	Receive Filter
	Types and functions for operating with bRAWcap receive filters.

Macros
#define	BRAWCAP_RX_COPY_PACKETS_DEFAULT 0
	Default minimum packets to copy value which has to be received before any receive function return even if configured timeout exceeds.

#define	BRAWCAP_RX_TIMEOUT_MS_DEFAULT 10
	Default timeout in milliseconds after which a bRAWcap receive returns, even if buffer is not yet full but the configured receive min packets to copy must be reached.

#define	BRAWCAP_RX_TIMESTAMP_MODE_DEFAULT BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
	Default receive timestamp mode which will be used.

#define	BRAWCAP_RX_VLAN_TAGGING_DEFAULT FALSE
	Default VLAN tagging mode which will be used.

#define	BRAWCAP_RX_DRIVER_QUEUE_SIZE_DEFAULT 4096
	Default size for driver receive queues in number of packets.

#define	BRAWCAP_RX_TIMEOUT_MS_MAX 5000
	Maximum supported receive timeout in number of milliseconds.

#define	BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX 40000
	Maximum size (in number of packets) supported for driver receive queues.

#define	BRAWCAP_RX_DIRECTION_DEFAULT BRAWCAP_RX_DIRECTION_BOTH
	Default receive direction which will be used.

#define	BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX 2
	Max number of supported packet (receive) buffers per bRAWcap handle.

Typedefs
typedef UINT16	brawcap_rx_timeout_t
	Type for handling receive timeouts in number of milliseconds. The timeout specifies the maximum blocking time in milliseconds for pending bRAWcap receives. If a packet is received or the receive buffer is full before the timeout is reached, receive will return earlier.

typedef UINT32	brawcap_rx_min_packets_t
	Type for handling the minimum amount of packets to copy before a bRAWcap receive will return. It specifies how many packets should be received before a pending receive returns. Reading more packets in a single call can improve the performance but leads to higher latency.

typedef void(*	brawcap_rx_callback_t) (brawcap_handle_t const pHandle, const brawcap_status_t status, brawcap_buffer_t const pBuffer, void *pUser)
	Receive callback which is called each time a receive has finished. Receiving can be started with brawcap_rx_start and has to be stopped with brawcap_rx_stop. Before anything can be received it is necessary to attach packet buffers to the bRAWcap handle. This can be done by creating new bRAWcap buffers (brawcap_buffer_create) and attach it with brawcap_rx_buffer_attach.

Enumerations
enum	brawcap_rx_mode_t { BRAWCAP_RX_MODE_LIVE = 1 , BRAWCAP_RX_MODE_DUMP = 2 }
	List of receive modes. More...

enum	brawcap_rx_direction_t { BRAWCAP_RX_DIRECTION_UNKNOWN = 0x00 , BRAWCAP_RX_DIRECTION_IN = 0x01 , BRAWCAP_RX_DIRECTION_OUT = 0x02 , BRAWCAP_RX_DIRECTION_BOTH = 0x03 }
	List of supported receive directions. More...

Functions
brawcap_status_t	brawcap_rx_packet (brawcap_handle_t const pHandle, brawcap_packet_t const pPacket)
	Receives a single packet from the specified handle.

brawcap_status_t	brawcap_rx_start (brawcap_handle_t const pHandle, brawcap_rx_callback_t const callback, void const pUser, const BOOLEAN indicateNoPackets)
	Starts the internal receive loop.

brawcap_status_t	brawcap_rx_stop (brawcap_handle_t *const pHandle)
	Stops the internal receive loop.

brawcap_status_t	brawcap_rx_buffer_attach (brawcap_handle_t const pHandle, brawcap_buffer_t const pBuffer)
	Attaches the specified bRAWcap packet buffer to the specified handle.

brawcap_status_t	brawcap_rx_buffer_detach (brawcap_handle_t const pHandle, brawcap_buffer_t const pBuffer)
	Detaches the specified bRAWcap packet buffer from the specified handle.

brawcap_status_t	brawcap_rx_direction_set (brawcap_handle_t *const pHandle, const brawcap_rx_direction_t direction)
	Sets the receive direction for the specified handle.

brawcap_status_t	brawcap_rx_direction_get (brawcap_handle_t const pHandle, brawcap_rx_direction_t const pDirection)
	Reads out the currently configured receive direction of the specified handle.

brawcap_status_t	brawcap_rx_min_packets_set (brawcap_handle_t *const pHandle, const brawcap_rx_min_packets_t minPackets)
	Sets the minimum amount of packets to receive for the specified handle.

brawcap_status_t	brawcap_rx_min_packets_get (brawcap_handle_t const pHandle, brawcap_rx_min_packets_t const pMinPackets)
	Reads out the currently configured number of packets to receive for the specified handle.

brawcap_status_t	brawcap_rx_timeout_set (brawcap_handle_t *const pHandle, const brawcap_rx_timeout_t timeout_ms)
	Configures the receive timeout for the specified handle.

brawcap_status_t	brawcap_rx_timeout_get (brawcap_handle_t const pHandle, brawcap_rx_timeout_t const pTimeout_ms)
	Reads out the currently configured receive timeout for the specified handle.

brawcap_status_t	brawcap_rx_filter_set (brawcap_handle_t const pHandle, const brawcap_filter_t const pFilter)
	Sets the specified filter to the specified handle.

brawcap_status_t	brawcap_rx_filter_get (brawcap_handle_t const pHandle, brawcap_filter_t const pFilter)
	Reads out the currently configured filter for the specified handle.

brawcap_status_t	brawcap_rx_promiscuous_mode_set (brawcap_handle_t *const pHandle, const BOOLEAN enable)
	Sets the current promiscuous mode flag for the specified handle.

brawcap_status_t	brawcap_rx_promiscuous_mode_get (brawcap_handle_t const pHandle, BOOLEAN const pEnabled, BOOLEAN *const pEnabledAdapter)
	Reads out the current promiscuous mode state for the specified handle.

brawcap_status_t	brawcap_rx_timestamp_capabilities (brawcap_handle_t const pHandle, brawcap_timestamp_capabilities_t const pCapabilities)
	Reads out the available receive timestamp modes for the specified handle.

brawcap_status_t	brawcap_rx_timestamp_mode_get (brawcap_handle_t const pHandle, brawcap_timestamp_mode_t const pMode)
	Reads out the currently configured receive time stamping mode for the specified handle.

brawcap_status_t	brawcap_rx_timestamp_mode_set (brawcap_handle_t *const pHandle, const brawcap_timestamp_mode_t mode)
	Configures the used receive time stamping mode for the specified handle.

brawcap_status_t	brawcap_rx_vlan_tagging_set (brawcap_handle_t *const pHandle, const BOOLEAN enable)
	Sets the current VLAN tagging flag for the specified handle.

brawcap_status_t	brawcap_rx_vlan_tagging_get (brawcap_handle_t const pHandle, BOOLEAN const pEnabled)
	Reads out the configured VLAN tagging state for the specified handle.

brawcap_status_t	brawcap_rx_driver_queue_size_set (brawcap_handle_t *const pHandle, const brawcap_queue_size_t size)
	Sets the driver queue size (in number of packets) for the specified handle.

brawcap_status_t	brawcap_rx_driver_queue_size_get (brawcap_handle_t const pHandle, brawcap_queue_size_t const pSize)
	Reads out the currently configured driver receive queue size for the specified handle.

Detailed Description

Types and functions for bRAWcap receiving.

List of examples:

Macro Definition Documentation

◆ BRAWCAP_RX_COPY_PACKETS_DEFAULT

#define BRAWCAP_RX_COPY_PACKETS_DEFAULT 0

#include <brawcap_types_shared.h>

Default minimum packets to copy value which has to be received before any receive function return even if configured timeout exceeds.

Note: bRAWcap waits at least up to 10 times the configured timeout before finally returning if the minimum number of packets has not yet been received.

Warning: If a timeout of zero which is equivalent to infinite wait is configured it blocks until the minimum amount of packets are received and will not return earlier.

◆ BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX

#define BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX 2

#include <brawcap_types_um.h>

Max number of supported packet (receive) buffers per bRAWcap handle.

Limits the number of buffers which can be attached to a single handle with brawcap_rx_buffer_attach.

Typedef Documentation

◆ brawcap_rx_timeout_t

typedef UINT16 brawcap_rx_timeout_t

#include <brawcap_types_shared.h>

Type for handling receive timeouts in number of milliseconds. The timeout specifies the maximum blocking time in milliseconds for pending bRAWcap receives. If a packet is received or the receive buffer is full before the timeout is reached, receive will return earlier.

Attention

A receive timeout value of zero corresponds to an infinite wait. This means that bRAWcap receive will only return if

brawcap_rx_packet - a packet is received,
brawcap_rx_start - the minimum amount of packets to copy is reached (see brawcap_rx_min_packets_t) or the attached buffer is full - whichever comes first.

◆ brawcap_rx_min_packets_t

typedef UINT32 brawcap_rx_min_packets_t

#include <brawcap_types_shared.h>

Type for handling the minimum amount of packets to copy before a bRAWcap receive will return. It specifies how many packets should be received before a pending receive returns. Reading more packets in a single call can improve the performance but leads to higher latency.

Note: This setting is only used with looped receive (brawcap_rx_start) and has no impact on single packet reception (brawcap_rx_packet).

◆ brawcap_rx_callback_t

typedef void(* brawcap_rx_callback_t) (brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)

#include <brawcap_types_um.h>

Receive callback which is called each time a receive has finished. Receiving can be started with brawcap_rx_start and has to be stopped with brawcap_rx_stop. Before anything can be received it is necessary to attach packet buffers to the bRAWcap handle. This can be done by creating new bRAWcap buffers (brawcap_buffer_create) and attach it with brawcap_rx_buffer_attach.

Note: If a handle has multiple buffers attached, the callback may be called in parallel (by different threads).

Warning: Executing to long in the callback can lead to a bottleneck in reception! It is recommended that the driver always has at least one (free) buffer were it can store the packets to.

Parameters

[in]	pHandle	Handle on which the receive returned.
[in]	status	The overall receive status see brawcap_status_t for possible return values.
[in]	pBuffer	Pointer to the buffer which has finished receiving. It can be used to access all packets in the buffer and allows to retrieve information for each received packet (e.g. payload, length, timestamp, ...).
[in]	pUser	Pointer to a user defined context. It allows access to user specific data within the callback.

Enumeration Type Documentation

◆ brawcap_rx_mode_t

enum brawcap_rx_mode_t

#include <brawcap_types_shared.h>

List of receive modes.

Enumerator

BRAWCAP_RX_MODE_LIVE

Received packets are stored in a user created bRAWcap packet (buffer) and provided to the calling application for processing.

BRAWCAP_RX_MODE_DUMP

Received packets are directly written to disk.

Note: Dumping mode is not yet supported and may be added to later releases.

◆ brawcap_rx_direction_t

enum brawcap_rx_direction_t

#include <brawcap_types_shared.h>

List of supported receive directions.

The receive direction allows the select for which direction (transmit/receive) the packets shall be captured. This setting can be seen as some kind of generic receive filter.

Enumerator
BRAWCAP_RX_DIRECTION_UNKNOWN	Stops to receive packets of any direction.
BRAWCAP_RX_DIRECTION_IN	Only received packets by the network adapter will be received.
BRAWCAP_RX_DIRECTION_OUT	Only transmitted packets by bRAWcap or upper network stack drivers will be received. This allows some kind of loopback for packets which are transmitted to the network. Note This currently does not include packets sent to localhost (IP 127.0.0.1), because they are not transmitted/received via a real network adapter. Instead Windows creates a separate "virtual" adapter for localhost communication. This adapter is currently not supported by bRAWcap.
BRAWCAP_RX_DIRECTION_BOTH	Both transmitted packets by bRAWcap or upper network stack drivers and received packets from the underlying network adapter will be received.

Function Documentation

◆ brawcap_rx_packet()

brawcap_status_t brawcap_rx_packet	(	brawcap_handle_t *const	pHandle,
		brawcap_packet_t *const	pPacket
	)

#include <brawcap.h>

Receives a single packet from the specified handle.

The caller must provide a valid packet were bRAWcap will store the received data. To create a packet use brawcap_packet_create or use a buffered packet which was returned by a valid buffer with brawcap_buffer_at_index.

Note: Parallel receives per handle are not allowed. This means that if there is any other receive pending on the handle each further initiated receive will fail until the pending operation has finished.

Parameters

[in]	pHandle	bRAWcap handle to receive from.
[out]	pPacket	Packet were the received data will be stored.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_WARNING_PENDING	Another receive is still pending/active.
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE	bRAWcap driver is not active (anymore) on the adapter.
BRAWCAP_STATUS_WARNING_DEMO_MODE	Running in demo mode (no license).
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.
BRAWCAP_STATUS_INFO_NO_DATA	Returned without any data received (due to timeout).

Examples: 05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.

◆ brawcap_rx_start()

brawcap_status_t brawcap_rx_start	(	brawcap_handle_t *const	pHandle,
		brawcap_rx_callback_t const	callback,
		void *const	pUser,
		const BOOLEAN	indicateNoPackets
	)

#include <brawcap.h>

Starts the internal receive loop.

To receive data using this method it is necessary to attach memory to the bRAWcap handle were received data can be stored. This can be done by attaching (with brawcap_rx_buffer_attach) a previously created bRAWcap packet buffer (with brawcap_buffer_create).

When a reception has finished (due to timeout, min packets or full buffer) the receive callback will be called for this handle (brawcap_rx_callback_t). In this callback the user application can do it´s post processing on the received data. If the user application does not detach the buffer (with brawcap_rx_buffer_detach) it will be reused for receiving after callback has completed.

The user application should do it´s post processing anyway, as fast as possible. Depending on the current bandwidth the attached buffers may be filled up very fast. If the user application takes to long it will lead to a bottleneck in the reception and the driver runs out of resources. This may result in performance degradation or packet loss.

It is possible to attach more than only one buffer to a single handle. This ensures that the bRAWcap driver can toggle the buffers during the reception. This reduces the time gap the driver has to buffer data internally (because there is no user buffer available). With more than one buffer the driver can still fill up another buffer while the user application does it´s post processing. Therefore in general, using more than one buffer increases the performance.

Note

Due to the focus on optimized throughput with minimal CPU load bRAWcap does not fill up the packets in the buffer with the same sequence they were received by the adapter. Here we want to give some additional information on the topic of "packet sequence/timestamp":

First of all it should be known that the receive sequence may not be equal to the sending sequence. Due to several senders or some network managers in between (switches and so on...). For any protocols which require a ordered packet stream, there will be at least one field in the packet payload which allows to sort the packets on the receiver side. This is a "higher" layer topic and not part of bRAWcap.
With the bRAWcap supported timestamp mechanisms it is possible to sort the received packets corresponding to their receive timestamps. But keep in mind that only the BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE guarantees that the receive timestamps really match the received packet sequence on the adapter. To use the named timestamp mechanism, the underlying network adapter must support it. Any other timestamp is generated by software. Windows is not a realtime operation system, and therefore due to multithreading, scheduling (...) it could happen that some packets are processed before other packets which was received earlier. Especially the Windows network stack feature called "receive side scaling" can also increase the issue of incorrect packet sequences.

Invariant: The user parameter allows access to user defined context. The given pointer is not used and validated by bRAWcap. Therefore the user is responsible for validating the context in the callback before accessing it.

Attention: After starting receive brawcap_rx_packet can not be used until you stop the receive with brawcap_rx_stop, because parallel receives are not allowed.

Parameters

[in]	pHandle	bRAWcap handle to receive from.
[in]	callback	Function pointer to user application receive callback.
[in]	pUser	Pointer to a user defined context. Can be NULL if no user context is required.
[in]	indicateNoPackets	Specifies if callback is called even without any received data.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_WARNING_PENDING	Another receive is pending or reception is already started.

Examples: 07_receive_buffered_receiver.c.

◆ brawcap_rx_stop()

brawcap_status_t brawcap_rx_stop ( brawcap_handle_t *const pHandle )

#include <brawcap.h>

Stops the internal receive loop.

Parameters

[in] pHandle bRAWcap handle to stop reception.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_INFO_NOT_RUNNING	There was no receive running.

Examples: 07_receive_buffered_receiver.c.

◆ brawcap_rx_buffer_attach()

brawcap_status_t brawcap_rx_buffer_attach	(	brawcap_handle_t *const	pHandle,
		brawcap_buffer_t *const	pBuffer
	)

#include <brawcap.h>

Attaches the specified bRAWcap packet buffer to the specified handle.

After attaching a packet buffer to a handle it will be used for receiving data on that handle. Data is only received if the internal receive loop was started/is running (with brawcap_rx_start).

The buffer is locked until:

It is detached from the handle with brawcap_rx_buffer_detach.
A receive has finished and the receive callback is called (buffer is not locked during callback execution).

Note: A buffer can be attached only once and is than locked down by the handle it is attached to. This means that it has to be detached before it can be used again for another handle.

Parameters

[in]	pHandle	bRAWcap handle for attaching the buffer.
[in]	pBuffer	Packet buffer to be attached.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE	The buffer is already in use / locked down by another operation.
BRAWCAP_STATUS_WARNING_LIMIT_REACHED	Limitation of buffer per handle reached (BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX)

Examples: 07_receive_buffered_receiver.c.

◆ brawcap_rx_buffer_detach()

brawcap_status_t brawcap_rx_buffer_detach	(	brawcap_handle_t *const	pHandle,
		brawcap_buffer_t *const	pBuffer
	)

#include <brawcap.h>

Detaches the specified bRAWcap packet buffer from the specified handle.

After detaching a buffer it is unlocked and can be accessed/modified. It can also be reused for another operation or freed with brawcap_buffer_free if it is not required anymore.

Parameters

[in]	pHandle	bRAWcap handle from which the buffer is to be detached.
[in]	pBuffer	Packet buffer to be detached.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_INFO_NOT_ATTACHED	The buffer was not attached.

Examples: 07_receive_buffered_receiver.c.

◆ brawcap_rx_direction_set()

brawcap_status_t brawcap_rx_direction_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_rx_direction_t	direction
	)

#include <brawcap.h>

Sets the receive direction for the specified handle.

Possible directions are:

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	direction	The direction to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_direction_get()

brawcap_status_t brawcap_rx_direction_get	(	brawcap_handle_t *const	pHandle,
		brawcap_rx_direction_t *const	pDirection
	)

#include <brawcap.h>

Reads out the currently configured receive direction of the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pDirection	Will contain the currently configured receive direction, afterwards.

Returns

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

◆ brawcap_rx_min_packets_set()

brawcap_status_t brawcap_rx_min_packets_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_rx_min_packets_t	minPackets
	)

#include <brawcap.h>

Sets the minimum amount of packets to receive for the specified handle.

This value influences how often the bRAWcap driver will return pending receives. It forces the driver to stay in the request as long as not the minimum amount of packets were captured. Setting a higher value here can reduce the overall system load but increases also the responsiveness/latency when the packet was received by the adapter and the indication of the packet to the caller. The initial/default value is set to BRAWCAP_RX_COPY_PACKETS_DEFAULT.

Invariant: If high receive rates should be reached (and many packets coming in), a high value is preferred. Otherwise if low latency is required the best effort would be to set this value to zero.

Note: Independent from this value the receive will at least return if it pends for 10 times the configured receive timeout. This avoid infinite blocking (infinite blocking is only the possible if the receive timeout is zero). If this value is set to zero it will always return after the first receive timeout. And if the given buffer becomes filled up before the timeout is reached it will return when the buffer is full.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	minPackets	The minimum amount of packets to receive.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_min_packets_get()

brawcap_status_t brawcap_rx_min_packets_get	(	brawcap_handle_t *const	pHandle,
		brawcap_rx_min_packets_t *const	pMinPackets
	)

#include <brawcap.h>

Reads out the currently configured number of packets to receive for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pMinPackets	Will contain the configured minimum amount of packets per receive, afterwards.

Returns

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

◆ brawcap_rx_timeout_set()

brawcap_status_t brawcap_rx_timeout_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_rx_timeout_t	timeout_ms
	)

#include <brawcap.h>

Configures the receive timeout for the specified handle.

It´s guaranteed that receive functions will return at least after the specified timeout value, if the configured amount of packets value brawcap_rx_min_packets_t is reached before. If the configured amount of packets are not reached until the timeout occurs, the driver will stay in the request for up to 10 times of the specified timeout time until it final returns. It is also possible to specify a timeout of zero. A timeout of zero is equivalent to "no timeout".

Note: Default timeout value is BRAWCAP_RX_TIMEOUT_MS_DEFAULT. And the max supported timeout is BRAWCAP_RX_TIMEOUT_MS_MAX.

Attention: Be careful in using infinite timeouts. It could lead to a endless blocking behaviour. For example if there are no packets received which meet your configured filter on the underlying adapter.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	timeout_ms	Receive timeout in milliseconds to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The specified timeout value is invalid/out of range.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_timeout_get()

brawcap_status_t brawcap_rx_timeout_get	(	brawcap_handle_t *const	pHandle,
		brawcap_rx_timeout_t *const	pTimeout_ms
	)

#include <brawcap.h>

Reads out the currently configured receive timeout for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pTimeout_ms	Will contain the configured receive timeout in milliseconds, afterwards.

Returns

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

◆ brawcap_rx_filter_set()

brawcap_status_t brawcap_rx_filter_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_filter_t *const	pFilter
	)

#include <brawcap.h>

Sets the specified filter to the specified handle.

For more information on filters see brawcap_filter_t.

Note: Each handle can have exactly one filter applied. If several filters shall be applied to the same adapter, it is required to open several bRAWcap handles to the same adapter.

Parameters

[in]	pHandle	bRAWcap handle to be modified.
[in]	pFilter	The filter to set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Specified filter type is not available.

Examples: 06_filter_firewall.c.

◆ brawcap_rx_filter_get()

brawcap_status_t brawcap_rx_filter_get	(	brawcap_handle_t *const	pHandle,
		brawcap_filter_t *const	pFilter
	)

#include <brawcap.h>

Reads out the currently configured filter for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pFilter	Will contain the currently configured filter, afterwards.

Returns

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

◆ brawcap_rx_promiscuous_mode_set()

brawcap_status_t brawcap_rx_promiscuous_mode_set	(	brawcap_handle_t *const	pHandle,
		const BOOLEAN	enable
	)

#include <brawcap.h>

Sets the current promiscuous mode flag for the specified handle.

If a adapter is set into promiscuous mode it receives not only packages which directly address the adapter. This can be used for recording/sniffing purposes but increases the local system load. Promiscuous mode is a network adapter feature and which can only be modified by bRAWcap. Therefore it is not specific to a bRAWcap handle. Instead it is a per adapter setting which can also be modified from another application.

Note: Promiscuous mode will be reset automatically upon deleting the corresponding handle. Which means if it was activated due to the bRAWcap handle it will be disabled again when the handle is closed.

Attention: Because of the per adapter scope, promiscuous mode can not explicitly modified by bRAWcap. Instead if at least one application or another bRAWcap handle activated it, it will stay enabled until the last application/handle which has activated it, is closed or deactivates it again.

Parameters

[in]	pHandle	bRAWcap handle to be modified.
[in]	enable	Promiscuous mode state to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_promiscuous_mode_get()

brawcap_status_t brawcap_rx_promiscuous_mode_get	(	brawcap_handle_t *const	pHandle,
		BOOLEAN *const	pEnabled,
		BOOLEAN *const	pEnabledAdapter
	)

#include <brawcap.h>

Reads out the current promiscuous mode state for the specified handle.

Additionally to the promiscuous state of the handle itself it also reads the current promiscuous state of to the underlying adapter.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pEnabled	Will contain the current promiscuous mode state of the handle, afterwards.
[out]	pEnabledAdapter	Will contain the current promiscuous mode state of the underlying adapter, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_timestamp_capabilities()

brawcap_status_t brawcap_rx_timestamp_capabilities	(	brawcap_handle_t *const	pHandle,
		brawcap_timestamp_capabilities_t *const	pCapabilities
	)

#include <brawcap.h>

Reads out the available receive timestamp modes for the specified handle.

Some of the timestamp capabilites depend on the features provided by the underlying adapter. Those modes are named with "adapter".

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pCapabilities	Will contain the available receive timestamp modes, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_rx_timestamp_mode_get()

brawcap_status_t brawcap_rx_timestamp_mode_get	(	brawcap_handle_t *const	pHandle,
		brawcap_timestamp_mode_t *const	pMode
	)

#include <brawcap.h>

Reads out the currently configured receive time stamping mode for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pMode	Will contain the currently used receive time stamping mode, afterwards.

Returns

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

◆ brawcap_rx_timestamp_mode_set()

brawcap_status_t brawcap_rx_timestamp_mode_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_timestamp_mode_t	mode
	)

#include <brawcap.h>

Configures the used receive time stamping mode for the specified handle.

Note: Only available timestamp modes are accepted. It is recommended to check if a timestamp mode is supported before setting it. To check if a timestamp mode is available use brawcap_rx_timestamp_capabilities.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[out]	mode	The receive timestamp mode to be configured.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Specified timestamp mode not available.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

Examples: 08_receive_timestamp_inspector.c.

◆ brawcap_rx_vlan_tagging_set()

brawcap_status_t brawcap_rx_vlan_tagging_set	(	brawcap_handle_t *const	pHandle,
		const BOOLEAN	enable
	)

#include <brawcap.h>

Sets the current VLAN tagging flag for the specified handle.

If VLAN tagging is enabled, the VLAN Header (defined by IEEE 802.1Q) will be part of the packet payload. By default, the VLAN header is not included in the packet payload.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	enable	VLAN tagging state to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

◆ brawcap_rx_vlan_tagging_get()

brawcap_status_t brawcap_rx_vlan_tagging_get	(	brawcap_handle_t *const	pHandle,
		BOOLEAN *const	pEnabled
	)

#include <brawcap.h>

Reads out the configured VLAN tagging state for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pEnabled	Will contain the currently configured VLAN tagging state, afterwards.

Returns

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

◆ brawcap_rx_driver_queue_size_set()

brawcap_status_t brawcap_rx_driver_queue_size_set	(	brawcap_handle_t *const	pHandle,
		const brawcap_queue_size_t	size
	)

#include <brawcap.h>

Sets the driver queue size (in number of packets) for the specified handle.

A larger driver queue can avoid packet drops for time gaps were no packet buffer is available. But setting large driver queues should only be done if really necessary, because it can consume a lot of memory. Because driver queues exist per handle, the total amount of consumed memory has to summed up for all open handles and their current configuration.

The driver queue size can be adjusted at any time.

Note: The default queue size is

See also: BRAWCAP_RX_DRIVER_QUEUE_SIZE_DEFAULT (in number of packets). And its max limitation is; BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX (in number of packets).

Attention: Reducing the queue size during runtime may result in packet loss. This may be the case if there are more packets stored in the queue than the new size can accommodate.

Parameters

[in]	pHandle	bRAWcap handle to be configured.
[in]	size	Driver receive queue size to be set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the given pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Specified queue size is out of range/invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

Examples: 06_filter_firewall.c.

◆ brawcap_rx_driver_queue_size_get()

brawcap_status_t brawcap_rx_driver_queue_size_get	(	brawcap_handle_t *const	pHandle,
		brawcap_queue_size_t *const	pSize
	)

#include <brawcap.h>

Reads out the currently configured driver receive queue size for the specified handle.

Parameters

[in]	pHandle	bRAWcap handle to read from.
[out]	pSize	Will contain the currently configured driver receive queue size, afterwards.

Returns

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

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BRAWCAP_RX_COPY_PACKETS_DEFAULT

◆ BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX

Typedef Documentation

◆ brawcap_rx_timeout_t

◆ brawcap_rx_min_packets_t

◆ brawcap_rx_callback_t

Enumeration Type Documentation

◆ brawcap_rx_mode_t

◆ brawcap_rx_direction_t

Function Documentation

◆ brawcap_rx_packet()

◆ brawcap_rx_start()

◆ brawcap_rx_stop()

◆ brawcap_rx_buffer_attach()

◆ brawcap_rx_buffer_detach()

◆ brawcap_rx_direction_set()

◆ brawcap_rx_direction_get()

◆ brawcap_rx_min_packets_set()

◆ brawcap_rx_min_packets_get()

◆ brawcap_rx_timeout_set()

◆ brawcap_rx_timeout_get()

◆ brawcap_rx_filter_set()

◆ brawcap_rx_filter_get()

◆ brawcap_rx_promiscuous_mode_set()

◆ brawcap_rx_promiscuous_mode_get()

◆ brawcap_rx_timestamp_capabilities()

◆ brawcap_rx_timestamp_mode_get()

◆ brawcap_rx_timestamp_mode_set()

◆ brawcap_rx_vlan_tagging_set()

◆ brawcap_rx_vlan_tagging_get()

◆ brawcap_rx_driver_queue_size_set()

◆ brawcap_rx_driver_queue_size_get()