Types and functions for operating with bRAWcap receive filters. More...

Data Structures
struct	brawcap_bpf_insn_t
	A single BPF pseudo-instruction. More...

struct	brawcap_bpf_program_t
	A BPF pseudo-assembly program. More...

Macros
#define	BRAWCAP_FILTER_BYTE_MAX_LENGTH 64U
	The maximum supported filter byte mask length in bytes.

Typedefs
typedef UINT8	brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
	Fixed size array for storing a filter byte mask.

typedef UINT8	brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
	Fixed size array for storing a byte wise bitfield.

typedef brawcap_packet_size_t	brawcap_filter_byte_length_t
	Type for specifying the byte filter length.

typedef struct _brawcap_filter	brawcap_filter_t
	bRAWcap filter object.

Enumerations
enum	brawcap_filter_type_t { BRAWCAP_FILTER_TYPE_BYTE_MASK = 0 , BRAWCAP_FILTER_TYPE_BPF = 1 }
	List of filter types. More...

Functions
brawcap_status_t	brawcap_filter_create (brawcap_filter_t **const pFilter, const brawcap_filter_type_t type)
	Creates a new filter.

brawcap_status_t	brawcap_filter_free (brawcap_filter_t *pFilter)
	Frees the specified filter. When this function is called the given filter becomes invalid and it´s memory will be released.

brawcap_status_t	brawcap_filter_type_get (brawcap_filter_t const pFilter, brawcap_filter_type_t const pType)
	Reads out the type for the specified filter.

brawcap_status_t	brawcap_filter_mask_set (brawcap_filter_t *const pFilter, const brawcap_filter_byte_length_t offset, const brawcap_filter_byte_length_t length, const brawcap_filter_mask_array_t mask, const brawcap_filter_ignore_bits_array_t ignoreBits)
	Sets the filter parameters for the specified filter.

brawcap_status_t	brawcap_filter_mask_get (brawcap_filter_t const pFilter, brawcap_filter_byte_length_t const pOffset, brawcap_filter_byte_length_t const pLength, brawcap_filter_mask_array_t const pMask, brawcap_filter_ignore_bits_array_t *const pIgnoreBits)
	Reads out the filter mask parameters for the specified filter.

brawcap_status_t	brawcap_filter_activate (brawcap_filter_t *const pFilter)
	Sets the specified filter to active.

brawcap_status_t	brawcap_filter_deactivate (brawcap_filter_t *const pFilter)
	Sets the specified filter to inactive.

brawcap_status_t	brawcap_filter_is_activated (brawcap_filter_t const pFilter, BOOLEAN const pActive)
	Reads out the current activation state of the specified filter.

brawcap_status_t	brawcap_filter_bytes_to_capture_set (brawcap_filter_t *const pFilter, const brawcap_packet_size_t offset, const brawcap_packet_size_t length)
	Sets the bytes to capture of the specified filter.

brawcap_status_t	brawcap_filter_bytes_to_capture_get (brawcap_filter_t const pFilter, brawcap_packet_size_t const pOffset, brawcap_packet_size_t *const pLength)
	Reads out the configured bytes to capture of the specified filter.

brawcap_status_t	brawcap_filter_indicate_set (brawcap_filter_t *const pFilter, const BOOLEAN indicate)
	Specifies if packets which matched the specified filter should be indicated to the network stack.

brawcap_status_t	brawcap_filter_indicate_get (brawcap_filter_t const pFilter, BOOLEAN const pIndicate)
	Reads out the current network stack indication state of the specified filter.

Detailed Description

Types and functions for operating with bRAWcap receive filters.

To create a new filter use brawcap_filter_create. If a filter is not required anymore it shall be deleted with brawcap_filter_free.

Note: Applying filters to handles:
Each bRAWcap handle has it´s own filter instance. Therefore after applying the filter to a bRAWcap handle the filter may be reused to apply the same (or a different) filter to another handle or freed if not required anymore.

List of examples:

Firewall

Data Structure Documentation

◆ bpf_insn

struct bpf_insn

A single BPF pseudo-instruction.

Contains a single instruction for the BPF.

Data Fields
USHORT	code	Instruction type and addressing mode.
UCHAR	jt	Jump if true.
UCHAR	jf	Jump if false.
UINT32	k	Generic field used for various purposes.

◆ bpf_program

struct bpf_program

A BPF pseudo-assembly program.

The BPF program can be used to filter incoming packets. To get a BPF program it has to be generated/compiled from a BPF filter string, first.

Data Fields
UINT	bf_len	Indicates the number of instructions of the program.
struct bpf_insn *	bf_insns	A pointer to the first instruction of the program.

Typedef Documentation

◆ brawcap_filter_mask_array_t

typedef UINT8 brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]

#include <brawcap_types_shared.h>

Fixed size array for storing a filter byte mask.

Note: It is not necessary to set all bytes. If the used filter does not require the complete mask length. bRAWcap evaluates only the bytes up to the specified filter length.

Examples: 06_filter_firewall.c.

◆ brawcap_filter_ignore_bits_array_t

typedef UINT8 brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]

#include <brawcap_types_shared.h>

Fixed size array for storing a byte wise bitfield.

This allows to ignore specific bits in the specified filter byte mask. Each bit which is set to one is ignored in the filter byte mask.

Note: It is not necessary to set all bytes. If the used filter does not require the complete mask length. bRAWcap evaluates only the bytes up to the specified filter length.

Examples: 06_filter_firewall.c.

◆ brawcap_filter_t

typedef struct _brawcap_filter brawcap_filter_t

#include <brawcap_types_shared.h>

bRAWcap filter object.

The filter object can be accessed with the bRAWcap filter functions. Filters can be created and freed.

Enumeration Type Documentation

◆ brawcap_filter_type_t

enum brawcap_filter_type_t

#include <brawcap_types_shared.h>

List of filter types.

Note: Currently only the byte filter is supported. A BPF (Berkley Packet Filter) filter, which is equivalent to the one which libpcap uses, may be added in the future.

Enumerator
BRAWCAP_FILTER_TYPE_BYTE_MASK	A bRAWcap byte filter.
BRAWCAP_FILTER_TYPE_BPF	A Berkley Packet Filter.

Function Documentation

◆ brawcap_filter_create()

brawcap_status_t brawcap_filter_create	(	brawcap_filter_t **const	pFilter,
		const brawcap_filter_type_t	type
	)

#include <brawcap.h>

Creates a new filter.

The created filter can be used for filtering received packets by applying it to a bRAWcap handle with brawcap_rx_filter_set.

If a created filter is not required anymore it should be freed with brawcap_filter_free.

Note: Currently only the BRAWCAP_FILTER_TYPE_BYTE_MASK filter type is supported. Support for BRAWCAP_FILTER_TYPE_BPF may be added later on.

Parameters

[in]	pFilter	Will contain the new created filter.
[in]	type	Specifies the type of the created filter.

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	Specified filter type is not supported.
BRAWCAP_STATUS_ERROR_FAILED	System error occurred (e.g. out of memory).

Examples: 06_filter_firewall.c.

◆ brawcap_filter_free()

brawcap_status_t brawcap_filter_free ( brawcap_filter_t * pFilter )

#include <brawcap.h>

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

Warning: Freeing a filter is not thread safe and the user is responsible for synchronization.

Parameters

[in] pFilter The filter 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: 06_filter_firewall.c.

◆ brawcap_filter_type_get()

brawcap_status_t brawcap_filter_type_get	(	brawcap_filter_t *const	pFilter,
		brawcap_filter_type_t *const	pType
	)

#include <brawcap.h>

Reads out the type for the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pType	Will contain the filter type, afterwards.

Returns

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

◆ brawcap_filter_mask_set()

brawcap_status_t brawcap_filter_mask_set	(	brawcap_filter_t *const	pFilter,
		const brawcap_filter_byte_length_t	offset,
		const brawcap_filter_byte_length_t	length,
		const brawcap_filter_mask_array_t	mask,
		const brawcap_filter_ignore_bits_array_t	ignoreBits
	)

#include <brawcap.h>

Sets the filter parameters for the specified filter.

Note: Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	offset	Byte offset of the filter. This value specifies at which packet byte offset the first filter byte shall be applied.
[in]	length	Byte length of the filter. Specifies the number of bytes used by the filter. This value is limited to BRAWCAP_FILTER_BYTE_MAX_LENGTH.
[in]	mask	The byte mask for the filter. This is a fixed size byte array. Set the byte values to the filter you want to apply. Only bytes up to the specified filter length are used and following bytes will be ignored.
[in]	ignoreBits	A fixed size bitfield byte array. The bytes in this array has to be interpreted/used as bitfields. This allows to select if a single bit at the corresponding mask position shall be ignored. To ignore the value of a bit set it´s value to 1. Like the mask, only bytes up to the specified filter length are used and following bytes will be ignored.

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	Specified filter is not of type BRAWCAP_FILTER_TYPE_BYTE_MASK.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Specified offset+length exceeds BRAWCAP_FILTER_BYTE_MAX_LENGTH.

Examples: 06_filter_firewall.c.

◆ brawcap_filter_mask_get()

brawcap_status_t brawcap_filter_mask_get	(	brawcap_filter_t *const	pFilter,
		brawcap_filter_byte_length_t *const	pOffset,
		brawcap_filter_byte_length_t *const	pLength,
		brawcap_filter_mask_array_t *const	pMask,
		brawcap_filter_ignore_bits_array_t *const	pIgnoreBits
	)

#include <brawcap.h>

Reads out the filter mask parameters for the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pOffset	Will contain the filter byte offset, afterwards.
[out]	pLength	Will contain the filter byte length, afterwards.
[out]	pMask	Will contain the filter mask bytes, afterwards.
[out]	pIgnoreBits	Will contain the filter bits to ignore, 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	Specified filter is not of type BRAWCAP_FILTER_TYPE_BYTE_MASK.

◆ brawcap_filter_activate()

brawcap_status_t brawcap_filter_activate ( brawcap_filter_t *const pFilter )

#include <brawcap.h>

Sets the specified filter to active.

Note: Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in] pFilter The filter to be modified.

Returns

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

Examples: 06_filter_firewall.c.

◆ brawcap_filter_deactivate()

brawcap_status_t brawcap_filter_deactivate ( brawcap_filter_t *const pFilter )

#include <brawcap.h>

Sets the specified filter to inactive.

Note: Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in] pFilter The filter to be modified.

Returns

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

◆ brawcap_filter_is_activated()

brawcap_status_t brawcap_filter_is_activated	(	brawcap_filter_t *const	pFilter,
		BOOLEAN *const	pActive
	)

#include <brawcap.h>

Reads out the current activation state of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pActive	Will contain the activation state, afterwards.

Returns

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

◆ brawcap_filter_bytes_to_capture_set()

brawcap_status_t brawcap_filter_bytes_to_capture_set	(	brawcap_filter_t *const	pFilter,
		const brawcap_packet_size_t	offset,
		const brawcap_packet_size_t	length
	)

#include <brawcap.h>

Sets the bytes to capture of the specified filter.

Note: Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	offset	The byte offset, from packet payload beginning, to begin capturing the payload bytes.
[in]	length	The number of bytes to be captured - beginning at offset.

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 offset+length exceeds BRAWCAP_PACKET_SIZE_MAX.

◆ brawcap_filter_bytes_to_capture_get()

brawcap_status_t brawcap_filter_bytes_to_capture_get	(	brawcap_filter_t *const	pFilter,
		brawcap_packet_size_t *const	pOffset,
		brawcap_packet_size_t *const	pLength
	)

#include <brawcap.h>

Reads out the configured bytes to capture of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pOffset	Will contain the byte offset of the bytes to capture, afterwards.
[out]	pLength	Will contain the number of bytes to capture, afterwards.

Returns

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

◆ brawcap_filter_indicate_set()

brawcap_status_t brawcap_filter_indicate_set	(	brawcap_filter_t *const	pFilter,
		const BOOLEAN	indicate
	)

#include <brawcap.h>

Specifies if packets which matched the specified filter should be indicated to the network stack.

Note: Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	indicate	Flag specifying the network stack indication. If true filtered packets are forwarded to the network stack. If false filtered packets are not forwarded to the network stack, they are only visible for bRAWcap handles.

Returns

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

Examples: 06_filter_firewall.c.

◆ brawcap_filter_indicate_get()

brawcap_status_t brawcap_filter_indicate_get	(	brawcap_filter_t *const	pFilter,
		BOOLEAN *const	pIndicate
	)

#include <brawcap.h>

Reads out the current network stack indication state of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pIndicate	Will contain the current network stack indication, afterwards.

Returns

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ bpf_insn

◆ bpf_program

Typedef Documentation

◆ brawcap_filter_mask_array_t

◆ brawcap_filter_ignore_bits_array_t

◆ brawcap_filter_t

Enumeration Type Documentation

◆ brawcap_filter_type_t

Function Documentation

◆ brawcap_filter_create()

◆ brawcap_filter_free()

◆ brawcap_filter_type_get()

◆ brawcap_filter_mask_set()

◆ brawcap_filter_mask_get()

◆ brawcap_filter_activate()

◆ brawcap_filter_deactivate()

◆ brawcap_filter_is_activated()

◆ brawcap_filter_bytes_to_capture_set()

◆ brawcap_filter_bytes_to_capture_get()

◆ brawcap_filter_indicate_set()

◆ brawcap_filter_indicate_get()