Types and functions for handling bRAWcap (Ethernet) adapters. More...

Data Structures
union	brawcap_adapter_ipv4_t
	IPv4 address. More...

union	brawcap_adapter_ipv6_t
	IPv6 address. More...

Macros
#define	BRAWCAP_ADAPTER_MAC_LENGTH 6
	Required number of bytes for describing a MAC address. The defined length does not containing any delimiters, it represents the number of MAC address digits.

#define	BRAWCAP_ADAPTER_NAME_LENGTH 40
	The max supported length for an adapter name.

Typedefs
typedef UINT8	brawcap_adapter_count_t
	Type used for counting the available/supported adapters on a machine.

typedef UINT8	brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH]
	Fixed size array describing a MAC address.

typedef char	brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
	Fixed size array containing a adapter name.

typedef UINT64	brawcap_adapter_mtu_t
	Type for handling the adapter maximum transmission unit (MTU).

typedef void(*	brawcap_adapter_notify_callback_t) (const brawcap_adapter_name_t name, const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void *pUser)
	The general callback for adapter change notifications. It will be called each time a available and supported adapter change is detected.

typedef void(*	brawcap_adapter_notify_handle_callback_t) (brawcap_handle_t const pHandle, const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void pUser)
	The per handle callback for adapter change notifications. It will be called each time a change for the handle underlying adapter (and only for this adapter) is detected.

Enumerations
enum	brawcap_adapter_speed_t { BRAWCAP_ADAPTER_SPEED_UNKNOWN = 0ULL , BRAWCAP_ADAPTER_SPEED_10M = 10ULL , BRAWCAP_ADAPTER_SPEED_100M = 100ULL , BRAWCAP_ADAPTER_SPEED_1G = 1000ULL , BRAWCAP_ADAPTER_SPEED_2_5G = 2500ULL , BRAWCAP_ADAPTER_SPEED_5G = 5000ULL , BRAWCAP_ADAPTER_SPEED_10G = 10000ULL , BRAWCAP_ADAPTER_SPEED_25G = 25000ULL , BRAWCAP_ADAPTER_SPEED_40G = 40000ULL , BRAWCAP_ADAPTER_SPEED_50G = 50000ULL , BRAWCAP_ADAPTER_SPEED_100G = 100000ULL }
	List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed. More...

enum	brawcap_adapter_connection_state_t { BRAWCAP_ADAPTER_CONNECTION_UNKNOWN = 0 , BRAWCAP_ADAPTER_CONNECTION_UP = 1 , BRAWCAP_ADAPTER_CONNECTION_DOWN = 2 }
	List of adapter connection states. Values indicating the current adapter connection state (uplink/cable connected). More...

enum	brawcap_adapter_operation_state_t { BRAWCAP_ADAPTER_OPERATION_UNKNOWN = 0 , BRAWCAP_ADAPTER_OPERATION_UP = 1 , BRAWCAP_ADAPTER_OPERATION_DOWN = 2 , BRAWCAP_ADAPTER_OPERATION_TESTING = 3 }
	List of adapter operation states. Values indicating the current adapter operation state (adapter driver status). More...

enum	brawcap_adapter_notify_reason_t { BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN = 0 , BRAWCAP_ADAPTER_NOTIFY_REASON_ADD = 1 , BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE = 2 , BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE = 3 }
	List of reasons for adapter change notifications. This values indicate why a adapter change notification is received. More...

enum	brawcap_adapter_properties_t { BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME = 0x0001 , BRAWCAP_ADAPTER_PROPERTY_RX_SPEED = 0x0002 , BRAWCAP_ADAPTER_PROPERTY_TX_SPEED = 0x0004 , BRAWCAP_ADAPTER_PROPERTY_MTU = 0x0008 , BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE = 0x0010 , BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE = 0x0020 , BRAWCAP_ADAPTER_PROPERTY_IPV4 = 0x0040 , BRAWCAP_ADAPTER_PROPERTY_IPV6 = 0x0080 }
	List of adapter properties. They are used to identify adapter change notifications with a property change reason. More...

Functions
brawcap_status_t	brawcap_adapter_list_update ()
	Updates the list of supported adapters. This function searches the current machine for supported adapters and add them to the adapter list.

brawcap_status_t	brawcap_adapter_list_count (brawcap_adapter_count_t *const pCount)
	Reads out the current number of supported adapters in the adapter list.

brawcap_status_t	brawcap_adapter_list_at (const brawcap_adapter_count_t index, brawcap_adapter_name_t name)
	Reads out the adapter name of the adapter at the adapter list index.

brawcap_status_t	brawcap_adapter_notify_register (brawcap_adapter_notify_callback_t const callback, void *const pUser)
	Registers the calling process for receiving adapter change notifications.

brawcap_status_t	brawcap_adapter_notify_unregister ()
	Unregisters the calling process from receiving adapter change notifications.

brawcap_status_t	brawcap_adapter_notify_handle_register (brawcap_handle_t const pHandle, brawcap_adapter_notify_handle_callback_t const callback, void const pUser)
	Registers the specified handle for receiving adapter change notifications.

brawcap_status_t	brawcap_adapter_notify_handle_unregister (brawcap_handle_t *const pHandle)
	Unregisters the specified handle from receiving adapter change notifications.

brawcap_status_t	brawcap_adapter_name_by_handle (brawcap_handle_t *const pHandle, brawcap_adapter_name_t name)
	Reads out the adapter name of the specified adapter.

brawcap_status_t	brawcap_adapter_friendly_name (const brawcap_adapter_name_t name, char const friendlyName, UINT32 const pLength)
	Reads out the currently set adapter friendly name for the specified adapter.

brawcap_status_t	brawcap_adapter_friendly_name_by_handle (brawcap_handle_t const pHandle, char const friendlyName, UINT32 *const pLength)
	Reads out the currently set friendly name of the specified adapter.

brawcap_status_t	brawcap_adapter_description (const brawcap_adapter_name_t name, char const description, UINT32 const pLength)
	Reads out the description of the specified adapter.

brawcap_status_t	brawcap_adapter_description_by_handle (brawcap_handle_t const pHandle, char const description, UINT32 *const pLength)
	Reads out the description of a network adapter based on the specified adapter.

brawcap_status_t	brawcap_adapter_ipv4 (const brawcap_adapter_name_t name, brawcap_adapter_ipv4_t *const pIpv4)
	Reads out the currently set IPv4 address of the specified adapter.

brawcap_status_t	brawcap_adapter_ipv4_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_ipv4_t const pIpv4)
	Reads out the currently set IPv4 address of the specified adapter.

brawcap_status_t	brawcap_adapter_ipv6 (const brawcap_adapter_name_t name, brawcap_adapter_ipv6_t *const pIpv6)
	Reads out the currently set IPv6 address of the specified adapter.

brawcap_status_t	brawcap_adapter_ipv6_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_ipv6_t const pIpv6)
	Reads out the currently set IPv6 address of the specified adapter.

brawcap_status_t	brawcap_adapter_mac (const brawcap_adapter_name_t name, brawcap_adapter_mac_t mac)
	Reads out the MAC address of the specified adapter.

brawcap_status_t	brawcap_adapter_mac_by_handle (brawcap_handle_t *const pHandle, brawcap_adapter_mac_t mac)
	Reads out the MAC address of the specified adapter.

brawcap_status_t	brawcap_adapter_speed_rx (const brawcap_adapter_name_t name, brawcap_adapter_speed_t *const pSpeed)
	Reads out the current receive speed of the specified adapter.

brawcap_status_t	brawcap_adapter_speed_rx_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_speed_t const pSpeed)
	Reads out the current receive speed of the specified adapter.

brawcap_status_t	brawcap_adapter_speed_tx (const brawcap_adapter_name_t name, brawcap_adapter_speed_t *const pSpeed)
	Reads out the current transmit speed of the specified adapter.

brawcap_status_t	brawcap_adapter_speed_tx_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_speed_t const pSpeed)
	Reads out the current transmit speed of the specified adapter.

brawcap_status_t	brawcap_adapter_connection (const brawcap_adapter_name_t name, brawcap_adapter_connection_state_t *const pConnection)
	Reads out the current connection state of the specified adapter.

brawcap_status_t	brawcap_adapter_connection_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_connection_state_t const pConnection)
	Reads out the current connection state of the specified adapter.

brawcap_status_t	brawcap_adapter_operation (const brawcap_adapter_name_t name, brawcap_adapter_operation_state_t *const pOperation)
	Reads out the current operation state of the specified adapter.

brawcap_status_t	brawcap_adapter_operation_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_operation_state_t const pOperation)
	Reads out the current operation state of the specified adapter.

brawcap_status_t	brawcap_adapter_mtu (const brawcap_adapter_name_t name, brawcap_adapter_mtu_t *const pMtu)
	Reads out the configured MTU of the specified adapter.

brawcap_status_t	brawcap_adapter_mtu_by_handle (brawcap_handle_t const pHandle, brawcap_adapter_mtu_t const pMtu)
	Reads out the configured MTU of the specified adapter.

Detailed Description

Types and functions for handling bRAWcap (Ethernet) adapters.

This module provides many features that facilitate the detection of bRAWcap (Ethernet) adapters. It allows to scan the local machine for available and supported adapters, to resolve many useful adapter properties for each adapter and also an adapter change notification.

Adapter change notifications inform your application directly when any of the available properties have changed, or when a new adapter has been found or an existing one has been removed (e.g. by disabling the interface).

When you use these functions, they make all calls to the Windows API - related to adapter handling - obsolete.

List of examples:

Data Structure Documentation

◆ brawcap_adapter_ipv4_t

union brawcap_adapter_ipv4_t

IPv4 address.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

Data Fields
UINT8	bytes[4]	IPv4 address as byte array.
UINT16	words[2]	IPv4 address as word array (each element has two Bytes).
UINT32	addr	IPv4 address as single integer value.

◆ brawcap_adapter_ipv6_t

union brawcap_adapter_ipv6_t

IPv6 address.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

Data Fields
UINT8	bytes[16]	IPv6 address as byte array.
UINT16	words[8]	IPv6 address as word array (each element has two Bytes).
UINT64	qwords[2]	IPv6 address as large word array (each element has eight Bytes).

Macro Definition Documentation

◆ BRAWCAP_ADAPTER_NAME_LENGTH

#define BRAWCAP_ADAPTER_NAME_LENGTH 40

#include <brawcap_types_um.h>

The max supported length for an adapter name.

Note: On Windows a adapter name always corresponds to it´s GUID. Those GUIDs have a fixed length.

Typedef Documentation

◆ brawcap_adapter_mac_t

typedef UINT8 brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH]

#include <brawcap_types_um.h>

Fixed size array describing a MAC address.

The array only contains the MAC address digits without any delimiters.

Examples: 01_adapter_property_reader.c.

◆ brawcap_adapter_name_t

typedef char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]

#include <brawcap_types_um.h>

Fixed size array containing a adapter name.

Note: On Windows a adapter name corresponds always to it´s GUID. Textual GUIDs always have the format "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".

Examples: 01_adapter_property_reader.c, 02_adapter_change_notifier.c, 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_adapter_mtu_t

typedef UINT64 brawcap_adapter_mtu_t

#include <brawcap_types_um.h>

Type for handling the adapter maximum transmission unit (MTU).

It describes the maximum bytes per packet which can be received/transmitted on the adapter. Typical values are 1500 bytes for default sized Ethernet and 9000 bytes for jumbo frames.

Note: In general the MTU does not contain the Ethernet header (14 Bytes). If something like 1514/9014 is displayed by the adapter driver it contains the Ethernet header. If VLAN tagging is activated, VLAN packets require 4 additional bytes for each VLAN tag. There is also a 4 Byte FCS - defined by Ethernet - added to each packet (done by the network adapter). For example a full sized Jumbo Packet with one VLAN Tag can have: 14 Bytes Ethernet header + 4 Bytes VLAN Tag + 9000 Bytes Payload + 4 Bytes FCS = 9022 Bytes.

◆ brawcap_adapter_notify_callback_t

typedef void(* brawcap_adapter_notify_callback_t) (const brawcap_adapter_name_t name, const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void *pUser)

#include <brawcap_types_um.h>

The general callback for adapter change notifications. It will be called each time a available and supported adapter change is detected.

Attention: Each application can only register for this callback once.

Parameters

[in]	name	The adapter name on which the change happened.
[in]	reason	The reason/type of change (see brawcap_adapter_notify_reason_t).
[in]	properties	A bit field with the properties that have changed (see brawcap_adapter_properties_t).
[in]	pUser	Pointer to a user defined context. It allows access to user specific data within the callback.

Examples: 02_adapter_change_notifier.c.

◆ brawcap_adapter_notify_handle_callback_t

typedef void(* brawcap_adapter_notify_handle_callback_t) (brawcap_handle_t *const pHandle, const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void *pUser)

#include <brawcap_types_um.h>

The per handle callback for adapter change notifications. It will be called each time a change for the handle underlying adapter (and only for this adapter) is detected.

Attention: Each handle can register for this callback once.

Parameters

[in]	pHandle	The handle for which the adapter change notification was registered.
[in]	reason	The reason/type of change (see brawcap_adapter_notify_reason_t).
[in]	properties	A bit field with the properties that have changed (see brawcap_adapter_properties_t).
[in]	pUser	Pointer to a user defined context. It allows access to user specific data within the callback.

Enumeration Type Documentation

◆ brawcap_adapter_speed_t

enum brawcap_adapter_speed_t

#include <brawcap_types_um.h>

List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed.

Note: The speed should be always equal for rx and tx, but both can be requested independent of each other.

Enumerator
BRAWCAP_ADAPTER_SPEED_UNKNOWN	Speed unknown
BRAWCAP_ADAPTER_SPEED_10M	10 MBit/s
BRAWCAP_ADAPTER_SPEED_100M	100 MBit/s
BRAWCAP_ADAPTER_SPEED_1G	1 GBit/s
BRAWCAP_ADAPTER_SPEED_2_5G	2,5 GBit/s
BRAWCAP_ADAPTER_SPEED_5G	5 GBit/s
BRAWCAP_ADAPTER_SPEED_10G	10 GBit/s
BRAWCAP_ADAPTER_SPEED_25G	25 GBit/s
BRAWCAP_ADAPTER_SPEED_40G	40 GBit/s
BRAWCAP_ADAPTER_SPEED_50G	50 GBit/s
BRAWCAP_ADAPTER_SPEED_100G	100 GBit/s

◆ brawcap_adapter_connection_state_t

enum brawcap_adapter_connection_state_t

#include <brawcap_types_um.h>

List of adapter connection states. Values indicating the current adapter connection state (uplink/cable connected).

Enumerator
BRAWCAP_ADAPTER_CONNECTION_UNKNOWN	Connection state unknown.
BRAWCAP_ADAPTER_CONNECTION_UP	Connection is up (uplink/cable connected).
BRAWCAP_ADAPTER_CONNECTION_DOWN	Connection is down (cable not connected).

◆ brawcap_adapter_operation_state_t

enum brawcap_adapter_operation_state_t

#include <brawcap_types_um.h>

List of adapter operation states. Values indicating the current adapter operation state (adapter driver status).

Enumerator
BRAWCAP_ADAPTER_OPERATION_UNKNOWN	Operation state unknown.
BRAWCAP_ADAPTER_OPERATION_UP	Adapter is running (driver activated).
BRAWCAP_ADAPTER_OPERATION_DOWN	Adapter is down/disabled (driver deactivated).
BRAWCAP_ADAPTER_OPERATION_TESTING	Adapter is in probing state.

◆ brawcap_adapter_notify_reason_t

enum brawcap_adapter_notify_reason_t

#include <brawcap_types_um.h>

List of reasons for adapter change notifications. This values indicate why a adapter change notification is received.

Enumerator
BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN	The notification reason is unknown.
BRAWCAP_ADAPTER_NOTIFY_REASON_ADD	A new bRAWcap adapter was detected. E.g. due to enabling bRAWcap driver on an adapter where it was disabled before.
BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE	A bRAWcap adapter was removed. E.g. due to disabling bRAWcap driver on an adapter where it was enabled before.
BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE	A adapter property has changed. This can have several reasons, for a list of all properties see brawcap_adapter_properties_t.

◆ brawcap_adapter_properties_t

enum brawcap_adapter_properties_t

#include <brawcap_types_um.h>

List of adapter properties. They are used to identify adapter change notifications with a property change reason.

Note: The property values allow to store several properties in a single bitfield. This makes it possible to indicate several property changes with only one notification.

Enumerator
BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME	Adapter friendly name changed.
BRAWCAP_ADAPTER_PROPERTY_RX_SPEED	Adapter receive speed changed.
BRAWCAP_ADAPTER_PROPERTY_TX_SPEED	Adapter transmit speed changed.
BRAWCAP_ADAPTER_PROPERTY_MTU	Adapter max transmission unit changed.
BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE	Adapter operation state changed.
BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE	Adapter connection state changed.
BRAWCAP_ADAPTER_PROPERTY_IPV4	Adapter IPv4 address changed.
BRAWCAP_ADAPTER_PROPERTY_IPV6	Adapter IPv6 address changed.

Function Documentation

◆ brawcap_adapter_list_update()

brawcap_status_t brawcap_adapter_list_update ( )

#include <brawcap.h>

Updates the list of supported adapters. This function searches the current machine for supported adapters and add them to the adapter list.

Note: The list will be initialized when calling the first bRAWcap function and not update automatically after that. To update the list later on use this function. A alternative to detect new/removed adapters is registering for change notifications.

Attention: The adapter list is not thread safe. Therefore parallel calls to this function, brawcap_adapter_list_count and brawcap_adapter_list_at should be avoided or at least synchronized. If the list is changed by this function and another thread is currently retrieving information from the list it may lead to undefined behavior or even a crash if the number of entries is reduced.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.

Examples: 01_adapter_property_reader.c.

◆ brawcap_adapter_list_count()

brawcap_status_t brawcap_adapter_list_count ( brawcap_adapter_count_t *const pCount )

#include <brawcap.h>

Reads out the current number of supported adapters in the adapter list.

Note: The count is only updated after a call to brawcap_adapter_list_update.

Attention: Updating the list and retrieving information from it is not thread safe. Therefore accessing it from different threads shall be avoided or synchronized.

Parameters

[out] pCount Will contain the current number of adapters in the list, afterwards.

Returns

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

Examples: 01_adapter_property_reader.c, 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_adapter_list_at()

brawcap_status_t brawcap_adapter_list_at	(	const brawcap_adapter_count_t	index,
		brawcap_adapter_name_t	name
	)

#include <brawcap.h>

Reads out the adapter name of the adapter at the adapter list index.

Note: The adapter list is only updated after a call to brawcap_adapter_list_update.

Attention: Updating the list and retrieving information from it is not thread safe. Therefore accessing it from different threads shall be avoided or synchronized.

Parameters

[in]	index	The index of the adapter in the adapter list..
[out]	name	Will contain the name of the adapter, 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_PARAM_OUT_OF_RANGE	Specified index exceeds adapter list length.

Examples: 01_adapter_property_reader.c, 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_adapter_notify_register()

brawcap_status_t brawcap_adapter_notify_register	(	brawcap_adapter_notify_callback_t const	callback,
		void *const	pUser
	)

#include <brawcap.h>

Registers the calling process for receiving adapter change notifications.

The given callback function will be called each time a adapter change is recognized by bRAWcap for any of the supported adapters on the current machine.

Attention: Blocking for long periods within the callback function can lead to incorrect behavior and should be avoided. If you need to process a lot on adapter changes it is recommended to do the processing in another thread rather than directly within the callback.

Note: Calls to the registered callback function are serialized. This means that the callback can not be called in parallel and one call has to be finished before another one is received.; Each process can only register for notifications once.

Parameters

[in]	callback	Function pointer to the callback function which should be executed each time a adapter change is registered.
[in]	pUser	Pointer to a user defined context. This allows access to user specific data within the callback.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_INFO_ALREADY_REGISTERED	Calling process has already registered for this notification.

Examples: 02_adapter_change_notifier.c.

◆ brawcap_adapter_notify_unregister()

brawcap_status_t brawcap_adapter_notify_unregister ( )

#include <brawcap.h>

Unregisters the calling process from receiving adapter change notifications.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_INFO_NOT_REGISTERED	Calling process was not registered for this notification.

Examples: 02_adapter_change_notifier.c.

◆ brawcap_adapter_notify_handle_register()

brawcap_status_t brawcap_adapter_notify_handle_register	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_notify_handle_callback_t const	callback,
		void *const	pUser
	)

#include <brawcap.h>

Registers the specified handle for receiving adapter change notifications.

This registration only receives adapter change notifications related to the underlying adapter of the given bRAWcap handle. Whereas brawcap_adapter_notify_register notifies about adapter changes for all supported adapters on the current machine.

Each bRAWcap handle can register for this notification once.

Attention: Blocking for long periods within the callback function can lead to incorrect behavior and should be avoided. If you need to process a lot on adapter changes it is recommended to do the processing in another thread rather than directly within the callback.

Note: Calls to the registered callback function are serialized. This means that the callback can not be called in parallel and one call has to be finished before another one is received.

Parameters

[in]	pHandle	Handle to register for adapter notifications.
[in]	pUser	Pointer to a user defined context. This allows access to user specific data within the callback.
[in]	callback	Function pointer to the callback function which should be executed each time a adapter change is registered.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_INFO_ALREADY_REGISTERED	Specified handle has already registered for this notification.

◆ brawcap_adapter_notify_handle_unregister()

brawcap_status_t brawcap_adapter_notify_handle_unregister ( brawcap_handle_t *const pHandle )

#include <brawcap.h>

Unregisters the specified handle from receiving adapter change notifications.

Parameters

[in] pHandle Handle to unregister for adapter notifications.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_INFO_NOT_REGISTERED	Specified handle was not registered for this notification.

◆ brawcap_adapter_name_by_handle()

brawcap_status_t brawcap_adapter_name_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_name_t	name
	)

#include <brawcap.h>

Reads out the adapter name of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	name	Will contain the adapter name, afterwards.

Returns

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

◆ brawcap_adapter_friendly_name()

brawcap_status_t brawcap_adapter_friendly_name	(	const brawcap_adapter_name_t	name,
		char *const	friendlyName,
		UINT32 *const	pLength
	)

#include <brawcap.h>

Reads out the currently set adapter friendly name for the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	friendlyName	Pointer to a buffer which will contain the currently set adapter friendly name, afterwards. This parameter can be NULL. If it is NULL the function will set the required buffer length in pLength and return BRAWCAP_STATUS_ERROR_OVERRUN.
[in,out]	pLength	Length of the provided buffer. If the specified length is to short, it will be set to the required length and BRAWCAP_STATUS_ERROR_OVERRUN is returned.

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	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.
BRAWCAP_STATUS_ERROR_OVERRUN	Given buffer length was to short.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_friendly_name_by_handle()

brawcap_status_t brawcap_adapter_friendly_name_by_handle	(	brawcap_handle_t *const	pHandle,
		char *const	friendlyName,
		UINT32 *const	pLength
	)

#include <brawcap.h>

Reads out the currently set friendly name of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	friendlyName	Pointer to a buffer which will contain the currently set friendly name, afterwards. This parameter can be NULL. If it is NULL the function will set the required buffer length in pLength and return BRAWCAP_STATUS_ERROR_OVERRUN.
[in,out]	pLength	Length of the provided buffer. If the specified length is to short, it will be set to the required length and BRAWCAP_STATUS_ERROR_OVERRUN is returned.

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	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_OVERRUN	Given buffer length was to short.

◆ brawcap_adapter_description()

brawcap_status_t brawcap_adapter_description	(	const brawcap_adapter_name_t	name,
		char *const	description,
		UINT32 *const	pLength
	)

#include <brawcap.h>

Reads out the description of the specified adapter.

Note: Adapter descriptions are set depending on the loaded network adapter driver. This means it will not change as long as the network driver is not changed.

Parameters

[in]	name	Name of the adapter.
[out]	description	Pointer to a buffer which will contain the description, afterwards. This parameter can be NULL. If it is NULL the function will set the required buffer length in pLength and return BRAWCAP_STATUS_ERROR_OVERRUN.
[in,out]	pLength	Length of the provided buffer. If the specified length is to short, it will be set to the required length and BRAWCAP_STATUS_ERROR_OVERRUN is returned.

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	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.
BRAWCAP_STATUS_ERROR_OVERRUN	Given buffer length was to short.

Examples: 01_adapter_property_reader.c.

◆ brawcap_adapter_description_by_handle()

brawcap_status_t brawcap_adapter_description_by_handle	(	brawcap_handle_t *const	pHandle,
		char *const	description,
		UINT32 *const	pLength
	)

#include <brawcap.h>

Reads out the description of a network adapter based on the specified adapter.

Note: Adapter descriptions are set depending on the loaded network adapter driver. This means it will not change as long as the network driver is not changed.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	description	Pointer to a buffer which will contain the description, afterwards. This parameter can be NULL. If it is NULL the required buffer length will be set for pLength and the function will return BRAWCAP_STATUS_ERROR_OVERRUN.
[in,out]	pLength	Length of the provided buffer. If the specified length is to short, it will be set to the required length and BRAWCAP_STATUS_ERROR_OVERRUN is returned.

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	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_OVERRUN	Given buffer length was to short.

◆ brawcap_adapter_ipv4()

brawcap_status_t brawcap_adapter_ipv4	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_ipv4_t *const	pIpv4
	)

#include <brawcap.h>

Reads out the currently set IPv4 address of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pIpv4	Will contain the currently set IPv4 address, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_ipv4_by_handle()

brawcap_status_t brawcap_adapter_ipv4_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_ipv4_t *const	pIpv4
	)

#include <brawcap.h>

Reads out the currently set IPv4 address of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pIpv4	Will contain the currently set IPv4 address, 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_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_ipv6()

brawcap_status_t brawcap_adapter_ipv6	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_ipv6_t *const	pIpv6
	)

#include <brawcap.h>

Reads out the currently set IPv6 address of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pIpv6	Will contain the currently set IPv6 address, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_ipv6_by_handle()

brawcap_status_t brawcap_adapter_ipv6_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_ipv6_t *const	pIpv6
	)

#include <brawcap.h>

Reads out the currently set IPv6 address of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pIpv6	Will contain the currently set IPv6 address, 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_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_mac()

brawcap_status_t brawcap_adapter_mac	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_mac_t	mac
	)

#include <brawcap.h>

Reads out the MAC address of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	mac	Will contain the MAC address, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c.

◆ brawcap_adapter_mac_by_handle()

brawcap_status_t brawcap_adapter_mac_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_mac_t	mac
	)

#include <brawcap.h>

Reads out the MAC address of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	mac	Will contain the MAC address, 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_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_speed_rx()

brawcap_status_t brawcap_adapter_speed_rx	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_speed_t *const	pSpeed
	)

#include <brawcap.h>

Reads out the current receive speed of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pSpeed	Will contain the current receive speed, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_speed_rx_by_handle()

brawcap_status_t brawcap_adapter_speed_rx_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_speed_t *const	pSpeed
	)

#include <brawcap.h>

Reads out the current receive speed of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pSpeed	Will contain the current receive speed, 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_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_speed_tx()

brawcap_status_t brawcap_adapter_speed_tx	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_speed_t *const	pSpeed
	)

#include <brawcap.h>

Reads out the current transmit speed of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pSpeed	Will contain the current transmit speed, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_speed_tx_by_handle()

brawcap_status_t brawcap_adapter_speed_tx_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_speed_t *const	pSpeed
	)

#include <brawcap.h>

Reads out the current transmit speed of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pSpeed	Will contain the current transmit speed, 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_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_connection()

brawcap_status_t brawcap_adapter_connection	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_connection_state_t *const	pConnection
	)

#include <brawcap.h>

Reads out the current connection state of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pConnection	Will contain the current connection 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_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_connection_by_handle()

brawcap_status_t brawcap_adapter_connection_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_connection_state_t *const	pConnection
	)

#include <brawcap.h>

Reads out the current connection state of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pConnection	Will contain the current connection 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_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_operation()

brawcap_status_t brawcap_adapter_operation	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_operation_state_t *const	pOperation
	)

#include <brawcap.h>

Reads out the current operation state of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pOperation	Will contain the current operation 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_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_operation_by_handle()

brawcap_status_t brawcap_adapter_operation_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_operation_state_t *const	pOperation
	)

#include <brawcap.h>

Reads out the current operation state of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pOperation	Will contain the current operation 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_STATUS_ERROR_NOT_AVAILABLE	Not available in demo mode (no license).

◆ brawcap_adapter_mtu()

brawcap_status_t brawcap_adapter_mtu	(	const brawcap_adapter_name_t	name,
		brawcap_adapter_mtu_t *const	pMtu
	)

#include <brawcap.h>

Reads out the configured MTU of the specified adapter.

Parameters

[in]	name	Name of the adapter.
[out]	pMtu	Will contain the configured MTU, 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_NOT_AVAILABLE	Not available in demo mode (no license).
BRAWCAP_STATUS_ERROR_NOT_FOUND	Adapter name not found/not available.

Examples: 01_adapter_property_reader.c, and 02_adapter_change_notifier.c.

◆ brawcap_adapter_mtu_by_handle()

brawcap_status_t brawcap_adapter_mtu_by_handle	(	brawcap_handle_t *const	pHandle,
		brawcap_adapter_mtu_t *const	pMtu
	)

#include <brawcap.h>

Reads out the configured MTU of the specified adapter.

Parameters

[in]	pHandle	The bRAWcap handle to read from.
[out]	pMtu	Will contain the configured MTU, 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_NOT_AVAILABLE	Not available in demo mode (no license).

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ brawcap_adapter_ipv4_t

◆ brawcap_adapter_ipv6_t

Macro Definition Documentation

◆ BRAWCAP_ADAPTER_NAME_LENGTH

Typedef Documentation

◆ brawcap_adapter_mac_t

◆ brawcap_adapter_name_t

◆ brawcap_adapter_mtu_t

◆ brawcap_adapter_notify_callback_t

◆ brawcap_adapter_notify_handle_callback_t

Enumeration Type Documentation

◆ brawcap_adapter_speed_t

◆ brawcap_adapter_connection_state_t

◆ brawcap_adapter_operation_state_t

◆ brawcap_adapter_notify_reason_t

◆ brawcap_adapter_properties_t

Function Documentation

◆ brawcap_adapter_list_update()

◆ brawcap_adapter_list_count()

◆ brawcap_adapter_list_at()

◆ brawcap_adapter_notify_register()

◆ brawcap_adapter_notify_unregister()

◆ brawcap_adapter_notify_handle_register()

◆ brawcap_adapter_notify_handle_unregister()

◆ brawcap_adapter_name_by_handle()

◆ brawcap_adapter_friendly_name()

◆ brawcap_adapter_friendly_name_by_handle()

◆ brawcap_adapter_description()

◆ brawcap_adapter_description_by_handle()

◆ brawcap_adapter_ipv4()

◆ brawcap_adapter_ipv4_by_handle()

◆ brawcap_adapter_ipv6()

◆ brawcap_adapter_ipv6_by_handle()

◆ brawcap_adapter_mac()

◆ brawcap_adapter_mac_by_handle()

◆ brawcap_adapter_speed_rx()

◆ brawcap_adapter_speed_rx_by_handle()

◆ brawcap_adapter_speed_tx()

◆ brawcap_adapter_speed_tx_by_handle()

◆ brawcap_adapter_connection()

◆ brawcap_adapter_connection_by_handle()

◆ brawcap_adapter_operation()

◆ brawcap_adapter_operation_by_handle()

◆ brawcap_adapter_mtu()

◆ brawcap_adapter_mtu_by_handle()