Contains generic types and functions of bRAWcap. More...

Macros
#define	BRAWCAP_HANDLES_PER_ADAPTER_MAX 5
	Specifies the maximum supported bRAWcap handles per adapter.

Typedefs
typedef UINT32	brawcap_queue_size_t
	The number of packets which can be (temporary) buffered by the bRAWcap driver queue.

typedef struct _brawcap_handle	brawcap_handle_t
	A bRAWcap handle.

Functions
brawcap_status_t	brawcap_open (const brawcap_adapter_name_t name, brawcap_handle_t **const pHandle)
	Opens a new bRAWcap handle on the adapter, specified by it´s name.

brawcap_status_t	brawcap_close (brawcap_handle_t *pHandle)
	Closes the specified bRAWcap handle.

Detailed Description

Contains generic types and functions of bRAWcap.

Everything in here is not part of any specific module, instead those types and functions are relevant for many other modules. It contains for example functions to open/create and close a bRAWcap handle.

List of examples:

Handle Opener

Macro Definition Documentation

◆ BRAWCAP_HANDLES_PER_ADAPTER_MAX

#define BRAWCAP_HANDLES_PER_ADAPTER_MAX 5

#include <brawcap_types_shared.h>

Specifies the maximum supported bRAWcap handles per adapter.

Attention: If this number of handles is reached (for a specific adapter) each additional open will fail.

Typedef Documentation

◆ brawcap_queue_size_t

typedef UINT32 brawcap_queue_size_t

#include <brawcap_types_shared.h>

The number of packets which can be (temporary) buffered by the bRAWcap driver queue.

The total number of packets which can be buffered by the driver queue is limited to:

receive: BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX
transmit: BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX

Note: Each bRAWcap handle has it´s own driver queue. Therefore the total memory consumption by the driver depends on the number of adapters and handles to each adapter, and also on how large the driver queue is specified.

Attention: Larger driver queues can minimize packet drops due to more resources. Especially in cases where the user application requires longer than expected to pick up (call receive) on the handle. But it has to be said that large queues shouldn´t be required in optimized configurations and that they can consume a lot of memory if they are not configured with care.

◆ brawcap_handle_t

typedef struct _brawcap_handle brawcap_handle_t

#include <brawcap_types_um.h>

A bRAWcap handle.

It can be created/opened and deleted/closed. In general every function which communicates with the bRAWcap driver requires a open bRAWcap handle.

Attention: The number of bRAWcap handles per adapter is limited to BRAWCAP_HANDLES_PER_ADAPTER_MAX. If this limit is reached each additional open on that adapter will fail.

Function Documentation

◆ brawcap_open()

brawcap_status_t brawcap_open	(	const brawcap_adapter_name_t	name,
		brawcap_handle_t **const	pHandle
	)

#include <brawcap.h>

Opens a new bRAWcap handle on the adapter, specified by it´s name.

The created/opened bRAWcap handle should be saved by the user application and used for calling further bRAWcap functions. Each opened handle shall be closed, if it is not required anymore.

Note: On Windows a adapter name is always represented by a GUID.; bRAWcap supports multiple handles to the same adapter. But the total number of open handles on the same adapter is limited to BRAWCAP_HANDLES_PER_ADAPTER_MAX.

Warning: Opening multiple handles to the same adapter, with the same receive filter leads to redundancy and performance degradation and therefore should be avoided, if possible.

Parameters

[in]	name	The name of the adapter to open a bRAWcap handle.
[out]	pHandle	Will contain the opened bRAWcap handle, 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_INVALID_PARAM	The specified name does not represent a adapter name (GUID).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Specified adapter name not found/not available.
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE	bRAWcap driver is not running on specified adapter.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED	Communicating with bRAWcap driver failed.

Examples: 03_generic_handle_opener.c, 04_version_comparator.c, 05_receive_simple_packet_receiver.c, 06_filter_firewall.c, 07_receive_buffered_receiver.c, and 08_receive_timestamp_inspector.c.

◆ brawcap_close()

brawcap_status_t brawcap_close ( brawcap_handle_t * pHandle )

#include <brawcap.h>

Closes the specified bRAWcap handle.

The user application should not use the specified handle anymore, after calling this function.

Warning: Closing bRAWcap handles is not thread safe and the user is responsible for synchronization.