diff --git a/sdk/c/doc/html/2_bplus_generic_extensions.css b/sdk/c/doc/html/2_bplus_generic_extensions.css index fa27149..1760c23 100644 --- a/sdk/c/doc/html/2_bplus_generic_extensions.css +++ b/sdk/c/doc/html/2_bplus_generic_extensions.css @@ -192,6 +192,13 @@ html { } } +@media screen and (min-width: 1000px) { + #doc-content > div > div.contents, + .PageDoc > div.contents { + display: block; + } +} + @media (prefers-color-scheme: dark) { html:not(.light-mode) { color-scheme: dark; diff --git a/sdk/c/doc/html/a00002.html b/sdk/c/doc/html/a00002.html new file mode 100644 index 0000000..e845611 --- /dev/null +++ b/sdk/c/doc/html/a00002.html @@ -0,0 +1,130 @@ + + + + + + + + +bRAWcap: libbrawcap.h File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+
libbrawcap.h File Reference
+
+
+ +

bRAWcap main header. +More...

+
#include "brawcap/brawcap.h"
+
+

Go to the source code of this file.

+

Detailed Description

+

bRAWcap main header.

+

This should be included by any project which want to make use of bRAWcap. It will handle the includes of all further required headers.

+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus technologies GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00002_source.html b/sdk/c/doc/html/a00002_source.html new file mode 100644 index 0000000..2941eaa --- /dev/null +++ b/sdk/c/doc/html/a00002_source.html @@ -0,0 +1,136 @@ + + + + + + + + +bRAWcap: libbrawcap.h Source File + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
libbrawcap.h
+
+
+Go to the documentation of this file.
1/**
+
2 * @file libbrawcap.h
+
3 * @brief bRAWcap main header.
+
4 *
+
5 * This should be included by any project which want to make use of bRAWcap.
+
6 * It will handle the includes of all further required headers.
+
7 *
+
8 * @copyright
+
9 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
10 *
+
11 * All rights exclusively reserved for b-plus technologies GmbH, unless expressly otherwise agreed.
+
12 *
+
13 * Redistribution in source or any other form, with or without modification, is not permitted.
+
14 *
+
15 * You may use this code under the according license terms of b-plus.
+
16 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
17 */
+
18#include "brawcap/brawcap.h"
+
brawcap.h
bRAWcap API - Functions.
+
+ + + + + + diff --git a/sdk/c/doc/html/a00005.html b/sdk/c/doc/html/a00005.html new file mode 100644 index 0000000..40fb2d8 --- /dev/null +++ b/sdk/c/doc/html/a00005.html @@ -0,0 +1,141 @@ + + + + + + + + +bRAWcap: 01_adapter_property_reader.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
01_adapter_property_reader.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates the usage of the adapter handling module. +More...

+
#include "libbrawcap.h"
+#include <stdlib.h>
+#include <stdio.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates the usage of the adapter handling module.

+

It shows how to:

+

This example makes use of C only.

+
Attention
This example requires a valid bRAWcap license. Reading adapter properties is not part of the demo.
+
Version
1.0
+
Date
2023-03-24
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00008.html b/sdk/c/doc/html/a00008.html new file mode 100644 index 0000000..f741a2a --- /dev/null +++ b/sdk/c/doc/html/a00008.html @@ -0,0 +1,141 @@ + + + + + + + + +bRAWcap: 02_adapter_change_notifier.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
02_adapter_change_notifier.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates the usage of the adapter handling module. +More...

+
#include "libbrawcap.h"
+#include <stdlib.h>
+#include <stdio.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates the usage of the adapter handling module.

+

It shows how to:

+

This example makes use of C only.

+
Attention
This example requires a valid bRAWcap license. Receiving adapter change notifications and reading their properties is not part of the demo.
+
Version
1.0
+
Date
2023-03-24
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00011.html b/sdk/c/doc/html/a00011.html new file mode 100644 index 0000000..a3bf701 --- /dev/null +++ b/sdk/c/doc/html/a00011.html @@ -0,0 +1,141 @@ + + + + + + + + +bRAWcap: 03_generic_handle_opener.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
03_generic_handle_opener.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates the usage of the generic bRAWcap functions. +More...

+
#include "libbrawcap.h"
+#include <stdlib.h>
+#include <stdio.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates the usage of the generic bRAWcap functions.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.0
+
Date
2023-03-28
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00014.html b/sdk/c/doc/html/a00014.html new file mode 100644 index 0000000..dcae8bf --- /dev/null +++ b/sdk/c/doc/html/a00014.html @@ -0,0 +1,140 @@ + + + + + + + + +bRAWcap: 04_version_comparator.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
04_version_comparator.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates how to use the bRAWcap version. +More...

+
#include "libbrawcap.h"
+#include <stdio.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates how to use the bRAWcap version.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.0
+
Date
2023-03-28
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00017.html b/sdk/c/doc/html/a00017.html new file mode 100644 index 0000000..0aacc20 --- /dev/null +++ b/sdk/c/doc/html/a00017.html @@ -0,0 +1,141 @@ + + + + + + + + +bRAWcap: 05_receive_simple_packet_receiver.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
05_receive_simple_packet_receiver.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets. +More...

+
#include "libbrawcap.h"
+#include <stdio.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.1
+
Date
2023-03-30
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00020.html b/sdk/c/doc/html/a00020.html new file mode 100644 index 0000000..15db121 --- /dev/null +++ b/sdk/c/doc/html/a00020.html @@ -0,0 +1,142 @@ + + + + + + + + +bRAWcap: 06_filter_firewall.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
06_filter_firewall.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates how to throw away specific received packets. +More...

+
#include "libbrawcap.h"
+#include <stdlib.h>
+#include <stdio.h>
+#include <time.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates how to throw away specific received packets.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.0
+
Date
2023-03-28
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00023.html b/sdk/c/doc/html/a00023.html new file mode 100644 index 0000000..092406f --- /dev/null +++ b/sdk/c/doc/html/a00023.html @@ -0,0 +1,144 @@ + + + + + + + + +bRAWcap: 07_receive_buffered_receiver.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
07_receive_buffered_receiver.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers. +More...

+
#include "libbrawcap.h"
+#include <stdio.h>
+#include <stdlib.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.1
+
Date
2023-03-30
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00026.html b/sdk/c/doc/html/a00026.html new file mode 100644 index 0000000..fdd63aa --- /dev/null +++ b/sdk/c/doc/html/a00026.html @@ -0,0 +1,143 @@ + + + + + + + + +bRAWcap: 08_receive_timestamp_inspector.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
08_receive_timestamp_inspector.c File Reference
+
+
+ +

bRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes. +More...

+
#include "libbrawcap.h"
+#include <stdio.h>
+#include <time.h>
+

Detailed Description

+

bRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes.

+

It shows how to:

+

This example makes use of C only.

+
Version
1.1
+
Date
2023-03-30
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00029.html b/sdk/c/doc/html/a00029.html new file mode 100644 index 0000000..5b4f1d9 --- /dev/null +++ b/sdk/c/doc/html/a00029.html @@ -0,0 +1,133 @@ + + + + + + + + +bRAWcap: 09_transmit_simple_packet_transmitter.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
09_transmit_simple_packet_transmitter.c File Reference
+
+
+ +

bRAWcap Example - TODO: +More...

+
#include "libbrawcap.h"
+

Detailed Description

+

bRAWcap Example - TODO:

+
Version
1.0
+
Date
TODO:
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00032.html b/sdk/c/doc/html/a00032.html new file mode 100644 index 0000000..8501dba --- /dev/null +++ b/sdk/c/doc/html/a00032.html @@ -0,0 +1,133 @@ + + + + + + + + +bRAWcap: 10_transmit_buffered_transmitter.c File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
10_transmit_buffered_transmitter.c File Reference
+
+
+ +

bRAWcap Example - TODO: +More...

+
#include "libbrawcap.h"
+

Detailed Description

+

bRAWcap Example - TODO:

+
Version
1.0
+
Date
TODO:
+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00035.html b/sdk/c/doc/html/a00035.html new file mode 100644 index 0000000..bf69f4d --- /dev/null +++ b/sdk/c/doc/html/a00035.html @@ -0,0 +1,482 @@ + + + + + + + + +bRAWcap: brawcap.h File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
+Functions
+
brawcap.h File Reference
+
+
+ +

bRAWcap API - Functions. +More...

+
#include "brawcap_types_um.h"
+
+

Go to the source code of this file.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

brawcap_status_t brawcap_log_level_set (const brawcap_log_type_t type, const brawcap_log_level_t level, const char *pKey)
 Sets the current log level for the given log type to the specified log level.
 
brawcap_status_t brawcap_log_levels_set (const UINT32 type, const UINT32 level, const char *pKey)
 Sets the current log levels for the given log types to the specified log levels.
 
brawcap_status_t brawcap_log_level_get (const brawcap_log_type_t type, brawcap_log_level_t *const pLevel)
 Reads the level(s) for the given log type.
 
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.
 
brawcap_status_t brawcap_last_status ()
 Reads the last status appeared in bRAWcap, for the calling thread.
 
brawcap_status_t brawcap_version_api (brawcap_version_t *const pVersion)
 Returns loaded bRAWcap library version.
 
brawcap_status_t brawcap_version_driver (brawcap_handle_t *const pHandle, brawcap_version_t *const pVersion)
 Reads current version of loaded bRAWcap driver.
 
brawcap_status_t brawcap_timestamp_mode_get (brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_mode_t *const pMode)
 Reads out the mode of the specified timestamp.
 
brawcap_status_t brawcap_timestamp_resolution_ns_get (brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_resolution_ns_t *const pResolution_ns)
 Reads out the timestamp resolution of the specified timestamp.
 
brawcap_status_t brawcap_timestamp_value_ns_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pNanoseconds)
 Reads out the timestamp value in seconds and nanoseconds.
 
brawcap_status_t brawcap_timestamp_value_ns_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 nanoseconds)
 Sets the timestamp value in seconds and nanoseconds.
 
brawcap_status_t brawcap_timestamp_value_us_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMicroseconds)
 Reads out the timestamp value in seconds and microseconds.
 
brawcap_status_t brawcap_timestamp_value_us_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 microseconds)
 Sets the timestamp value in seconds and microseconds.
 
brawcap_status_t brawcap_timestamp_value_ms_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMilliseconds)
 Reads out the timestamp value in seconds and milliseconds.
 
brawcap_status_t brawcap_timestamp_value_ms_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 milliseconds)
 Sets the timestamp value in seconds and milliseconds.
 
brawcap_status_t brawcap_packet_create (brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
 Creates a new packet.
 
brawcap_status_t brawcap_packet_free (brawcap_packet_t *pPacket)
 Frees the specified packet. When this function is called the specified packet becomes invalid and it´s memory is released.
 
brawcap_status_t brawcap_packet_status_get (brawcap_packet_t *const pPacket, brawcap_status_t *const pStatus)
 Reads out the status for the specified packet. The status will be set updated during reception/transmission. It indicates the status of the packet depending on the operation.
 
brawcap_status_t brawcap_packet_timestamp_get (brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
 Reads out the timestamp object for the specified packet.
 
brawcap_status_t brawcap_packet_length_on_wire_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLengthOnWire)
 Reads out the length on wire of the specified packet. This value is especially useful for received packets. It indicates the total packet payload byte size of the packet on wire. This may not equal to the captured payload byte size. Because the payload byte size depends on the configured filter and it´s bytes to capture parameters.
 
brawcap_status_t brawcap_packet_payload_max_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pMaxPayloadSize)
 Reads out the max supported payload byte size of the specified packet. This value was set during packet creation (or buffer creation if it´s a buffered packet).
 
brawcap_status_t brawcap_packet_payload_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLength)
 Reads out the captured payload byte size of the specified packet. This indicates the total byte size of the (captured - if received) packet payload.
 
brawcap_status_t brawcap_packet_payload_get (brawcap_packet_t *const pPacket, const char **const pPayload, brawcap_packet_size_t *const pLength)
 Reads out the payload of the specified packet.
 
brawcap_status_t brawcap_packet_payload_set (brawcap_packet_t *const pPacket, const char *const pPayload, const brawcap_packet_size_t length)
 Sets the packet payload of the specified packet.
 
brawcap_status_t brawcap_buffer_create (brawcap_buffer_t **const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize, const brawcap_buffer_packet_count_t numPackets)
 Creates a new packet buffer.
 
brawcap_status_t brawcap_buffer_free (brawcap_buffer_t *pBuffer)
 Frees the specified packet buffer. When this function is called the specified packet buffer becomes invalid and it´s memory will be released.
 
brawcap_status_t brawcap_buffer_clear (brawcap_buffer_t *const pBuffer)
 Clears the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_back (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
 Adds the specified packet at the end of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_front (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
 Adds the specified packet at the front of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_at_index (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket, const brawcap_buffer_packet_count_t index)
 Inserts the specified packet at index/position into the specified packet buffer.
 
brawcap_status_t brawcap_buffer_at_index (brawcap_buffer_t *const pBuffer, const brawcap_buffer_packet_count_t index, brawcap_packet_t **const pPacket)
 Reads out a buffered packet at the index of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_front (brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
 Reads out the first buffered packet of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_back (brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
 Reads out the last buffered packet of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_count (brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCount)
 Reads out the number of currently buffered packets in the specified packet buffer.
 
brawcap_status_t brawcap_buffer_capacity (brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCapacity)
 Reads out the total number of packets which can be buffered by the specified packet buffer. This value represents the packet buffer capacity, which is set during buffer creation.
 
brawcap_status_t brawcap_buffer_iterator_create (brawcap_buffer_iterator_t **const pIterator, brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t startPosition)
 Creates a new iterator for the specified buffer.
 
brawcap_status_t brawcap_buffer_iterator_free (brawcap_buffer_iterator_t *const pIterator)
 Frees the specified iterator. When this function is called the specified iterator becomes invalid and it´s memory will be released.
 
brawcap_status_t brawcap_buffer_iterator_next (brawcap_buffer_iterator_t *const pIterator)
 Increments the iterator to the next buffered packet.
 
brawcap_status_t brawcap_buffer_iterator_prev (brawcap_buffer_iterator_t *const pIterator)
 Decreases the iterator to the previous buffered packet.
 
brawcap_packet_t * brawcap_buffer_iterator_eval (brawcap_buffer_iterator_t *const pIterator)
 Returns the buffered packet for the specified iterator.
 
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.
 
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.
 
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.
 
brawcap_status_t brawcap_tx_packet (brawcap_handle_t *const pHandle, brawcap_packet_t *const pPacket)
 Transmits a single packet on the specified handle.
 
brawcap_status_t brawcap_tx_start (brawcap_handle_t *const pHandle, brawcap_tx_callback_t const callback, void *pUser)
 Starts the internal transmit loop.
 
brawcap_status_t brawcap_tx_stop (brawcap_handle_t *const pHandle)
 Stops the internal transmit loop.
 
brawcap_status_t brawcap_tx_buffer_send (brawcap_handle_t *const pHandle, brawcap_buffer_t *const pBuffer, const BOOLEAN synchronized)
 Pushes the specified buffer to the specified handle transmit queue.
 
brawcap_status_t brawcap_tx_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_tx_driver_queue_size_get (brawcap_handle_t *const pHandle, brawcap_queue_size_t *const pSize)
 Reads out the currently configured driver transmit queue size for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_capabilities (brawcap_handle_t *const pHandle, brawcap_timestamp_capabilities_t *const pCapabilities)
 Reads out the available transmit timestamp modes for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_mode_set (brawcap_handle_t *const pHandle, const brawcap_timestamp_mode_t mode)
 Configures the used transmit time stamping mode for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_mode_get (brawcap_handle_t *const pHandle, brawcap_timestamp_mode_t *const pMode)
 Reads out the currently configured transmit time stamping mode for the specified handle.
 
brawcap_status_t brawcap_stats_rx (brawcap_handle_t *const pHandle, brawcap_stats_rx_t *const pStats)
 Reads out the available receive statistic counters for the specified handle.
 
brawcap_status_t brawcap_stats_tx (brawcap_handle_t *const pHandle, brawcap_stats_tx_t *const pStats)
 Reads out the available transmit statistic counters for the specified handle.
 
+

Detailed Description

+

bRAWcap API - Functions.

+

This file contains generic parts of the API and includes all specific bRAWcap parts.

+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00035_source.html b/sdk/c/doc/html/a00035_source.html new file mode 100644 index 0000000..8876add --- /dev/null +++ b/sdk/c/doc/html/a00035_source.html @@ -0,0 +1,2912 @@ + + + + + + + + +bRAWcap: brawcap.h Source File + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
brawcap.h
+
+
+Go to the documentation of this file.
1/**
+
2 * @file brawcap.h
+
3 *
+
4 * @brief bRAWcap API - Functions.
+
5 *
+
6 * This file contains generic parts of the API and includes all specific bRAWcap parts.
+
7 *
+
8 * @copyright
+
9 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
10 *
+
11 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
12 *
+
13 * Redistribution in source or any other form, with or without modification, is not permitted.
+
14 *
+
15 * You may use this code under the according license terms of b-plus.
+
16 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
17 */
+
18#ifndef BRAWCAP_H
+
19#define BRAWCAP_H
+
20
+
21#include "brawcap_types_um.h"
+
22
+
23#if defined(__cplusplus)
+
24extern "C"
+
25{
+
26#endif //(__cplusplus)
+
27
+
28/************************************************ LOGGING ************************************************************/
+
29#if 1
+
30/**
+
31 * @addtogroup brawcap_logging
+
32 * @{
+
33 */
+
34
+
35/**
+
36 * @brief Sets the current log level for the given log type to the specified log level.
+
37 *
+
38 * @param[in] type Log type for which to configure the log level.
+
39 *
+
40 * @param[in] level The log level to be applied.
+
41 *
+
42 * @param[in] pKey Key required to activate debug logging.
+
43 * For any other log level than @ref BRAWCAP_LOG_LEVEL_DEBUG this parameter is not required
+
44 * and should be set to NULL.
+
45 *
+
46 * @return
+
47 * Status | Description
+
48 * ---------------------------------------------- | -------------------------------------------------------------------
+
49 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
50 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Attempted to enable debug logging with wrong key.
+
51 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | None of the specified log types is available.
+
52 */
+
53_BRAWCAP_API_FUNC(brawcap_status_t)
+
54brawcap_log_level_set(const brawcap_log_type_t type, const brawcap_log_level_t level, const char* pKey);
+
55
+
56/**
+
57 * @brief Sets the current log levels for the given log types to the specified log levels.
+
58 *
+
59 * @param[in] type Log types for which to configure the log level(s).
+
60 * Value has to be interpreted as bitfield.
+
61 * This allows to (de)activate levels for several types with only one call.
+
62 *
+
63 * @param[in] level The log levels to be applied.
+
64 * Value has to be interpreted as bitfield.
+
65 * This allows to (de)activate several levels with only one call.
+
66 *
+
67 * @param[in] pKey Key required to activate debug logging.
+
68 * For any other log level than @ref BRAWCAP_LOG_LEVEL_DEBUG this parameter is not required
+
69 * and should be set to NULL.
+
70 *
+
71 * @return
+
72 * Status | Description
+
73 * ---------------------------------------------- | -------------------------------------------------------------------
+
74 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
75 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Attempted to enable debug logging with wrong key.
+
76 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | None of the specified log types is available.
+
77 */
+
78_BRAWCAP_API_FUNC(brawcap_status_t)
+
79brawcap_log_levels_set(const UINT32 type, const UINT32 level, const char* pKey);
+
80
+
81/**
+
82 * @brief Reads the level(s) for the given log type.
+
83 *
+
84 * @param[in] type Log type for which to read the log level.
+
85 * It is only possible to retrieve the log level for one type.
+
86 * Call this function for each type to resolve all log levels.
+
87 *
+
88 * @param[out] pLevel Will contain the currently configured log level(s), afterwards.
+
89 * This value shall be interpreted as bitfield, which allows to resolve all log levels for the type with only one call.
+
90 *
+
91 * @return
+
92 * Status | Description
+
93 * ---------------------------------------------- | -------------------------------------------------------------------
+
94 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
95 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
96 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The specified log types is invalid.
+
97 */
+
98_BRAWCAP_API_FUNC(brawcap_status_t)
+
99brawcap_log_level_get(const brawcap_log_type_t type, brawcap_log_level_t* const pLevel);
+
100
+
101/**@}*/
+
102#endif
+
103
+
104/************************************************ GENERIC ************************************************************/
+
105#if 1
+
106/**
+
107 * @addtogroup brawcap_generics
+
108 * @{
+
109 */
+
110
+
111/**
+
112 * @brief Opens a new bRAWcap handle on the adapter, specified by it´s name.
+
113 *
+
114 * The created/opened bRAWcap handle should be saved by the user application and used for calling further bRAWcap
+
115 * functions. Each opened handle shall be @ref brawcap_close "closed", if it is not required anymore.
+
116 *
+
117 * @note On Windows a adapter name is always represented by a GUID.
+
118 *
+
119 * @note bRAWcap supports multiple handles to the same adapter.
+
120 * But the total number of open handles on the same adapter is limited to @ref BRAWCAP_HANDLES_PER_ADAPTER_MAX.
+
121 *
+
122 * @warning Opening multiple handles to the same adapter, with the same receive filter leads to redundancy and
+
123 * performance degradation and therefore should be avoided, if possible.
+
124 *
+
125 * @param[in] name The name of the adapter to open a bRAWcap handle.
+
126 *
+
127 * @param[out] pHandle Will contain the opened bRAWcap handle, afterwards.
+
128 *
+
129 * @return
+
130 * Status | Description
+
131 * ---------------------------------------------- | -------------------------------------------------------------------
+
132 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
133 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
134 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The specified name does not represent a adapter name (GUID).
+
135 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Specified adapter name not found/not available.
+
136 * @ref BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE | bRAWcap driver is not running on specified adapter.
+
137 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
138 */
+
139_BRAWCAP_API_FUNC(brawcap_status_t)
+
140brawcap_open(const brawcap_adapter_name_t name, brawcap_handle_t** const pHandle);
+
141
+
142/**
+
143 * @brief Closes the specified bRAWcap handle.
+
144 *
+
145 * The user application should not use the specified handle anymore, after calling this function.
+
146 *
+
147 * @warning Closing bRAWcap handles is not thread safe and the user is responsible for synchronization.
+
148 *
+
149 * @param[in] pHandle bRAWcap handle to be closed.
+
150 *
+
151 * @return
+
152 * Status | Description
+
153 * ---------------------------------------------- | -------------------------------------------------------------------
+
154 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
155 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
156 * @ref BRAWCAP_STATUS_ERROR_FAILED | A system error occurred.
+
157 */
+
158_BRAWCAP_API_FUNC(brawcap_status_t)
+
159brawcap_close(brawcap_handle_t* pHandle);
+
160
+
161/**@}*/
+
162#endif
+
163
+
164/************************************************** STATUS ***********************************************************/
+
165#if 1
+
166/**
+
167 * @addtogroup brawcap_status
+
168 * @{
+
169 */
+
170
+
171/**
+
172 * @brief Reads the last status appeared in bRAWcap, for the calling thread.
+
173 *
+
174 * The last status is only updated if it does not equal @ref BRAWCAP_STATUS_SUCCESS.
+
175 * Which means that this function shall never be used to check if a bRAWcap function succeeded.
+
176 * Instead this should always be checked on each bRAWcap function return value directly
+
177 * and only if something different than @ref BRAWCAP_STATUS_SUCCESS is returned,
+
178 * this function can be used to get the last status again.
+
179 *
+
180 * The last status may be overwritten when the calling thread calls another bRAWcap function.
+
181 * It is therefore recommended to call this function directly after a bRAWcap function to get the status of that
+
182 * function again.
+
183 *
+
184 * @note If yet, no other status than @ref BRAWCAP_STATUS_SUCCESS occurred for the calling thread,
+
185 * @ref BRAWCAP_STATUS_SUCCESS will be returned.
+
186 *
+
187 * @return
+
188 * Status | Description
+
189 * ---------------------------------------------- | ------------------------------------------------------------------
+
190 * @ref BRAWCAP_STATUS_SUCCESS | If no other status than success happened for the calling thread.
+
191 * Any of @ref brawcap_status_t | Please see return of last called function for detailed info.
+
192 */
+
193_BRAWCAP_API_FUNC(brawcap_status_t)
+
194brawcap_last_status();
+
195
+
196/**@}*/
+
197#endif
+
198
+
199/************************************************ VERSION ************************************************************/
+
200#if 1
+
201/**
+
202 * @addtogroup brawcap_version
+
203 * @{
+
204 */
+
205
+
206/**
+
207 * @brief Returns loaded bRAWcap library version.
+
208 *
+
209 * @param[out] pVersion Will contain the loaded library version, afterwards.
+
210 *
+
211 * @return
+
212 * Status | Description
+
213 * ---------------------------------------------- | ------------------------------------------------------------------
+
214 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
215 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
216 */
+
217_BRAWCAP_API_FUNC(brawcap_status_t)
+
218brawcap_version_api(brawcap_version_t* const pVersion);
+
219
+
220/**
+
221 * @brief Reads current version of loaded bRAWcap driver.
+
222 *
+
223 * @note The driver version is the same for each adapter.
+
224 * Therefore, it doesn´t matter which handle/adapter is used to read the driver version.
+
225 *
+
226 * @param[in] pHandle bRAWcap handle to read from.
+
227 *
+
228 * @param[out] pVersion Will contain the bRAWcap driver version, afterwards.
+
229 *
+
230 * @return
+
231 * Status | Description
+
232 * ---------------------------------------------- | ------------------------------------------------------------------
+
233 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
234 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
235 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
236 */
+
237_BRAWCAP_API_FUNC(brawcap_status_t)
+
238brawcap_version_driver(brawcap_handle_t* const pHandle, brawcap_version_t* const pVersion);
+
239
+
240/**@}*/
+
241#endif
+
242
+
243/*********************************************** TIMESTAMP ***********************************************************/
+
244#if 1
+
245/**
+
246 * @addtogroup brawcap_timestamp
+
247 * @{
+
248 */
+
249
+
250/**
+
251 * @brief Reads out the mode of the specified timestamp.
+
252 *
+
253 * @param[in] pTimestamp The timestamp to read from.
+
254 *
+
255 * @param[out] pMode Will contain the timestamp mode, afterwards.
+
256 *
+
257 * @return
+
258 * Status | Description
+
259 * ---------------------------------------------- | ------------------------------------------------------------------
+
260 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
261 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
262 */
+
263_BRAWCAP_API_FUNC(brawcap_status_t)
+
264brawcap_timestamp_mode_get(brawcap_timestamp_t* const pTimestamp, brawcap_timestamp_mode_t* const pMode);
+
265
+
266/**
+
267 * @brief Reads out the timestamp resolution of the specified timestamp.
+
268 *
+
269 * @note If the resolution is unknown it will be set to zero (@ref BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN)
+
270 *
+
271 * @param[in] pTimestamp The timestamp to read from.
+
272 *
+
273 * @param[out] pResolution_ns Will contain the timestamp resolution in nanoseconds, afterwards.
+
274 *
+
275 * @return
+
276 * Status | Description
+
277 * ---------------------------------------------- | ------------------------------------------------------------------
+
278 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
279 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
280 */
+
281_BRAWCAP_API_FUNC(brawcap_status_t)
+
282brawcap_timestamp_resolution_ns_get(brawcap_timestamp_t* const pTimestamp,
+
283 brawcap_timestamp_resolution_ns_t* const pResolution_ns);
+
284
+
285/**
+
286 * @brief Reads out the timestamp value in seconds and nanoseconds.
+
287 *
+
288 * The values are based on 00:00 01.01.1970.
+
289 *
+
290 * The seconds part contains only whole seconds of the timestamp,
+
291 * while the nanoseconds part contains only the fractional part.
+
292 *
+
293 * @param[in] pTimestamp The timestamp to read from.
+
294 *
+
295 * @param[out] pSeconds Will contain the whole seconds of the timestamp, afterwards.
+
296 *
+
297 * @param[out] pNanoseconds Will contain the fractional part in nanoseconds, afterwards.
+
298 *
+
299 * @return
+
300 * Status | Description
+
301 * ---------------------------------------------- | ------------------------------------------------------------------
+
302 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
303 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
304 */
+
305_BRAWCAP_API_FUNC(brawcap_status_t)
+
306brawcap_timestamp_value_ns_get(brawcap_timestamp_t* const pTimestamp, UINT64* const pSeconds,
+
307 UINT32* const pNanoseconds);
+
308
+
309/**
+
310 * @brief Sets the timestamp value in seconds and nanoseconds.
+
311 *
+
312 * The values has to be based on 00:00 01.01.1970.
+
313 *
+
314 * @param[in] pTimestamp The timestamp to be modified.
+
315 *
+
316 * @param[in] seconds Whole seconds since 00:00 01.01.1970.
+
317 *
+
318 * @param[in] nanoseconds The fractional part in nanoseconds.
+
319 * This parameter should only contain the fractional timestamp part.
+
320 * That means that it can never exceed 999.999.999 nanoseconds.
+
321 *
+
322 * @return
+
323 * Status | Description
+
324 * ---------------------------------------------- | ------------------------------------------------------------------
+
325 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
326 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
327 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Nanosecond value to high (only fraction of second).
+
328 */
+
329_BRAWCAP_API_FUNC(brawcap_status_t)
+
330brawcap_timestamp_value_ns_set(brawcap_timestamp_t* const pTimestamp, const UINT64 seconds, const UINT32 nanoseconds);
+
331
+
332/**
+
333 * @brief Reads out the timestamp value in seconds and microseconds.
+
334 *
+
335 * The values are based on 00:00 01.01.1970.
+
336 *
+
337 * The seconds part contains only whole seconds of the timestamp,
+
338 * while the microseconds contains only the fractional part.
+
339 *
+
340 * @param[in] pTimestamp The timestamp to read from.
+
341 *
+
342 * @param[out] pSeconds Will contain the whole seconds of the timestamp, afterwards.
+
343 *
+
344 * @param[out] pMicroseconds Will contain the fractional part in microseconds, afterwards.
+
345 *
+
346 * @return
+
347 * Status | Description
+
348 * ---------------------------------------------- | ------------------------------------------------------------------
+
349 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
350 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
351 */
+
352_BRAWCAP_API_FUNC(brawcap_status_t)
+
353brawcap_timestamp_value_us_get(brawcap_timestamp_t* const pTimestamp, UINT64* const pSeconds,
+
354 UINT32* const pMicroseconds);
+
355
+
356/**
+
357 * @brief Sets the timestamp value in seconds and microseconds.
+
358 *
+
359 * The values has to be based on 00:00 01.01.1970.
+
360 *
+
361 * @param[in] pTimestamp The timestamp to be modified.
+
362 *
+
363 * @param[in] seconds Whole seconds since 00:00 01.01.1970.
+
364 *
+
365 * @param[in] microseconds The fractional part in microseconds.
+
366 * This parameter should only contain the fractional timestamp part.
+
367 * That means that it can never exceed 999.999 microseconds.
+
368 *
+
369 * @return
+
370 * Status | Description
+
371 * ---------------------------------------------- | ------------------------------------------------------------------
+
372 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
373 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
374 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Nanosecond value to high (only fraction of second).
+
375 *
+
376 */
+
377_BRAWCAP_API_FUNC(brawcap_status_t)
+
378brawcap_timestamp_value_us_set(brawcap_timestamp_t* const pTimestamp, const UINT64 seconds, const UINT32 microseconds);
+
379
+
380/**
+
381 * @brief Reads out the timestamp value in seconds and milliseconds.
+
382 *
+
383 * The values are based on 00:00 01.01.1970.
+
384 *
+
385 * The seconds part contains only whole seconds of the timestamp,
+
386 * while the milliseconds part contains only the fractional part.
+
387 *
+
388 * @param[in] pTimestamp The timestamp to read from.
+
389 *
+
390 * @param[out] pSeconds Will contain the whole seconds of the timestamp, afterwards.
+
391 *
+
392 * @param[out] pMilliseconds Will contain the fractional part in milliseconds, afterwards.
+
393 *
+
394 * @return
+
395 * Status | Description
+
396 * ---------------------------------------------- | ------------------------------------------------------------------
+
397 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
398 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
399 */
+
400_BRAWCAP_API_FUNC(brawcap_status_t)
+
401brawcap_timestamp_value_ms_get(brawcap_timestamp_t* const pTimestamp, UINT64* const pSeconds,
+
402 UINT32* const pMilliseconds);
+
403
+
404/**
+
405 * @brief Sets the timestamp value in seconds and milliseconds.
+
406 *
+
407 * The values has to be based on 00:00 01.01.1970.
+
408 *
+
409 * @param[in] pTimestamp The timestamp to be modified.
+
410 *
+
411 * @param[in] seconds Whole seconds since 00:00 01.01.1970.
+
412 *
+
413 * @param[in] milliseconds The fractional part in milliseconds.
+
414 * This parameter should only contain the fractional timestamp part.
+
415 * That means that it can never exceed 999 milliseconds.
+
416 *
+
417 * @return
+
418 * Status | Description
+
419 * ---------------------------------------------- | ------------------------------------------------------------------
+
420 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
421 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
422 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Nanosecond value to high (only fraction of second).
+
423 */
+
424_BRAWCAP_API_FUNC(brawcap_status_t)
+
425brawcap_timestamp_value_ms_set(brawcap_timestamp_t* const pTimestamp, const UINT64 seconds, const UINT32 milliseconds);
+
426
+
427/**@}*/
+
428#endif
+
429
+
430/************************************************ PACKET *************************************************************/
+
431#if 1
+
432/**
+
433 * @addtogroup brawcap_packet
+
434 * @{
+
435 */
+
436
+
437/**
+
438 * @brief Creates a new packet.
+
439 *
+
440 * A packet can be used for @ref brawcap_rx_packet "receiving" (single packet based) or
+
441 * @ref brawcap_tx_packet "transmitting"
+
442 * (also single packet based).
+
443 *
+
444 * If a packet is not required anymore it should be @ref brawcap_packet_free "freed".
+
445 *
+
446 * @param[out] pPacket Will contain the new created packet, afterwards.
+
447 *
+
448 * @param[in] maxSize The maximum supported byte size for the packet payload.
+
449 * This value cannot be changed after packet creation and determines how much memory is required for the packet.
+
450 * The packet can only contain payloads up to this value.
+
451 *
+
452 * @return
+
453 * Status | Description
+
454 * ---------------------------------------------- | ------------------------------------------------------------------
+
455 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
456 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
457 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Packet payload byte size to low/high.
+
458 * @ref BRAWCAP_STATUS_ERROR_FAILED | System error occurred (e.g. out of memory).
+
459 */
+
460_BRAWCAP_API_FUNC(brawcap_status_t)
+
461brawcap_packet_create(brawcap_packet_t** const pPacket, const brawcap_packet_size_t maxSize);
+
462
+
463/**
+
464 * @brief Frees the specified packet.
+
465 * When this function is called the specified packet becomes invalid and it´s memory is released.
+
466 *
+
467 * @warning Freeing a packet is not thread safe and the user is responsible for synchronization.
+
468 *
+
469 * @param[in] pPacket The packet to be freed.
+
470 *
+
471 * @return
+
472 * Status | Description
+
473 * ---------------------------------------------- | ------------------------------------------------------------------
+
474 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
475 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
476 */
+
477_BRAWCAP_API_FUNC(brawcap_status_t)
+
478brawcap_packet_free(brawcap_packet_t* pPacket);
+
479
+
480/**
+
481 * @brief Reads out the status for the specified packet.
+
482 * The status will be set updated during reception/transmission.
+
483 * It indicates the status of the packet depending on the operation.
+
484 *
+
485 * @param[in] pPacket The packet to read from.
+
486 *
+
487 * @param[out] pStatus Will contain the packet status, afterwards.
+
488 *
+
489 * @return
+
490 * Status | Description
+
491 * ---------------------------------------------- | ------------------------------------------------------------------
+
492 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
493 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
494 */
+
495_BRAWCAP_API_FUNC(brawcap_status_t)
+
496brawcap_packet_status_get(brawcap_packet_t* const pPacket, brawcap_status_t* const pStatus);
+
497
+
498/**
+
499 * @brief Reads out the @ref brawcap_timestamp "timestamp" object for the specified packet.
+
500 *
+
501 * @attention The timestamp is part of the packet itself.
+
502 * Therefore the returned timestamp is only valid as long as the packet itself is valid.
+
503 * The user application shall not store the timestamp object separately and only used it as long as the packet is valid.
+
504 *
+
505 * @param[in] pPacket The packet to read from.
+
506 *
+
507 * @param[out] pTimestamp Will contain the timestamp object of the packet, afterwards.
+
508 * This object can be used by the @ref brawcap_timestamp module.
+
509 *
+
510 * @return
+
511 * Status | Description
+
512 * ---------------------------------------------- | ------------------------------------------------------------------
+
513 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
514 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
515 */
+
516_BRAWCAP_API_FUNC(brawcap_status_t)
+
517brawcap_packet_timestamp_get(brawcap_packet_t* const pPacket, brawcap_timestamp_t** const pTimestamp);
+
518
+
519/**
+
520 * @brief Reads out the length on wire of the specified packet.
+
521 * This value is especially useful for received packets.
+
522 * It indicates the total packet payload byte size of the packet on wire.
+
523 * This may not equal to the @ref brawcap_packet_payload_size_get "captured payload byte size".
+
524 * Because the payload byte size depends on the configured filter and it´s
+
525 * @ref brawcap_filter_bytes_to_capture_set "bytes to capture" parameters.
+
526 *
+
527 * @param[in] pPacket The packet to read from.
+
528 *
+
529 * @param[out] pLengthOnWire Will contain the payload byte length on wire, afterwards.
+
530 *
+
531 * @return
+
532 * Status | Description
+
533 * ---------------------------------------------- | ------------------------------------------------------------------
+
534 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
535 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
536 */
+
537_BRAWCAP_API_FUNC(brawcap_status_t)
+
538brawcap_packet_length_on_wire_get(brawcap_packet_t* const pPacket, brawcap_packet_size_t* const pLengthOnWire);
+
539
+
540/**
+
541 * @brief Reads out the max supported payload byte size of the specified packet.
+
542 * This value was set during packet @ref brawcap_packet_create "creation"
+
543 * (or @ref brawcap_buffer_create "buffer creation" if it´s a buffered packet).
+
544 *
+
545 * @param[in] pPacket The packet to read from.
+
546 *
+
547 * @param[out] pMaxPayloadSize Will contain the max packet payload byte size, afterwards.
+
548 *
+
549 * @return
+
550 * Status | Description
+
551 * ---------------------------------------------- | ------------------------------------------------------------------
+
552 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
553 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
554 */
+
555_BRAWCAP_API_FUNC(brawcap_status_t)
+
556brawcap_packet_payload_max_size_get(brawcap_packet_t* const pPacket, brawcap_packet_size_t* const pMaxPayloadSize);
+
557
+
558/**
+
559 * @brief Reads out the captured payload byte size of the specified packet.
+
560 * This indicates the total byte size of the (captured - if received) packet payload
+
561 *
+
562 * @param[in] pPacket The packet to read from.
+
563 *
+
564 * @param[out] pLength Will contain the captured payload byte size, afterwards.
+
565 *
+
566 * @return
+
567 * Status | Description
+
568 * ---------------------------------------------- | ------------------------------------------------------------------
+
569 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
570 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
571 */
+
572_BRAWCAP_API_FUNC(brawcap_status_t)
+
573brawcap_packet_payload_size_get(brawcap_packet_t* const pPacket, brawcap_packet_size_t* const pLength);
+
574
+
575/**
+
576 * @brief Reads out the payload of the specified packet.
+
577 *
+
578 * The function returns a pointer to the beginning of the packet payload.
+
579 *
+
580 * @note The returned payload pointer should be only accessed as long as the packet is not freed.
+
581 * If post processing is required a copy of the required payload should be done.
+
582 *
+
583 * @attention Accessing the packet payload is not thread safe and user is responsible for synchronization.
+
584 *
+
585 * @param[in] pPacket The packet to read from.
+
586 *
+
587 * @param[out] pPayload Will contain a pointer to the beginning of the packet payload, afterwards.
+
588 *
+
589 * @param[out] pLength Will contain the total length of the packet payload, afterwards.
+
590 *
+
591 * @return
+
592 * Status | Description
+
593 * ---------------------------------------------- | ------------------------------------------------------------------
+
594 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
595 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
596 */
+
597_BRAWCAP_API_FUNC(brawcap_status_t)
+
598brawcap_packet_payload_get(brawcap_packet_t* const pPacket, const char** const pPayload,
+
599 brawcap_packet_size_t* const pLength);
+
600
+
601/**
+
602 * @brief Sets the packet payload of the specified packet.
+
603 *
+
604 * @note It is not allowed to set a larger payload than the max byte payload size
+
605 * (specified during @ref brawcap_packet_create "packet creation" or
+
606 * @ref brawcap_buffer_create "buffer creation").
+
607 * If a larger payload is specified the function will fail and return an error.
+
608 *
+
609 * @param[in] pPacket The packet to be modified.
+
610 *
+
611 * @param[in] pPayload Pointer to the beginning of the payload to set.
+
612 *
+
613 * @param[in] length Total byte size of the payload to set.
+
614 *
+
615 * @return
+
616 * Status | Description
+
617 * ---------------------------------------------- | ------------------------------------------------------------------
+
618 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
619 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
620 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The specified payload size exceeds the packet max payload size.
+
621 */
+
622_BRAWCAP_API_FUNC(brawcap_status_t)
+
623brawcap_packet_payload_set(brawcap_packet_t* const pPacket, const char* const pPayload,
+
624 const brawcap_packet_size_t length);
+
625
+
626/**@}*/
+
627#endif
+
628
+
629/************************************************* BUFFER ************************************************************/
+
630#if 1
+
631/**
+
632 * @addtogroup brawcap_buffer
+
633 * @{
+
634 */
+
635
+
636/**
+
637 * @brief Creates a new packet buffer.
+
638 *
+
639 * The created buffer can be used for:
+
640 * - Receiving by @ref brawcap_rx_buffer_attach "attaching" it.
+
641 * - Transmitting by @ref brawcap_tx_buffer_send "sending" it.
+
642 *
+
643 * If a buffer is not required anymore it shall be @ref brawcap_buffer_free "freed".
+
644 *
+
645 * @param[out] pBuffer Will contain the new created packet buffer, afterwards.
+
646 *
+
647 * @param[in] maxPacketPayloadSize Specifies the max payload byte size for each packet in the buffer.
+
648 * This cannot be changed after buffer creation and controls the memory size required for each packet in the buffer.
+
649 * When trying to set the packet payload of any buffered packet which exceeds this value, it will fail.
+
650 * The value has to be between @ref BRAWCAP_PACKET_SIZE_MIN and @ref BRAWCAP_PACKET_SIZE_MAX.
+
651 *
+
652 * @param[in] numPackets Specifies how many packets can be stored in the buffer.
+
653 * This value, together with the max packet payload size, will control the total amount of memory required for
+
654 * the packet buffer and cannot be changed after buffer creation.
+
655 * The value has to be between @ref BRAWCAP_BUFFER_PACKETS_MIN and @ref BRAWCAP_BUFFER_PACKETS_MAX.
+
656 *
+
657 * @return
+
658 * Status | Description
+
659 * ---------------------------------------------- | ------------------------------------------------------------------
+
660 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
661 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
662 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The specified packet payload or number of packets is invalid.
+
663 * @ref BRAWCAP_STATUS_ERROR_FAILED | System error occurred (e.g. out of memory).
+
664 */
+
665_BRAWCAP_API_FUNC(brawcap_status_t)
+
666brawcap_buffer_create(brawcap_buffer_t** const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize,
+
667 const brawcap_buffer_packet_count_t numPackets);
+
668
+
669/**
+
670 * @brief Frees the specified packet buffer.
+
671 * When this function is called the specified packet buffer becomes invalid and it´s memory will be released.
+
672 *
+
673 * @warning Freeing a buffer is not thread safe and the user is responsible for synchronization.
+
674 *
+
675 * @param[in] pBuffer The packet buffer to be freed.
+
676 *
+
677 * @return
+
678 * Status | Description
+
679 * ---------------------------------------------- | ------------------------------------------------------------------
+
680 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
681 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
682 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
683 */
+
684_BRAWCAP_API_FUNC(brawcap_status_t)
+
685brawcap_buffer_free(brawcap_buffer_t* pBuffer);
+
686
+
687/**
+
688 * @brief Clears the specified packet buffer.
+
689 *
+
690 * All buffered packets will be cleared.
+
691 * It may be used to reuse a already created packet buffer.
+
692 * For example this can be useful after transmission of the packet buffer has finished.
+
693 * Reusing a buffer improves performance and should be preferred instead of always creating and freeing packet
+
694 * buffers.
+
695 *
+
696 * @warning After calling this function all buffered packets in the packet buffer become invalid and shall not be used
+
697 * anymore.
+
698 *
+
699 * @param[in] pBuffer The packet buffer to be cleared.
+
700 *
+
701 * @return
+
702 * Status | Description
+
703 * ---------------------------------------------- | ------------------------------------------------------------------
+
704 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
705 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
706 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
707 */
+
708_BRAWCAP_API_FUNC(brawcap_status_t)
+
709brawcap_buffer_clear(brawcap_buffer_t* const pBuffer);
+
710
+
711/**
+
712 * @brief Adds the specified packet at the end of the specified packet buffer.
+
713 *
+
714 * @param[in] pBuffer The packet buffer to be modified.
+
715 *
+
716 * @param[in] pPacket The packet to insert into the buffer.
+
717 *
+
718 * @return
+
719 * Status | Description
+
720 * ---------------------------------------------- | ------------------------------------------------------------------
+
721 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
722 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
723 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
724 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | The max number of packets for the buffer is reached.
+
725 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The packet payload length is to long for the buffer.
+
726 */
+
727_BRAWCAP_API_FUNC(brawcap_status_t)
+
728brawcap_buffer_add_back(brawcap_buffer_t* const pBuffer, const brawcap_packet_t* const pPacket);
+
729
+
730/**
+
731 * @brief Adds the specified packet at the front of the specified packet buffer.
+
732 *
+
733 * @param[in] pBuffer The packet buffer to be modified.
+
734 *
+
735 * @param[in] pPacket The packet to insert into the buffer.
+
736 *
+
737 * @return
+
738 * Status | Description
+
739 * ---------------------------------------------- | ------------------------------------------------------------------
+
740 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
741 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
742 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
743 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | The max number of packets for the buffer is reached.
+
744 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The packet payload length is to long for the buffer.
+
745 */
+
746_BRAWCAP_API_FUNC(brawcap_status_t)
+
747brawcap_buffer_add_front(brawcap_buffer_t* const pBuffer, const brawcap_packet_t* const pPacket);
+
748
+
749/**
+
750 * @brief Inserts the specified packet at index/position into the specified packet buffer.
+
751 *
+
752 * @param[in] pBuffer The packet buffer to be modified.
+
753 *
+
754 * @param[in] pPacket The packet to insert into the buffer.
+
755 *
+
756 * @param[in] index Index at which the packet should be inserted.
+
757 *
+
758 * @return
+
759 * Status | Description
+
760 * ---------------------------------------------- | ------------------------------------------------------------------
+
761 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
762 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
763 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
764 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | The max number of packets for the buffer is reached.
+
765 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The packet payload length is to long for the buffer.
+
766 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The given index is invalid (exceeds buffer).
+
767 */
+
768_BRAWCAP_API_FUNC(brawcap_status_t)
+
769brawcap_buffer_add_at_index(brawcap_buffer_t* const pBuffer, const brawcap_packet_t* const pPacket,
+
770 const brawcap_buffer_packet_count_t index);
+
771
+
772/**
+
773 * @brief Reads out a buffered packet at the index of the specified packet buffer.
+
774 *
+
775 * @param[in] pBuffer The packet buffer to read from.
+
776 *
+
777 * @param[in] index The index of the packet.
+
778 *
+
779 * @param[out] pPacket Will contain the buffered packet, afterwards.
+
780 *
+
781 * @return
+
782 * Status | Description
+
783 * ---------------------------------------------- | ------------------------------------------------------------------
+
784 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
785 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
786 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
787 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The given index is invalid (exceeds buffer).
+
788 */
+
789_BRAWCAP_API_FUNC(brawcap_status_t)
+
790brawcap_buffer_at_index(brawcap_buffer_t* const pBuffer, const brawcap_buffer_packet_count_t index,
+
791 brawcap_packet_t** const pPacket);
+
792
+
793/**
+
794 * @brief Reads out the first buffered packet of the specified packet buffer.
+
795 *
+
796 * @param[in] pBuffer The packet buffer to read from.
+
797 *
+
798 * @param[out] pPacket Will contain the buffered packet, afterwards.
+
799 *
+
800 * @return
+
801 * Status | Description
+
802 * ---------------------------------------------- | ------------------------------------------------------------------
+
803 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
804 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
805 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
806 */
+
807_BRAWCAP_API_FUNC(brawcap_status_t)
+
808brawcap_buffer_front(brawcap_buffer_t* const pBuffer, brawcap_packet_t** const pPacket);
+
809
+
810/**
+
811 * @brief Reads out the last buffered packet of the specified packet buffer.
+
812 *
+
813 * @param[in] pBuffer The packet buffer to read from.
+
814 *
+
815 * @param[out] pPacket Will contain the buffered packet, afterwards.
+
816 *
+
817 * @return
+
818 * Status | Description
+
819 * ---------------------------------------------- | ------------------------------------------------------------------
+
820 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
821 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
822 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
823 */
+
824_BRAWCAP_API_FUNC(brawcap_status_t)
+
825brawcap_buffer_back(brawcap_buffer_t* const pBuffer, brawcap_packet_t** const pPacket);
+
826
+
827/**
+
828 * @brief Reads out the number of currently buffered packets in the specified packet buffer.
+
829 *
+
830 * @param[in] pBuffer The packet buffer to read from.
+
831 *
+
832 * @param[out] pPacketCount Will contain the number of buffered packets, afterwards.
+
833 *
+
834 * @return
+
835 * Status | Description
+
836 * ---------------------------------------------- | ------------------------------------------------------------------
+
837 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
838 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
839 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
840 */
+
841_BRAWCAP_API_FUNC(brawcap_status_t)
+
842brawcap_buffer_count(brawcap_buffer_t* const pBuffer, brawcap_buffer_packet_count_t* const pPacketCount);
+
843
+
844/**
+
845 * @brief Reads out the total number of packets which can be buffered by the specified packet buffer.
+
846 * This value represents the packet buffer capacity, which is set during buffer creation.
+
847 *
+
848 * @param[in] pBuffer The packet buffer to read from.
+
849 *
+
850 * @param[out] pPacketCapacity Will contain the total number of packets which can be buffered, afterwards.
+
851 *
+
852 * @return
+
853 * Status | Description
+
854 * ---------------------------------------------- | ------------------------------------------------------------------
+
855 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
856 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
857 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
858 */
+
859_BRAWCAP_API_FUNC(brawcap_status_t)
+
860brawcap_buffer_capacity(brawcap_buffer_t* const pBuffer, brawcap_buffer_packet_count_t* const pPacketCapacity);
+
861
+
862/********************************************* BUFFER ITERATOR ********************************************************/
+
863#if 1
+
864/**
+
865 * @addtogroup brawcap_buffer_iterator
+
866 * @{
+
867 */
+
868
+
869/**
+
870 * @brief Creates a new iterator for the specified buffer.
+
871 *
+
872 * If a iterator is not required anymore it shall be @ref brawcap_buffer_iterator_free "freed".
+
873 *
+
874 * @param[out] pIterator Will contain the new created iterator.
+
875 *
+
876 * @param[in] pBuffer The buffer for which to create the iterator.
+
877 *
+
878 * @param[in] startPosition The start position of the iterator (packet buffer index/position).
+
879 * The specified position must be below the number of currently buffered packets,
+
880 * which can be resolved with @ref brawcap_buffer_count.
+
881 *
+
882 * @return
+
883 * Status | Description
+
884 * ---------------------------------------------- | ------------------------------------------------------------------
+
885 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
886 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
887 * @ref BRAWCAP_STATUS_ERROR_IN_USE | Buffer is still in use/pending (receive/transmit).
+
888 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | Start position exceeds number of buffered packets.
+
889 * @ref BRAWCAP_STATUS_ERROR_FAILED | System error occurred (e.g. out of memory).
+
890 */
+
891_BRAWCAP_API_FUNC(brawcap_status_t)
+
892brawcap_buffer_iterator_create(brawcap_buffer_iterator_t** const pIterator, brawcap_buffer_t* const pBuffer,
+
893 brawcap_buffer_packet_count_t startPosition);
+
894
+
895/**
+
896 * @brief Frees the specified iterator.
+
897 * When this function is called the specified iterator becomes invalid and it´s memory will be released.
+
898 *
+
899 * @warning Freeing a iterator is not thread safe and the user is responsible for synchronization.
+
900 *
+
901 * @param[in] pIterator The iterator to be freed.
+
902 *
+
903 * @return
+
904 * Status | Description
+
905 * ---------------------------------------------- | ------------------------------------------------------------------
+
906 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
907 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
908 */
+
909_BRAWCAP_API_FUNC(brawcap_status_t)
+
910brawcap_buffer_iterator_free(brawcap_buffer_iterator_t* const pIterator);
+
911
+
912/**
+
913 * @brief Increments the iterator to the next buffered packet.
+
914 *
+
915 * @param[in] pIterator The iterator to be incremented.
+
916 *
+
917 * @return
+
918 * Status | Description
+
919 * ---------------------------------------------- | ------------------------------------------------------------------
+
920 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
921 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
922 */
+
923_BRAWCAP_API_FUNC(brawcap_status_t)
+
924brawcap_buffer_iterator_next(brawcap_buffer_iterator_t* const pIterator);
+
925
+
926/**
+
927 * @brief Decreases the iterator to the previous buffered packet.
+
928 *
+
929 * @param[in] pIterator The iterator to be decremented.
+
930 *
+
931 * @return
+
932 * Status | Description
+
933 * ---------------------------------------------- | ------------------------------------------------------------------
+
934 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
935 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
936 */
+
937_BRAWCAP_API_FUNC(brawcap_status_t)
+
938brawcap_buffer_iterator_prev(brawcap_buffer_iterator_t* const pIterator);
+
939
+
940/**
+
941 * @brief Returns the buffered packet for the specified iterator.
+
942 *
+
943 * @param[in] pIterator The iterator to read from.
+
944 *
+
945 * @return
+
946 * Pointer | Description
+
947 * ---------------------------------------------- | ------------------------------------------------------------------
+
948 * @ref brawcap_packet_t | On success a valid bRAWcap packet object pointer.
+
949 * NULL | Invalid iterator (e.g. beyond the last or first packet).
+
950 */
+
951_BRAWCAP_API_FUNC(brawcap_packet_t*)
+
952brawcap_buffer_iterator_eval(brawcap_buffer_iterator_t* const pIterator);
+
953
+
954/**@}*/
+
955#endif
+
956
+
957/**@}*/
+
958#endif
+
959
+
960/************************************************ ADAPTER ************************************************************/
+
961#if 1
+
962/**
+
963 * @addtogroup brawcap_adapter
+
964 * @{
+
965 */
+
966
+
967/**
+
968 * @brief Updates the list of supported adapters.
+
969 * This function searches the current machine for supported adapters and add them to the adapter list.
+
970 *
+
971 * @note The list will be initialized when calling the first bRAWcap function and not update automatically after that.
+
972 * To update the list later on use this function.
+
973 * A alternative to detect new/removed adapters is
+
974 * @ref brawcap_adapter_notify_register "registering for change notifications".
+
975 *
+
976 * @attention The adapter list is not thread safe.
+
977 * Therefore parallel calls to this function, @ref brawcap_adapter_list_count and @ref brawcap_adapter_list_at
+
978 * should be avoided or at least synchronized.
+
979 * If the list is changed by this function and another thread is currently retrieving information from the list
+
980 * it may lead to undefined behavior or even a crash if the number of entries is reduced.
+
981 *
+
982 * @return
+
983 * Status | Description
+
984 * ---------------------------------------------- | ------------------------------------------------------------------
+
985 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
986 */
+
987_BRAWCAP_API_FUNC(brawcap_status_t)
+
988brawcap_adapter_list_update();
+
989
+
990/**
+
991 * @brief Reads out the current number of supported adapters in the adapter list.
+
992 *
+
993 * @note The count is only updated after a call to @ref brawcap_adapter_list_update.
+
994 *
+
995 * @attention Updating the list and retrieving information from it is not thread safe.
+
996 * Therefore accessing it from different threads shall be avoided or synchronized.
+
997 *
+
998 * @param[out] pCount Will contain the current number of adapters in the list, afterwards.
+
999 *
+
1000 * @return
+
1001 * Status | Description
+
1002 * ---------------------------------------------- | ------------------------------------------------------------------
+
1003 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1004 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1005 */
+
1006_BRAWCAP_API_FUNC(brawcap_status_t)
+
1007brawcap_adapter_list_count(brawcap_adapter_count_t* const pCount);
+
1008
+
1009/**
+
1010 * @brief Reads out the adapter name of the adapter at the adapter list index.
+
1011 *
+
1012 * @note The adapter list is only updated after a call to @ref brawcap_adapter_list_update.
+
1013 *
+
1014 * @attention Updating the list and retrieving information from it is not thread safe.
+
1015 * Therefore accessing it from different threads shall be avoided or synchronized.
+
1016 *
+
1017 * @param[in] index The index of the adapter in the adapter list..
+
1018 *
+
1019 * @param[out] name Will contain the name of the adapter, afterwards.
+
1020 *
+
1021 * @return
+
1022 * Status | Description
+
1023 * ---------------------------------------------- | ------------------------------------------------------------------
+
1024 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1025 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1026 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Specified index exceeds adapter list length.
+
1027 */
+
1028_BRAWCAP_API_FUNC(brawcap_status_t)
+
1029brawcap_adapter_list_at(const brawcap_adapter_count_t index, brawcap_adapter_name_t name);
+
1030
+
1031/**
+
1032 * @brief Registers the calling process for receiving adapter change notifications.
+
1033 *
+
1034 * The given callback function will be called each time a adapter change is recognized by bRAWcap for any of the
+
1035 * supported adapters on the current machine.
+
1036 *
+
1037 * @attention Blocking for long periods within the callback function can lead to incorrect behavior
+
1038 * and should be avoided.
+
1039 * If you need to process a lot on adapter changes it is recommended to do the processing in
+
1040 * another thread rather than directly within the callback.
+
1041 *
+
1042 * @note Calls to the registered callback function are serialized.
+
1043 * This means that the callback can not be called in parallel and
+
1044 * one call has to be finished before another one is received.
+
1045 *
+
1046 * @note Each process can only register for notifications once.
+
1047 *
+
1048 * @param[in] callback Function pointer to the callback function which should be executed each time
+
1049 * a adapter change is registered.
+
1050 *
+
1051 * @param[in] pUser Pointer to a user defined context.
+
1052 * This allows access to user specific data within the callback.
+
1053 *
+
1054 * @return
+
1055 * Status | Description
+
1056 * ---------------------------------------------- | ------------------------------------------------------------------
+
1057 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1058 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1059 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1060 * @ref BRAWCAP_STATUS_INFO_ALREADY_REGISTERED | Calling process has already registered for this notification.
+
1061 */
+
1062_BRAWCAP_API_FUNC(brawcap_status_t)
+
1063brawcap_adapter_notify_register(brawcap_adapter_notify_callback_t const callback, void* const pUser);
+
1064
+
1065/**
+
1066 * @brief Unregisters the calling process from receiving adapter change notifications.
+
1067 *
+
1068 * @return
+
1069 * Status | Description
+
1070 * ---------------------------------------------- | ------------------------------------------------------------------
+
1071 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1072 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1073 * @ref BRAWCAP_STATUS_INFO_NOT_REGISTERED | Calling process was not registered for this notification.
+
1074 */
+
1075_BRAWCAP_API_FUNC(brawcap_status_t)
+
1076brawcap_adapter_notify_unregister();
+
1077
+
1078/**
+
1079 * @brief Registers the specified handle for receiving adapter change notifications.
+
1080 *
+
1081 * This registration only receives adapter change notifications related to the underlying adapter of the given
+
1082 * bRAWcap handle.
+
1083 * Whereas @ref brawcap_adapter_notify_register notifies about adapter changes for all supported adapters on the
+
1084 * current machine.
+
1085 *
+
1086 * Each bRAWcap handle can register for this notification once.
+
1087 *
+
1088 * @attention Blocking for long periods within the callback function can lead to incorrect behavior
+
1089 * and should be avoided. If you need to process a lot on adapter changes it is recommended to do the processing in
+
1090 * another thread rather than directly within the callback.
+
1091 *
+
1092 * @note Calls to the registered callback function are serialized.
+
1093 * This means that the callback can not be called in parallel and
+
1094 * one call has to be finished before another one is received.
+
1095 *
+
1096 * @param[in] pHandle Handle to register for adapter notifications.
+
1097 *
+
1098 * @param[in] pUser Pointer to a user defined context.
+
1099 * This allows access to user specific data within the callback.
+
1100 *
+
1101 * @param[in] callback Function pointer to the callback function which should be executed each time
+
1102 * a adapter change is registered.
+
1103 *
+
1104 * @return
+
1105 * Status | Description
+
1106 * ---------------------------------------------- | ------------------------------------------------------------------
+
1107 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1108 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1109 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1110 * @ref BRAWCAP_STATUS_INFO_ALREADY_REGISTERED | Specified handle has already registered for this notification.
+
1111 */
+
1112_BRAWCAP_API_FUNC(brawcap_status_t)
+
1113brawcap_adapter_notify_handle_register(brawcap_handle_t* const pHandle,
+
1114 brawcap_adapter_notify_handle_callback_t const callback, void* const pUser);
+
1115
+
1116/**
+
1117 * @brief Unregisters the specified handle from receiving adapter change notifications.
+
1118 *
+
1119 * @param[in] pHandle Handle to unregister for adapter notifications.
+
1120 *
+
1121 * @return
+
1122 * Status | Description
+
1123 * ---------------------------------------------- | ------------------------------------------------------------------
+
1124 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1125 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1126 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1127 * @ref BRAWCAP_STATUS_INFO_NOT_REGISTERED | Specified handle was not registered for this notification.
+
1128 */
+
1129_BRAWCAP_API_FUNC(brawcap_status_t)
+
1130brawcap_adapter_notify_handle_unregister(brawcap_handle_t* const pHandle);
+
1131
+
1132/**
+
1133 * @brief Reads out the adapter name of the specified adapter.
+
1134 *
+
1135 * @param[in] pHandle The bRAWcap handle to read from.
+
1136 *
+
1137 * @param[out] name Will contain the adapter name, afterwards.
+
1138 *
+
1139 * @return
+
1140 * Status | Description
+
1141 * ---------------------------------------------- | ------------------------------------------------------------------
+
1142 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1143 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1144 */
+
1145_BRAWCAP_API_FUNC(brawcap_status_t)
+
1146brawcap_adapter_name_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_name_t name);
+
1147
+
1148/**
+
1149 * @brief Reads out the currently set adapter friendly name for the specified adapter.
+
1150 *
+
1151 * @param[in] name Name of the adapter.
+
1152 *
+
1153 * @param[out] friendlyName Pointer to a buffer which will contain the currently set adapter friendly name, afterwards.
+
1154 * This parameter can be NULL.
+
1155 * If it is NULL the function will set the required buffer length in pLength and
+
1156 * return @ref BRAWCAP_STATUS_ERROR_OVERRUN.
+
1157 *
+
1158 * @param[inout] pLength Length of the provided buffer.
+
1159 * If the specified length is to short,
+
1160 * it will be set to the required length and @ref BRAWCAP_STATUS_ERROR_OVERRUN is returned.
+
1161 *
+
1162 * @return
+
1163 * Status | Description
+
1164 * ---------------------------------------------- | ------------------------------------------------------------------
+
1165 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1166 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1167 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1168 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1169 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | Given buffer length was to short.
+
1170 */
+
1171_BRAWCAP_API_FUNC(brawcap_status_t)
+
1172brawcap_adapter_friendly_name(const brawcap_adapter_name_t name, char* const friendlyName, UINT32* const pLength);
+
1173
+
1174/**
+
1175 * @brief Reads out the currently set friendly name of the specified adapter.
+
1176 *
+
1177 * @param[in] pHandle The bRAWcap handle to read from.
+
1178 *
+
1179 * @param[out] friendlyName Pointer to a buffer which will contain the currently set friendly name, afterwards.
+
1180 * This parameter can be NULL.
+
1181 * If it is NULL the function will set the required buffer length in pLength and
+
1182 * return @ref BRAWCAP_STATUS_ERROR_OVERRUN.
+
1183 *
+
1184 * @param[inout] pLength Length of the provided buffer.
+
1185 * If the specified length is to short,
+
1186 * it will be set to the required length and @ref BRAWCAP_STATUS_ERROR_OVERRUN is returned.
+
1187 *
+
1188 * @return
+
1189 * Status | Description
+
1190 * ---------------------------------------------- | -----------------------------------------------------------
+
1191 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1192 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1193 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1194 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | Given buffer length was to short.
+
1195 */
+
1196_BRAWCAP_API_FUNC(brawcap_status_t)
+
1197brawcap_adapter_friendly_name_by_handle(brawcap_handle_t* const pHandle, char* const friendlyName,
+
1198 UINT32* const pLength);
+
1199
+
1200/**
+
1201 * @brief Reads out the description of the specified adapter.
+
1202 *
+
1203 * @note Adapter descriptions are set depending on the loaded network adapter driver.
+
1204 * This means it will not change as long as the network driver is not changed.
+
1205 *
+
1206 * @param[in] name Name of the adapter.
+
1207 *
+
1208 * @param[out] description Pointer to a buffer which will contain the description, afterwards.
+
1209 * This parameter can be NULL.
+
1210 * If it is NULL the function will set the required buffer length in pLength and
+
1211 * return @ref BRAWCAP_STATUS_ERROR_OVERRUN.
+
1212 *
+
1213 * @param[inout] pLength Length of the provided buffer.
+
1214 * If the specified length is to short,
+
1215 * it will be set to the required length and @ref BRAWCAP_STATUS_ERROR_OVERRUN is returned.
+
1216 *
+
1217 * @return
+
1218 * Status | Description
+
1219 * ---------------------------------------------- | -----------------------------------------------------------
+
1220 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1221 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1222 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1223 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1224 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | Given buffer length was to short.
+
1225 */
+
1226_BRAWCAP_API_FUNC(brawcap_status_t)
+
1227brawcap_adapter_description(const brawcap_adapter_name_t name, char* const description, UINT32* const pLength);
+
1228
+
1229/**
+
1230 * @brief Reads out the description of a network adapter based on the specified adapter.
+
1231 *
+
1232 * @note Adapter descriptions are set depending on the loaded network adapter driver.
+
1233 * This means it will not change as long as the network driver is not changed.
+
1234 *
+
1235 * @param[in] pHandle The bRAWcap handle to read from.
+
1236 *
+
1237 * @param[out] description Pointer to a buffer which will contain the description, afterwards.
+
1238 * This parameter can be NULL.
+
1239 * If it is NULL the required buffer length will be set for pLength and the
+
1240 * function will return @ref BRAWCAP_STATUS_ERROR_OVERRUN.
+
1241 *
+
1242 * @param[inout] pLength Length of the provided buffer.
+
1243 * If the specified length is to short,
+
1244 * it will be set to the required length and @ref BRAWCAP_STATUS_ERROR_OVERRUN is returned.
+
1245 *
+
1246 * @return
+
1247 * Status | Description
+
1248 * ---------------------------------------------- | -----------------------------------------------------------
+
1249 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1250 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1251 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1252 * @ref BRAWCAP_STATUS_ERROR_OVERRUN | Given buffer length was to short.
+
1253 */
+
1254_BRAWCAP_API_FUNC(brawcap_status_t)
+
1255brawcap_adapter_description_by_handle(brawcap_handle_t* const pHandle, char* const description, UINT32* const pLength);
+
1256
+
1257/**
+
1258 * @brief Reads out the currently set IPv4 address of the specified adapter.
+
1259 *
+
1260 * @param[in] name Name of the adapter.
+
1261 *
+
1262 * @param[out] pIpv4 Will contain the currently set IPv4 address, afterwards.
+
1263 *
+
1264 * @return
+
1265 * Status | Description
+
1266 * ---------------------------------------------- | -----------------------------------------------------------
+
1267 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1268 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1269 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1270 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1271 */
+
1272_BRAWCAP_API_FUNC(brawcap_status_t)
+
1273brawcap_adapter_ipv4(const brawcap_adapter_name_t name, brawcap_adapter_ipv4_t* const pIpv4);
+
1274
+
1275/**
+
1276 * @brief Reads out the currently set IPv4 address of the specified adapter.
+
1277 *
+
1278 * @param[in] pHandle The bRAWcap handle to read from.
+
1279 *
+
1280 * @param[out] pIpv4 Will contain the currently set IPv4 address, afterwards.
+
1281 *
+
1282 * @return
+
1283 * Status | Description
+
1284 * ---------------------------------------------- | -----------------------------------------------------------
+
1285 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1286 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1287 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1288 */
+
1289_BRAWCAP_API_FUNC(brawcap_status_t)
+
1290brawcap_adapter_ipv4_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_ipv4_t* const pIpv4);
+
1291
+
1292/**
+
1293 * @brief Reads out the currently set IPv6 address of the specified adapter.
+
1294 *
+
1295 * @param[in] name Name of the adapter.
+
1296 *
+
1297 * @param[out] pIpv6 Will contain the currently set IPv6 address, afterwards.
+
1298 *
+
1299 * @return
+
1300 * Status | Description
+
1301 * ---------------------------------------------- | -----------------------------------------------------------
+
1302 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1303 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1304 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1305 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1306 */
+
1307_BRAWCAP_API_FUNC(brawcap_status_t)
+
1308brawcap_adapter_ipv6(const brawcap_adapter_name_t name, brawcap_adapter_ipv6_t* const pIpv6);
+
1309
+
1310/**
+
1311 * @brief Reads out the currently set IPv6 address of the specified adapter.
+
1312 *
+
1313 * @param[in] pHandle The bRAWcap handle to read from.
+
1314 *
+
1315 * @param[out] pIpv6 Will contain the currently set IPv6 address, afterwards.
+
1316 *
+
1317 * @return
+
1318 * Status | Description
+
1319 * ---------------------------------------------- | -----------------------------------------------------------
+
1320 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1321 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1322 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1323 */
+
1324_BRAWCAP_API_FUNC(brawcap_status_t)
+
1325brawcap_adapter_ipv6_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_ipv6_t* const pIpv6);
+
1326
+
1327/**
+
1328 * @brief Reads out the MAC address of the specified adapter.
+
1329 *
+
1330 * @param[in] name Name of the adapter.
+
1331 *
+
1332 * @param[out] mac Will contain the MAC address, afterwards.
+
1333 *
+
1334 * @return
+
1335 * Status | Description
+
1336 * ---------------------------------------------- | -----------------------------------------------------------
+
1337 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1338 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1339 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1340 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1341 */
+
1342_BRAWCAP_API_FUNC(brawcap_status_t)
+
1343brawcap_adapter_mac(const brawcap_adapter_name_t name, brawcap_adapter_mac_t mac);
+
1344
+
1345/**
+
1346 * @brief Reads out the MAC address of the specified adapter.
+
1347 *
+
1348 * @param[in] pHandle The bRAWcap handle to read from.
+
1349 *
+
1350 * @param[out] mac Will contain the MAC address, afterwards.
+
1351 *
+
1352 * @return
+
1353 * Status | Description
+
1354 * ---------------------------------------------- | -----------------------------------------------------------
+
1355 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1356 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1357 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1358 */
+
1359_BRAWCAP_API_FUNC(brawcap_status_t)
+
1360brawcap_adapter_mac_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_mac_t mac);
+
1361
+
1362/**
+
1363 * @brief Reads out the current receive speed of the specified adapter.
+
1364 *
+
1365 * @param[in] name Name of the adapter.
+
1366 *
+
1367 * @param[out] pSpeed Will contain the current receive speed, afterwards.
+
1368 *
+
1369 * @return
+
1370 * Status | Description
+
1371 * ---------------------------------------------- | -----------------------------------------------------------
+
1372 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1373 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1374 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1375 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1376 */
+
1377_BRAWCAP_API_FUNC(brawcap_status_t)
+
1378brawcap_adapter_speed_rx(const brawcap_adapter_name_t name, brawcap_adapter_speed_t* const pSpeed);
+
1379
+
1380/**
+
1381 * @brief Reads out the current receive speed of the specified adapter.
+
1382 *
+
1383 * @param[in] pHandle The bRAWcap handle to read from.
+
1384 *
+
1385 * @param[out] pSpeed Will contain the current receive speed, afterwards.
+
1386 *
+
1387 * @return
+
1388 * Status | Description
+
1389 * ---------------------------------------------- | -----------------------------------------------------------
+
1390 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1391 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1392 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1393 */
+
1394_BRAWCAP_API_FUNC(brawcap_status_t)
+
1395brawcap_adapter_speed_rx_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_speed_t* const pSpeed);
+
1396
+
1397/**
+
1398 * @brief Reads out the current transmit speed of the specified adapter.
+
1399 *
+
1400 * @param[in] name Name of the adapter.
+
1401 *
+
1402 * @param[out] pSpeed Will contain the current transmit speed, afterwards.
+
1403 *
+
1404 * @return
+
1405 * Status | Description
+
1406 * ---------------------------------------------- | -----------------------------------------------------------
+
1407 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1408 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1409 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1410 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1411 */
+
1412_BRAWCAP_API_FUNC(brawcap_status_t)
+
1413brawcap_adapter_speed_tx(const brawcap_adapter_name_t name, brawcap_adapter_speed_t* const pSpeed);
+
1414
+
1415/**
+
1416 * @brief Reads out the current transmit speed of the specified adapter.
+
1417 *
+
1418 * @param[in] pHandle The bRAWcap handle to read from.
+
1419 *
+
1420 * @param[out] pSpeed Will contain the current transmit speed, afterwards.
+
1421 *
+
1422 * @return
+
1423 * Status | Description
+
1424 * ---------------------------------------------- | -----------------------------------------------------------
+
1425 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1426 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1427 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1428 */
+
1429_BRAWCAP_API_FUNC(brawcap_status_t)
+
1430brawcap_adapter_speed_tx_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_speed_t* const pSpeed);
+
1431
+
1432/**
+
1433 * @brief Reads out the current connection state of the specified adapter.
+
1434 *
+
1435 * @param[in] name Name of the adapter.
+
1436 *
+
1437 * @param[out] pConnection Will contain the current connection state, afterwards.
+
1438 *
+
1439 * @return
+
1440 * Status | Description
+
1441 * ---------------------------------------------- | -----------------------------------------------------------
+
1442 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1443 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1444 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1445 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1446 */
+
1447_BRAWCAP_API_FUNC(brawcap_status_t)
+
1448brawcap_adapter_connection(const brawcap_adapter_name_t name, brawcap_adapter_connection_state_t* const pConnection);
+
1449
+
1450/**
+
1451 * @brief Reads out the current connection state of the specified adapter.
+
1452 *
+
1453 * @param[in] pHandle The bRAWcap handle to read from.
+
1454 *
+
1455 * @param[out] pConnection Will contain the current connection state, afterwards.
+
1456 *
+
1457 * @return
+
1458 * Status | Description
+
1459 * ---------------------------------------------- | -----------------------------------------------------------
+
1460 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1461 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1462 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1463 */
+
1464_BRAWCAP_API_FUNC(brawcap_status_t)
+
1465brawcap_adapter_connection_by_handle(brawcap_handle_t* const pHandle,
+
1466 brawcap_adapter_connection_state_t* const pConnection);
+
1467
+
1468/**
+
1469 * @brief Reads out the current operation state of the specified adapter.
+
1470 *
+
1471 * @param[in] name Name of the adapter.
+
1472 *
+
1473 * @param[out] pOperation Will contain the current operation state, afterwards.
+
1474 *
+
1475 * @return
+
1476 * Status | Description
+
1477 * ---------------------------------------------- | -----------------------------------------------------------
+
1478 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1479 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1480 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1481 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1482 */
+
1483_BRAWCAP_API_FUNC(brawcap_status_t)
+
1484brawcap_adapter_operation(const brawcap_adapter_name_t name, brawcap_adapter_operation_state_t* const pOperation);
+
1485
+
1486/**
+
1487 * @brief Reads out the current operation state of the specified adapter.
+
1488 *
+
1489 * @param[in] pHandle The bRAWcap handle to read from.
+
1490 *
+
1491 * @param[out] pOperation Will contain the current operation state, afterwards.
+
1492 *
+
1493 * @return
+
1494 * Status | Description
+
1495 * ---------------------------------------------- | -----------------------------------------------------------
+
1496 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1497 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1498 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1499 */
+
1500_BRAWCAP_API_FUNC(brawcap_status_t)
+
1501brawcap_adapter_operation_by_handle(brawcap_handle_t* const pHandle,
+
1502 brawcap_adapter_operation_state_t* const pOperation);
+
1503
+
1504/**
+
1505 * @brief Reads out the configured MTU of the specified adapter.
+
1506 *
+
1507 * @param[in] name Name of the adapter.
+
1508 *
+
1509 * @param[out] pMtu Will contain the configured MTU, afterwards.
+
1510 *
+
1511 * @return
+
1512 * Status | Description
+
1513 * ---------------------------------------------- | -----------------------------------------------------------
+
1514 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1515 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1516 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1517 * @ref BRAWCAP_STATUS_ERROR_NOT_FOUND | Adapter name not found/not available.
+
1518 */
+
1519_BRAWCAP_API_FUNC(brawcap_status_t)
+
1520brawcap_adapter_mtu(const brawcap_adapter_name_t name, brawcap_adapter_mtu_t* const pMtu);
+
1521
+
1522/**
+
1523 * @brief Reads out the configured MTU of the specified adapter.
+
1524 *
+
1525 * @param[in] pHandle The bRAWcap handle to read from.
+
1526 *
+
1527 * @param[out] pMtu Will contain the configured MTU, afterwards.
+
1528 *
+
1529 * @return
+
1530 * Status | Description
+
1531 * ---------------------------------------------- | -----------------------------------------------------------
+
1532 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1533 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1534 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Not available in demo mode (no license).
+
1535 */
+
1536_BRAWCAP_API_FUNC(brawcap_status_t)
+
1537brawcap_adapter_mtu_by_handle(brawcap_handle_t* const pHandle, brawcap_adapter_mtu_t* const pMtu);
+
1538
+
1539/**@}*/
+
1540#endif
+
1541
+
1542/************************************************ RECEIVE ************************************************************/
+
1543#if 1
+
1544/**
+
1545 * @addtogroup brawcap_receive
+
1546 * @{
+
1547 */
+
1548
+
1549/********************************************** RECEIVE FILTER *******************************************************/
+
1550#if 1
+
1551/**
+
1552 * @addtogroup brawcap_filter
+
1553 * @{
+
1554 */
+
1555
+
1556/**
+
1557 * @brief Creates a new filter.
+
1558 *
+
1559 * The created filter can be used for filtering received packets by applying it to a bRAWcap handle with
+
1560 * @ref brawcap_rx_filter_set.
+
1561 *
+
1562 * If a created filter is not required anymore it should be freed with @ref brawcap_filter_free.
+
1563 *
+
1564 * @note Currently only the @ref BRAWCAP_FILTER_TYPE_BYTE_MASK filter type is supported.
+
1565 * Support for @ref BRAWCAP_FILTER_TYPE_BPF may be added later on.
+
1566 *
+
1567 * @param[in] pFilter Will contain the new created filter.
+
1568 *
+
1569 * @param[in] type Specifies the type of the created filter.
+
1570 *
+
1571 * @return
+
1572 * Status | Description
+
1573 * ---------------------------------------------- | ------------------------------------------------------------------
+
1574 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1575 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1576 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Specified filter type is not supported.
+
1577 * @ref BRAWCAP_STATUS_ERROR_FAILED | System error occurred (e.g. out of memory).
+
1578 */
+
1579_BRAWCAP_API_FUNC(brawcap_status_t)
+
1580brawcap_filter_create(brawcap_filter_t** const pFilter, const brawcap_filter_type_t type);
+
1581
+
1582/**
+
1583 * @brief Frees the specified filter.
+
1584 * When this function is called the given filter becomes invalid and it´s memory will be released.
+
1585 *
+
1586 * @warning Freeing a filter is not thread safe and the user is responsible for synchronization.
+
1587 *
+
1588 * @param[in] pFilter The filter to be freed.
+
1589 *
+
1590 * @return
+
1591 * Status | Description
+
1592 * ---------------------------------------------- | ------------------------------------------------------------------
+
1593 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1594 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1595 */
+
1596_BRAWCAP_API_FUNC(brawcap_status_t)
+
1597brawcap_filter_free(brawcap_filter_t* pFilter);
+
1598
+
1599/**
+
1600 * @brief Reads out the type for the specified filter.
+
1601 *
+
1602 * @param[in] pFilter The filter to read from.
+
1603 *
+
1604 * @param[out] pType Will contain the filter type, afterwards.
+
1605 *
+
1606 * @return
+
1607 * Status | Description
+
1608 * ---------------------------------------------- | ------------------------------------------------------------------
+
1609 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1610 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1611 */
+
1612_BRAWCAP_API_FUNC(brawcap_status_t)
+
1613brawcap_filter_type_get(brawcap_filter_t* const pFilter, brawcap_filter_type_t* const pType);
+
1614
+
1615/**
+
1616 * @brief Sets the filter parameters for the specified filter.
+
1617 *
+
1618 * @note Changes will only effect after applying the modified filter to a handle with @ref brawcap_rx_filter_set.
+
1619 *
+
1620 * @param[in] pFilter The filter to be modified.
+
1621 *
+
1622 * @param[in] offset Byte offset of the filter.
+
1623 * This value specifies at which packet byte offset the first filter byte shall be applied.
+
1624 *
+
1625 * @param[in] length Byte length of the filter.
+
1626 * Specifies the number of bytes used by the filter.
+
1627 * This value is limited to @ref BRAWCAP_FILTER_BYTE_MAX_LENGTH.
+
1628 *
+
1629 * @param[in] mask The byte mask for the filter.
+
1630 * This is a fixed size byte array.
+
1631 * Set the byte values to the filter you want to apply.
+
1632 * Only bytes up to the specified filter length are used and following bytes will be ignored.
+
1633 *
+
1634 * @param[in] ignoreBits A fixed size bitfield byte array.
+
1635 * The bytes in this array has to be interpreted/used as bitfields.
+
1636 * This allows to select if a single bit at the corresponding mask position shall be ignored.
+
1637 * To ignore the value of a bit set it´s value to 1.
+
1638 * Like the mask, only bytes up to the specified filter length are used and following bytes will be ignored.
+
1639 *
+
1640 * @return
+
1641 * Status | Description
+
1642 * ---------------------------------------------- | ------------------------------------------------------------------
+
1643 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1644 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1645 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | Specified filter is not of type @ref BRAWCAP_FILTER_TYPE_BYTE_MASK.
+
1646 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Specified offset+length exceeds @ref BRAWCAP_FILTER_BYTE_MAX_LENGTH.
+
1647 */
+
1648_BRAWCAP_API_FUNC(brawcap_status_t)
+
1649brawcap_filter_mask_set(brawcap_filter_t* const pFilter, const brawcap_filter_byte_length_t offset,
+
1650 const brawcap_filter_byte_length_t length, const brawcap_filter_mask_array_t mask,
+
1651 const brawcap_filter_ignore_bits_array_t ignoreBits);
+
1652
+
1653/**
+
1654 * @brief Reads out the filter mask parameters for the specified filter.
+
1655 *
+
1656 * @param[in] pFilter The filter to read from.
+
1657 *
+
1658 * @param[out] pOffset Will contain the filter byte offset, afterwards.
+
1659 *
+
1660 * @param[out] pLength Will contain the filter byte length, afterwards.
+
1661 *
+
1662 * @param[out] pMask Will contain the filter mask bytes, afterwards.
+
1663 *
+
1664 * @param[out] pIgnoreBits Will contain the filter bits to ignore, afterwards
+
1665 *
+
1666 * @return
+
1667 * Status | Description
+
1668 * ---------------------------------------------- | ------------------------------------------------------------------
+
1669 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1670 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1671 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | Specified filter is not of type @ref BRAWCAP_FILTER_TYPE_BYTE_MASK.
+
1672 */
+
1673_BRAWCAP_API_FUNC(brawcap_status_t)
+
1674brawcap_filter_mask_get(brawcap_filter_t* const pFilter, brawcap_filter_byte_length_t* const pOffset,
+
1675 brawcap_filter_byte_length_t* const pLength, brawcap_filter_mask_array_t* const pMask,
+
1676 brawcap_filter_ignore_bits_array_t* const pIgnoreBits);
+
1677
+
1678/**
+
1679 * @brief Sets the specified filter to active.
+
1680 *
+
1681 * @note Changes will only effect after applying the modified filter to a handle with @ref brawcap_rx_filter_set.
+
1682 *
+
1683 * @param[in] pFilter The filter to be modified.
+
1684 *
+
1685 * @return
+
1686 * Status | Description
+
1687 * ---------------------------------------------- | ------------------------------------------------------------------
+
1688 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1689 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1690 */
+
1691_BRAWCAP_API_FUNC(brawcap_status_t)
+
1692brawcap_filter_activate(brawcap_filter_t* const pFilter);
+
1693
+
1694/**
+
1695 * @brief Sets the specified filter to inactive.
+
1696 *
+
1697 * @note Changes will only effect after applying the modified filter to a handle with @ref brawcap_rx_filter_set.
+
1698 *
+
1699 * @param[in] pFilter The filter to be modified.
+
1700 *
+
1701 * @return
+
1702 * Status | Description
+
1703 * ---------------------------------------------- | ------------------------------------------------------------------
+
1704 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1705 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1706 */
+
1707_BRAWCAP_API_FUNC(brawcap_status_t)
+
1708brawcap_filter_deactivate(brawcap_filter_t* const pFilter);
+
1709
+
1710/**
+
1711 * @brief Reads out the current activation state of the specified filter.
+
1712 *
+
1713 * @param[in] pFilter The filter to read from.
+
1714 *
+
1715 * @param[out] pActive Will contain the activation state, afterwards.
+
1716 *
+
1717 * @return
+
1718 * Status | Description
+
1719 * ---------------------------------------------- | ------------------------------------------------------------------
+
1720 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1721 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1722 */
+
1723_BRAWCAP_API_FUNC(brawcap_status_t)
+
1724brawcap_filter_is_activated(brawcap_filter_t* const pFilter, BOOLEAN* const pActive);
+
1725
+
1726/**
+
1727 * @brief Sets the bytes to capture of the specified filter.
+
1728 *
+
1729 * @note Changes will only effect after applying the modified filter to a handle with @ref brawcap_rx_filter_set.
+
1730 *
+
1731 * @param[in] pFilter The filter to be modified.
+
1732 *
+
1733 * @param[in] offset The byte offset, from packet payload beginning, to begin capturing the payload bytes.
+
1734 *
+
1735 * @param[in] length The number of bytes to be captured - beginning at offset.
+
1736 *
+
1737 * @return
+
1738 * Status | Description
+
1739 * ---------------------------------------------- | ------------------------------------------------------------------
+
1740 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1741 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1742 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Specified offset+length exceeds @ref BRAWCAP_PACKET_SIZE_MAX.
+
1743 */
+
1744_BRAWCAP_API_FUNC(brawcap_status_t)
+
1745brawcap_filter_bytes_to_capture_set(brawcap_filter_t* const pFilter, const brawcap_packet_size_t offset,
+
1746 const brawcap_packet_size_t length);
+
1747
+
1748/**
+
1749 * @brief Reads out the configured bytes to capture of the specified filter.
+
1750 *
+
1751 * @param[in] pFilter The filter to read from.
+
1752 *
+
1753 * @param[out] pOffset Will contain the byte offset of the bytes to capture, afterwards.
+
1754 *
+
1755 * @param[out] pLength Will contain the number of bytes to capture, afterwards.
+
1756 *
+
1757 * @return
+
1758 * Status | Description
+
1759 * ---------------------------------------------- | ------------------------------------------------------------------
+
1760 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1761 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1762 */
+
1763_BRAWCAP_API_FUNC(brawcap_status_t)
+
1764brawcap_filter_bytes_to_capture_get(brawcap_filter_t* const pFilter, brawcap_packet_size_t* const pOffset,
+
1765 brawcap_packet_size_t* const pLength);
+
1766
+
1767/**
+
1768 * @brief Specifies if packets which matched the specified filter should be indicated to the network stack.
+
1769 *
+
1770 * @note Changes will only effect after applying the modified filter to a handle with @ref brawcap_rx_filter_set.
+
1771 *
+
1772 * @param[in] pFilter The filter to be modified.
+
1773 *
+
1774 * @param[in] indicate Flag specifying the network stack indication.
+
1775 * If true filtered packets are forwarded to the network stack.
+
1776 * If false filtered packets are not forwarded to the network stack, they are only visible for bRAWcap handles.
+
1777 *
+
1778 * @return
+
1779 * Status | Description
+
1780 * ---------------------------------------------- | ------------------------------------------------------------------
+
1781 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1782 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1783 */
+
1784_BRAWCAP_API_FUNC(brawcap_status_t)
+
1785brawcap_filter_indicate_set(brawcap_filter_t* const pFilter, const BOOLEAN indicate);
+
1786
+
1787/**
+
1788 * @brief Reads out the current network stack indication state of the specified filter.
+
1789 *
+
1790 * @param[in] pFilter The filter to read from.
+
1791 *
+
1792 * @param[out] pIndicate Will contain the current network stack indication, afterwards.
+
1793 *
+
1794 * @return
+
1795 * Status | Description
+
1796 * ---------------------------------------------- | ------------------------------------------------------------------
+
1797 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1798 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the pointer parameters was invalid.
+
1799 */
+
1800_BRAWCAP_API_FUNC(brawcap_status_t)
+
1801brawcap_filter_indicate_get(brawcap_filter_t* const pFilter, BOOLEAN* const pIndicate);
+
1802
+
1803/**@}*/
+
1804#endif
+
1805
+
1806/**
+
1807 * @brief Receives a single packet from the specified handle.
+
1808 *
+
1809 * The caller must provide a valid packet were bRAWcap will store the received data.
+
1810 * To create a packet use @ref brawcap_packet_create or use a buffered packet which was returned by a
+
1811 * valid buffer with @ref brawcap_buffer_at_index.
+
1812 *
+
1813 * @note Parallel receives per handle are not allowed. This means that if there is any other receive pending on the
+
1814 * handle each further initiated receive will fail until the pending operation has finished.
+
1815 *
+
1816 * @param[in] pHandle bRAWcap handle to receive from.
+
1817 *
+
1818 * @param[out] pPacket Packet were the received data will be stored.
+
1819 *
+
1820 * @return
+
1821 * Status | Description
+
1822 * ---------------------------------------------- | -----------------------------------------------------------
+
1823 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1824 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1825 * @ref BRAWCAP_STATUS_WARNING_PENDING | Another receive is still pending/active.
+
1826 * @ref BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE | bRAWcap driver is not active (anymore) on the adapter.
+
1827 * @ref BRAWCAP_STATUS_WARNING_DEMO_MODE | Running in demo mode (no license).
+
1828 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
1829 * @ref BRAWCAP_STATUS_INFO_NO_DATA | Returned without any data received (due to timeout).
+
1830 */
+
1831_BRAWCAP_API_FUNC(brawcap_status_t)
+
1832brawcap_rx_packet(brawcap_handle_t* const pHandle, brawcap_packet_t* const pPacket);
+
1833
+
1834/**
+
1835 * @brief Starts the internal receive loop.
+
1836 *
+
1837 * To receive data using this method it is necessary to attach memory to the
+
1838 * bRAWcap handle were received data can be stored. This can be done by attaching (with @ref brawcap_rx_buffer_attach)
+
1839 * a previously created bRAWcap packet buffer (with @ref brawcap_buffer_create).
+
1840 *
+
1841 * When a reception has finished (due to timeout, min packets or full buffer) the receive callback will be called
+
1842 * for this handle (@ref brawcap_rx_callback_t). In this callback the user application can do it´s post
+
1843 * processing on the received data. If the user application does not detach the buffer
+
1844 * (with @ref brawcap_rx_buffer_detach) it will be reused for receiving after callback has completed.
+
1845 *
+
1846 * The user application should do it´s post processing anyway, as fast as possible. Depending on the current
+
1847 * bandwidth the attached buffers may be filled up very fast. If the user application takes to long it
+
1848 * will lead to a bottleneck in the reception and the driver runs out of resources. This may result in performance
+
1849 * degradation or packet loss.
+
1850 *
+
1851 * It is possible to attach more than only one buffer to a single handle. This ensures that the bRAWcap driver can
+
1852 * toggle the buffers during the reception. This reduces the time gap the driver has to buffer data internally (because
+
1853 * there is no user buffer available). With more than one buffer the driver can still fill up another buffer while the
+
1854 * user application does it´s post processing. Therefore in general, using more than one buffer increases the
+
1855 * performance.
+
1856 *
+
1857 * @note Due to the focus on optimized throughput with minimal CPU load bRAWcap does not fill up the packets in the
+
1858 * buffer with the same sequence they were received by the adapter.
+
1859 * Here we want to give some additional information on the topic of "packet sequence/timestamp":
+
1860 * - First of all it should be known that the receive sequence may not be equal to the sending sequence.
+
1861 * Due to several senders or some network managers in between (switches and so on...).
+
1862 * For any protocols which require a ordered packet stream, there will be at least one field in the packet
+
1863 * payload which allows to sort the packets on the receiver side.
+
1864 * This is a "higher" layer topic and not part of bRAWcap.
+
1865 * - With the bRAWcap supported timestamp mechanisms it is possible to sort the received packets corresponding to
+
1866 * their receive timestamps. But keep in mind that only the @ref BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE guarantees
+
1867 * that the receive timestamps really match the received packet sequence on the adapter. To use the named timestamp
+
1868 * mechanism, the underlying network adapter must support it. Any other timestamp is generated by software. Windows
+
1869 * is not a realtime operation system, and therefore due to multithreading, scheduling (...) it could happen
+
1870 * that some packets are processed before other packets which was received earlier.
+
1871 * Especially the Windows network stack feature called "receive side scaling" can also increase the issue
+
1872 * of incorrect packet sequences.
+
1873 *
+
1874 * @invariant The user parameter allows access to user defined context.
+
1875 * The given pointer is not used and validated by bRAWcap. Therefore the user is responsible for validating
+
1876 * the context in the callback before accessing it.
+
1877 *
+
1878 * @attention After starting receive @ref brawcap_rx_packet can not be used until you stop the receive
+
1879 * with @ref brawcap_rx_stop, because parallel receives are not allowed.
+
1880 *
+
1881 * @param[in] pHandle bRAWcap handle to receive from.
+
1882 *
+
1883 * @param[in] callback Function pointer to user application receive callback.
+
1884 *
+
1885 * @param[in] pUser Pointer to a user defined context. Can be NULL if no user context is required.
+
1886 *
+
1887 * @param[in] indicateNoPackets Specifies if callback is called even without any received data.
+
1888 *
+
1889 * @return
+
1890 * Status | Description
+
1891 * ---------------------------------------------- | -----------------------------------------------------------
+
1892 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1893 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1894 * @ref BRAWCAP_STATUS_WARNING_PENDING | Another receive is pending or reception is already started.
+
1895 */
+
1896_BRAWCAP_API_FUNC(brawcap_status_t)
+
1897brawcap_rx_start(brawcap_handle_t* const pHandle, brawcap_rx_callback_t const callback, void* const pUser,
+
1898 const BOOLEAN indicateNoPackets);
+
1899
+
1900/**
+
1901 * @brief Stops the internal receive loop.
+
1902 *
+
1903 * @param[in] pHandle bRAWcap handle to stop reception.
+
1904 *
+
1905 * @return
+
1906 * Status | Description
+
1907 * ---------------------------------------------- | -----------------------------------------------------------
+
1908 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1909 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1910 * @ref BRAWCAP_STATUS_INFO_NOT_RUNNING | There was no receive running.
+
1911 */
+
1912_BRAWCAP_API_FUNC(brawcap_status_t)
+
1913brawcap_rx_stop(brawcap_handle_t* const pHandle);
+
1914
+
1915/**
+
1916 * @brief Attaches the specified bRAWcap packet buffer to the specified handle.
+
1917 *
+
1918 * After attaching a packet buffer to a handle it will be used for receiving data on that handle.
+
1919 * Data is only received if the internal receive loop was started/is running (with @ref brawcap_rx_start).
+
1920 *
+
1921 * The buffer is locked until:
+
1922 * - It is detached from the handle with @ref brawcap_rx_buffer_detach.
+
1923 * - A receive has finished and the receive callback is called (buffer is not locked during callback execution).
+
1924 *
+
1925 * @note A buffer can be attached only once and is than locked down by the handle it is attached to.
+
1926 * This means that it has to be detached before it can be used again for another handle.
+
1927 *
+
1928 * @param[in] pHandle bRAWcap handle for attaching the buffer.
+
1929 *
+
1930 * @param[in] pBuffer Packet buffer to be attached.
+
1931 *
+
1932 * @return
+
1933 * Status | Description
+
1934 * ---------------------------------------------- | -----------------------------------------------------------
+
1935 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1936 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1937 * @ref BRAWCAP_STATUS_ERROR_IN_USE | The buffer is already in use / locked down by another operation.
+
1938 * @ref BRAWCAP_STATUS_WARNING_LIMIT_REACHED | Limitation of buffer per handle reached (@ref BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX)
+
1939 */
+
1940_BRAWCAP_API_FUNC(brawcap_status_t)
+
1941brawcap_rx_buffer_attach(brawcap_handle_t* const pHandle, brawcap_buffer_t* const pBuffer);
+
1942
+
1943/**
+
1944 * @brief Detaches the specified bRAWcap packet buffer from the specified handle.
+
1945 *
+
1946 * After detaching a buffer it is unlocked and can be accessed/modified.
+
1947 * It can also be reused for another operation or freed with @ref brawcap_buffer_free if it is not required anymore.
+
1948 *
+
1949 * @param[in] pHandle bRAWcap handle from which the buffer is to be detached.
+
1950 *
+
1951 * @param[in] pBuffer Packet buffer to be detached.
+
1952 *
+
1953 * @return
+
1954 * Status | Description
+
1955 * ---------------------------------------------- | -----------------------------------------------------------
+
1956 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1957 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1958 * @ref BRAWCAP_STATUS_INFO_NOT_ATTACHED | The buffer was not attached.
+
1959 */
+
1960_BRAWCAP_API_FUNC(brawcap_status_t)
+
1961brawcap_rx_buffer_detach(brawcap_handle_t* const pHandle, brawcap_buffer_t* const pBuffer);
+
1962
+
1963/**
+
1964 * @brief Sets the receive direction for the specified handle.
+
1965 *
+
1966 * Possible directions are:
+
1967 * - @ref BRAWCAP_RX_DIRECTION_UNKNOWN
+
1968 * - @ref BRAWCAP_RX_DIRECTION_IN
+
1969 * - @ref BRAWCAP_RX_DIRECTION_OUT
+
1970 * - @ref BRAWCAP_RX_DIRECTION_BOTH
+
1971 *
+
1972 * @param[in] pHandle bRAWcap handle to be configured.
+
1973 *
+
1974 * @param[in] direction The direction to be set.
+
1975 *
+
1976 * @return
+
1977 * Status | Description
+
1978 * ---------------------------------------------- | -----------------------------------------------------------
+
1979 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1980 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1981 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
1982 */
+
1983_BRAWCAP_API_FUNC(brawcap_status_t)
+
1984brawcap_rx_direction_set(brawcap_handle_t* const pHandle, const brawcap_rx_direction_t direction);
+
1985
+
1986/**
+
1987 * @brief Reads out the currently configured receive direction of the specified handle.
+
1988 *
+
1989 * @param[in] pHandle bRAWcap handle to read from.
+
1990 *
+
1991 * @param[out] pDirection Will contain the currently configured receive direction, afterwards.
+
1992 *
+
1993 * @return
+
1994 * Status | Description
+
1995 * ---------------------------------------------- | -----------------------------------------------------------
+
1996 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
1997 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
1998 */
+
1999_BRAWCAP_API_FUNC(brawcap_status_t)
+
2000brawcap_rx_direction_get(brawcap_handle_t* const pHandle, brawcap_rx_direction_t* const pDirection);
+
2001
+
2002/**
+
2003 * @brief Sets the minimum amount of packets to receive for the specified handle.
+
2004 *
+
2005 * This value influences how often the bRAWcap driver will return pending receives.
+
2006 * It forces the driver to stay in the request as long as not the minimum amount of packets were captured.
+
2007 * Setting a higher value here can reduce the overall system load but increases also the responsiveness/latency
+
2008 * when the packet was received by the adapter and the indication of the packet to the caller.
+
2009 * The initial/default value is set to @ref BRAWCAP_RX_COPY_PACKETS_DEFAULT.
+
2010 *
+
2011 * @invariant If high receive rates should be reached (and many packets coming in), a high value is preferred.
+
2012 * Otherwise if low latency is required the best effort would be to set this value to zero.
+
2013 *
+
2014 * @note Independent from this value the receive will at least return if it pends for 10 times the configured
+
2015 * receive timeout. This avoid infinite blocking (infinite blocking is only the possible if the receive timeout is zero).
+
2016 * If this value is set to zero it will always return after the first receive timeout.
+
2017 * And if the given buffer becomes filled up before the timeout is reached it will return when the buffer is full.
+
2018 *
+
2019 * @param[in] pHandle bRAWcap handle to be configured.
+
2020 *
+
2021 * @param[in] minPackets The minimum amount of packets to receive.
+
2022 *
+
2023 * @return
+
2024 * Status | Description
+
2025 * ---------------------------------------------- | -----------------------------------------------------------
+
2026 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2027 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2028 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2029 */
+
2030_BRAWCAP_API_FUNC(brawcap_status_t)
+
2031brawcap_rx_min_packets_set(brawcap_handle_t* const pHandle, const brawcap_rx_min_packets_t minPackets);
+
2032
+
2033/**
+
2034 * @brief Reads out the currently configured number of packets to receive for the specified handle.
+
2035 *
+
2036 * @param[in] pHandle bRAWcap handle to read from.
+
2037 *
+
2038 * @param[out] pMinPackets Will contain the configured minimum amount of packets per receive, afterwards.
+
2039 *
+
2040 * @return
+
2041 * Status | Description
+
2042 * ---------------------------------------------- | -----------------------------------------------------------
+
2043 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2044 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2045 */
+
2046_BRAWCAP_API_FUNC(brawcap_status_t)
+
2047brawcap_rx_min_packets_get(brawcap_handle_t* const pHandle, brawcap_rx_min_packets_t* const pMinPackets);
+
2048
+
2049/**
+
2050 * @brief Configures the receive timeout for the specified handle.
+
2051 *
+
2052 * It´s guaranteed that receive functions will return at least after the specified timeout value,
+
2053 * if the configured amount of packets value @ref brawcap_rx_min_packets_t is reached before.
+
2054 * If the configured amount of packets are not reached until the timeout occurs, the driver will stay in the request
+
2055 * for up to 10 times of the specified timeout time until it final returns.
+
2056 * It is also possible to specify a timeout of zero. A timeout of zero is equivalent to "no timeout".
+
2057 *
+
2058 * @note Default timeout value is @ref BRAWCAP_RX_TIMEOUT_MS_DEFAULT.
+
2059 * And the max supported timeout is @ref BRAWCAP_RX_TIMEOUT_MS_MAX.
+
2060 *
+
2061 * @attention Be careful in using infinite timeouts.
+
2062 * It could lead to a endless blocking behaviour.
+
2063 * For example if there are no packets received which meet your configured filter on the underlying adapter.
+
2064 *
+
2065 * @param[in] pHandle bRAWcap handle to be configured.
+
2066 *
+
2067 * @param[in] timeout_ms Receive timeout in milliseconds to be set.
+
2068 *
+
2069 * @return
+
2070 * Status | Description
+
2071 * ---------------------------------------------- | -----------------------------------------------------------
+
2072 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2073 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2074 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The specified timeout value is invalid/out of range.
+
2075 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2076 */
+
2077_BRAWCAP_API_FUNC(brawcap_status_t)
+
2078brawcap_rx_timeout_set(brawcap_handle_t* const pHandle, const brawcap_rx_timeout_t timeout_ms);
+
2079
+
2080/**
+
2081 * @brief Reads out the currently configured receive timeout for the specified handle
+
2082 *
+
2083 * @param[in] pHandle bRAWcap handle to read from.
+
2084 *
+
2085 * @param[out] pTimeout_ms Will contain the configured receive timeout in milliseconds, afterwards.
+
2086 *
+
2087 * @return
+
2088 * Status | Description
+
2089 * ---------------------------------------------- | -----------------------------------------------------------
+
2090 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2091 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2092 */
+
2093_BRAWCAP_API_FUNC(brawcap_status_t)
+
2094brawcap_rx_timeout_get(brawcap_handle_t* const pHandle, brawcap_rx_timeout_t* const pTimeout_ms);
+
2095
+
2096/**
+
2097 * @brief Sets the specified filter to the specified handle.
+
2098 *
+
2099 * For more information on filters see @ref brawcap_filter_t.
+
2100 *
+
2101 * @note Each handle can have exactly one filter applied.
+
2102 * If several filters shall be applied to the same adapter,
+
2103 * it is required to open several bRAWcap handles to the same adapter.
+
2104 *
+
2105 * @param[in] pHandle bRAWcap handle to be modified.
+
2106 *
+
2107 * @param[in] pFilter The filter to set.
+
2108 *
+
2109 * @return
+
2110 * Status | Description
+
2111 * ---------------------------------------------- | -----------------------------------------------------------
+
2112 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2113 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2114 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2115 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Specified filter type is not available.
+
2116 */
+
2117_BRAWCAP_API_FUNC(brawcap_status_t)
+
2118brawcap_rx_filter_set(brawcap_handle_t* const pHandle, const brawcap_filter_t* const pFilter);
+
2119
+
2120/**
+
2121 * @brief Reads out the currently configured filter for the specified handle.
+
2122 *
+
2123 * @param[in] pHandle bRAWcap handle to read from.
+
2124 *
+
2125 * @param[out] pFilter Will contain the currently configured filter, afterwards.
+
2126 *
+
2127 * @return
+
2128 * Status | Description
+
2129 * ---------------------------------------------- | -----------------------------------------------------------
+
2130 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2131 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2132 */
+
2133_BRAWCAP_API_FUNC(brawcap_status_t)
+
2134brawcap_rx_filter_get(brawcap_handle_t* const pHandle, brawcap_filter_t* const pFilter);
+
2135
+
2136/**
+
2137 * @brief Sets the current promiscuous mode flag for the specified handle.
+
2138 *
+
2139 * If a adapter is set into promiscuous mode it receives not only packages which directly address the adapter.
+
2140 * This can be used for recording/sniffing purposes but increases the local system load.
+
2141 * Promiscuous mode is a network adapter feature and which can only be modified by bRAWcap.
+
2142 * Therefore it is not specific to a bRAWcap handle. Instead it is a per adapter setting which can also be
+
2143 * modified from another application.
+
2144 *
+
2145 * @note Promiscuous mode will be reset automatically upon deleting the corresponding handle.
+
2146 * Which means if it was activated due to the bRAWcap handle it will be disabled again when the handle is closed.
+
2147 *
+
2148 * @attention Because of the per adapter scope, promiscuous mode can not explicitly modified by bRAWcap.
+
2149 * Instead if at least one application or another bRAWcap handle activated it, it will stay enabled until the last
+
2150 * application/handle which has activated it, is closed or deactivates it again.
+
2151 *
+
2152 * @param[in] pHandle bRAWcap handle to be modified.
+
2153 *
+
2154 * @param[in] enable Promiscuous mode state to be set.
+
2155 *
+
2156 * @return
+
2157 * Status | Description
+
2158 * ---------------------------------------------- | -----------------------------------------------------------
+
2159 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2160 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2161 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2162 */
+
2163_BRAWCAP_API_FUNC(brawcap_status_t)
+
2164brawcap_rx_promiscuous_mode_set(brawcap_handle_t* const pHandle, const BOOLEAN enable);
+
2165
+
2166/**
+
2167 * @brief Reads out the current promiscuous mode state for the specified handle.
+
2168 *
+
2169 * Additionally to the promiscuous state of the handle itself it also reads the current promiscuous state of to the
+
2170 * underlying adapter.
+
2171 *
+
2172 * @param[in] pHandle bRAWcap handle to read from.
+
2173 *
+
2174 * @param[out] pEnabled Will contain the current promiscuous mode state of the handle, afterwards.
+
2175 *
+
2176 * @param[out] pEnabledAdapter Will contain the current promiscuous mode state of the underlying adapter, afterwards.
+
2177 *
+
2178 * @return
+
2179 * Status | Description
+
2180 * ---------------------------------------------- | -----------------------------------------------------------
+
2181 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2182 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2183 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2184 */
+
2185_BRAWCAP_API_FUNC(brawcap_status_t)
+
2186brawcap_rx_promiscuous_mode_get(brawcap_handle_t* const pHandle, BOOLEAN* const pEnabled,
+
2187 BOOLEAN* const pEnabledAdapter);
+
2188
+
2189/**
+
2190 * @brief Reads out the available receive timestamp modes for the specified handle.
+
2191 *
+
2192 * Some of the timestamp capabilites depend on the features provided by the underlying adapter.
+
2193 * Those modes are named with "adapter".
+
2194 *
+
2195 * @param[in] pHandle bRAWcap handle to read from.
+
2196 *
+
2197 * @param[out] pCapabilities Will contain the available receive timestamp modes, afterwards.
+
2198 *
+
2199 * @return
+
2200 * Status | Description
+
2201 * ---------------------------------------------- | -----------------------------------------------------------
+
2202 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2203 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2204 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2205 */
+
2206_BRAWCAP_API_FUNC(brawcap_status_t)
+
2207brawcap_rx_timestamp_capabilities(brawcap_handle_t* const pHandle,
+
2208 brawcap_timestamp_capabilities_t* const pCapabilities);
+
2209
+
2210/**
+
2211 * @brief Reads out the currently configured receive time stamping mode for the specified handle.
+
2212 *
+
2213 * @param[in] pHandle bRAWcap handle to read from.
+
2214 *
+
2215 * @param[out] pMode Will contain the currently used receive time stamping mode, afterwards.
+
2216 *
+
2217 * @return
+
2218 * Status | Description
+
2219 * ---------------------------------------------- | -----------------------------------------------------------
+
2220 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2221 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2222 */
+
2223_BRAWCAP_API_FUNC(brawcap_status_t)
+
2224brawcap_rx_timestamp_mode_get(brawcap_handle_t* const pHandle, brawcap_timestamp_mode_t* const pMode);
+
2225
+
2226/**
+
2227 * @brief Configures the used receive time stamping mode for the specified handle.
+
2228 *
+
2229 *
+
2230 * @note Only available timestamp modes are accepted. It is recommended to check if a timestamp mode is supported
+
2231 * before setting it. To check if a timestamp mode is available use @ref brawcap_rx_timestamp_capabilities.
+
2232 *
+
2233 * @param[in] pHandle bRAWcap handle to be configured.
+
2234 *
+
2235 * @param[out] mode The receive timestamp mode to be configured.
+
2236 *
+
2237 * @return
+
2238 * Status | Description
+
2239 * ---------------------------------------------- | -----------------------------------------------------------
+
2240 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2241 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2242 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Specified timestamp mode not available.
+
2243 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2244 */
+
2245_BRAWCAP_API_FUNC(brawcap_status_t)
+
2246brawcap_rx_timestamp_mode_set(brawcap_handle_t* const pHandle, const brawcap_timestamp_mode_t mode);
+
2247
+
2248/**
+
2249 * @brief Sets the current VLAN tagging flag for the specified handle.
+
2250 *
+
2251 * If VLAN tagging is enabled, the VLAN Header (defined by IEEE 802.1Q) will be part of the packet payload.
+
2252 * By default, the VLAN header is not included in the packet payload.
+
2253 *
+
2254 * @param[in] pHandle bRAWcap handle to be configured.
+
2255 *
+
2256 * @param[in] enable VLAN tagging state to be set.
+
2257 *
+
2258 * @return
+
2259 * Status | Description
+
2260 * ---------------------------------------------- | -----------------------------------------------------------
+
2261 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2262 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2263 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2264 */
+
2265_BRAWCAP_API_FUNC(brawcap_status_t)
+
2266brawcap_rx_vlan_tagging_set(brawcap_handle_t* const pHandle, const BOOLEAN enable);
+
2267
+
2268/**
+
2269 * @brief Reads out the configured VLAN tagging state for the specified handle.
+
2270 *
+
2271 * @param[in] pHandle bRAWcap handle to read from.
+
2272 *
+
2273 * @param[out] pEnabled Will contain the currently configured VLAN tagging state, afterwards.
+
2274 *
+
2275 * @return
+
2276 * Status | Description
+
2277 * ---------------------------------------------- | -----------------------------------------------------------
+
2278 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2279 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2280 */
+
2281_BRAWCAP_API_FUNC(brawcap_status_t)
+
2282brawcap_rx_vlan_tagging_get(brawcap_handle_t* const pHandle, BOOLEAN* const pEnabled);
+
2283
+
2284/**
+
2285 * @brief Sets the driver queue size (in number of packets) for the specified handle.
+
2286 *
+
2287 * A larger driver queue can avoid packet drops for time gaps were no packet buffer is available.
+
2288 * But setting large driver queues should only be done if really necessary, because it can consume a lot of memory.
+
2289 * Because driver queues exist per handle, the total amount of consumed memory has to summed up for all open handles
+
2290 * and their current configuration.
+
2291 *
+
2292 * The driver queue size can be adjusted at any time.
+
2293 *
+
2294 * @note The default queue size is @see BRAWCAP_RX_DRIVER_QUEUE_SIZE_DEFAULT (in number of packets).
+
2295 * And its max limitation is @see BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX (in number of packets).
+
2296 *
+
2297 * @attention Reducing the queue size during runtime may result in packet loss.
+
2298 * This may be the case if there are more packets stored in the queue than the new size can accommodate.
+
2299 *
+
2300 * @param[in] pHandle bRAWcap handle to be configured.
+
2301 *
+
2302 * @param[in] size Driver receive queue size to be set.
+
2303 *
+
2304 * @return
+
2305 * Status | Description
+
2306 * ---------------------------------------------- | -----------------------------------------------------------
+
2307 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2308 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2309 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Specified queue size is out of range/invalid.
+
2310 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2311 */
+
2312_BRAWCAP_API_FUNC(brawcap_status_t)
+
2313brawcap_rx_driver_queue_size_set(brawcap_handle_t* const pHandle, const brawcap_queue_size_t size);
+
2314
+
2315/**
+
2316 * @brief Reads out the currently configured driver receive queue size for the specified handle.
+
2317 *
+
2318 * @param[in] pHandle bRAWcap handle to read from.
+
2319 *
+
2320 * @param[out] pSize Will contain the currently configured driver receive queue size, afterwards.
+
2321 *
+
2322 * @return
+
2323 * Status | Description
+
2324 * ---------------------------------------------- | -----------------------------------------------------------
+
2325 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2326 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2327 */
+
2328_BRAWCAP_API_FUNC(brawcap_status_t)
+
2329brawcap_rx_driver_queue_size_get(brawcap_handle_t* const pHandle, brawcap_queue_size_t* const pSize);
+
2330
+
2331/**@}*/
+
2332#endif
+
2333
+
2334/*********************************************** TRANSMIT ************************************************************/
+
2335#if 1
+
2336/**
+
2337 * @addtogroup brawcap_transmit
+
2338 * @{
+
2339 */
+
2340
+
2341/**
+
2342 * @brief Transmits a single packet on the specified handle.
+
2343 *
+
2344 * The caller must provide a valid packet filled up with the payload to transmit.
+
2345 *
+
2346 * For creating a packet use @ref brawcap_packet_create. After creating the packet set all the required packet fields
+
2347 * and than call this function to initiate a transmission.
+
2348 *
+
2349 * When transmission has finished (the function returns) the packet fields are updated.
+
2350 *
+
2351 * To check if the transmission was successful check for the function return status or the packet status itself
+
2352 * with @ref brawcap_packet_status_get. If the packet was transmitted and transmit time stamping was enabled the packet
+
2353 * timestamp will contain the transmission time, which be accessed with @ref brawcap_packet_timestamp_get.
+
2354 *
+
2355 * @param[in] pHandle bRAWcap handle to transmit on.
+
2356 *
+
2357 * @param[inout] pPacket Packet to be transmitted.
+
2358 *
+
2359 * @return
+
2360 * Status | Description
+
2361 * ---------------------------------------------- | -----------------------------------------------------------
+
2362 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2363 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2364 * @ref BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE | bRAWcap driver is not active (anymore) on the adapter.
+
2365 * @ref BRAWCAP_STATUS_WARNING_DEMO_MODE | Running in demo mode (no license).
+
2366 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2367 * @ref BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED | The transmission failed (or payload was not fully transmitted).
+
2368 */
+
2369_BRAWCAP_API_FUNC(brawcap_status_t)
+
2370brawcap_tx_packet(brawcap_handle_t* const pHandle, brawcap_packet_t* const pPacket);
+
2371
+
2372/**
+
2373 * @brief Starts the internal transmit loop.
+
2374 *
+
2375 * To transmit data using this method push previously filled packet buffers to the handle by using
+
2376 * @ref brawcap_tx_buffer_send. After that the buffer will be locked down by the handle and added to it´s transmission
+
2377 * queue.
+
2378 *
+
2379 * For creating a new packet buffer which can be used for transmission use @ref brawcap_buffer_create.
+
2380 *
+
2381 * When a packet buffer transmission has completed the @ref brawcap_tx_callback_t "transmit callback" will be
+
2382 * called for this handle and with the corresponding packet buffer. From within the callback the buffer can be
+
2383 * accessed for post processing (it is unlocked before entering the callback). It is also possible to do
+
2384 * post processing from a different thread and after the callback.
+
2385 *
+
2386 * In general executing to long in the callback can lead to a bottleneck in the transmission.
+
2387 * It´s not as critical as it is for receiving but it should be still kept in mind.
+
2388 *
+
2389 * Like @ref brawcap_tx_packet does, also each packet in transmitted packet buffers will be updated (e.g. packet status,
+
2390 * transmission timestamp). The user application can access those updated information after transmission has completed.
+
2391 *
+
2392 * A completed packet buffer transmission will automatically detach the buffer from the handle.
+
2393 * It is not needed to detach it explicitly (which would be required for receive buffers).
+
2394 *
+
2395 * @note The buffers are transmitted in the same order they have been added by the user application with
+
2396 * @ref brawcap_tx_buffer_send.
+
2397 *
+
2398 * @invariant The user parameter allows access to user defined context.
+
2399 * The given pointer is not used and validated by bRAWcap. Therefore the user is responsible for validating
+
2400 * the context in the callback before accessing it.
+
2401 *
+
2402 * @attention After starting transmission, @ref brawcap_tx_packet can not be used - on this handle - until tranmission
+
2403 * is stopped with @ref brawcap_tx_stop, because parallel transmissions are not allowed
+
2404 *
+
2405 * @param[in] pHandle bRAWcap handle to transmit on.
+
2406 *
+
2407 * @param[in] callback Function pointer to user application transmit callback.
+
2408 *
+
2409 * @param[in] pUser Pointer to a user defined context. Can be NULL if no user context is required.
+
2410 *
+
2411 * @return
+
2412 * Status | Description
+
2413 * ---------------------------------------------- | -----------------------------------------------------------
+
2414 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2415 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2416 * @ref BRAWCAP_STATUS_WARNING_PENDING | Another transmit is pending or transmission is already started.
+
2417 */
+
2418_BRAWCAP_API_FUNC(brawcap_status_t)
+
2419brawcap_tx_start(brawcap_handle_t* const pHandle, brawcap_tx_callback_t const callback, void* pUser);
+
2420
+
2421/**
+
2422 * @brief Stops the internal transmit loop.
+
2423 *
+
2424 * @param[in] pHandle bRAWcap handle to stop transmission on.
+
2425 *
+
2426 * @return
+
2427 * Status | Description
+
2428 * ---------------------------------------------- | -----------------------------------------------------------
+
2429 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2430 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2431 * @ref BRAWCAP_STATUS_INFO_NOT_RUNNING | There was no transmission running.
+
2432 */
+
2433_BRAWCAP_API_FUNC(brawcap_status_t)
+
2434brawcap_tx_stop( brawcap_handle_t* const pHandle);
+
2435
+
2436/**
+
2437 * @brief Pushes the specified buffer to the specified handle transmit queue.
+
2438 *
+
2439 * After pushing a packet buffer to the handle for transmission it is locked down by the handle until transmission
+
2440 * has completed (and the @ref brawcap_tx_callback_t "transmit callback" is called).
+
2441 *
+
2442 * With the synchronized flag it is possible to activate a synchronized transmission of the specified packet buffer.
+
2443 * This means that the driver reads the time gap between each packet in the packet buffer and waits until it has been
+
2444 * elapsed before initiating transmission.
+
2445 *
+
2446 * @attention For synchronized transmission it is necessary to sort the packets in the buffer by rising timestamp.
+
2447 * Furthermore, it is currently not supported to specify a "start time" when the first packet should be transmitted.
+
2448 * Therefore if you want to start transmission depending on the first packet timestamp you should wait until the
+
2449 * time is reached and after this initiate the transmission by calling this function. The driver itself only
+
2450 * evaluates the time gaps between each packet in the buffer.
+
2451 *
+
2452 * @note Packet buffers are transmitted in the same order they was pushed to the handle.
+
2453 *
+
2454 * @invariant Keep in mind that the packet timestamp is updated after transmission has been completed by the
+
2455 * transmission timestamp (depending on the configured timestamp mode). Therefore if there was a packet timestamp set
+
2456 * for example to send synchronized, this timestamp will be overwritten.
+
2457 *
+
2458 * @param[in] pHandle bRAWcap handle for sending the buffer.
+
2459 *
+
2460 * @param[in] pBuffer Packet buffer to be sent.
+
2461 *
+
2462 * @param[in] synchronized Flag indicating if the packets in the packet buffer should be sent synchronized.
+
2463 *
+
2464 * @return
+
2465 * Status | Description
+
2466 * ---------------------------------------------- | -----------------------------------------------------------
+
2467 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2468 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2469 * @ref BRAWCAP_STATUS_ERROR_IN_USE | The buffer is already in use / locked down by another operation.
+
2470 */
+
2471_BRAWCAP_API_FUNC(brawcap_status_t)
+
2472brawcap_tx_buffer_send(brawcap_handle_t* const pHandle, brawcap_buffer_t* const pBuffer, const BOOLEAN synchronized);
+
2473
+
2474/**
+
2475 * @brief Sets the driver queue size (in number of packets) for the specified handle.
+
2476 *
+
2477 * For transmission the driver queue size may be increased if high data rates should be reached (for example 10GBit/s).
+
2478 * With a larger transmission queue the driver can forward more packets to the network adapter at the same time.
+
2479 * Therefore if the transmission rate is below the expected value it may be solved by a larger driver queue size.
+
2480 *
+
2481 * The driver queue size can be adjusted at any time.
+
2482 *
+
2483 * @note The default queue size is @see BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT (in number of packets).
+
2484 * And its max limitation is @see BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX (in number of packets).
+
2485 *
+
2486 * @attention Reducing the queue size during runtime may result in packet transmission cancellation.
+
2487 * This may be the case if there are more packets pending for transmission than the new size can accommodate.
+
2488 *
+
2489 * @param[in] pHandle bRAWcap handle to be configured.
+
2490 *
+
2491 * @param[in] size Driver transmit queue size to be set.
+
2492 *
+
2493 * @return
+
2494 * Status | Description
+
2495 * ---------------------------------------------- | -----------------------------------------------------------
+
2496 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2497 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2498 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | Specified queue size is out of range/invalid.
+
2499 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2500 */
+
2501_BRAWCAP_API_FUNC(brawcap_status_t)
+
2502brawcap_tx_driver_queue_size_set(brawcap_handle_t* const pHandle, const brawcap_queue_size_t size);
+
2503
+
2504/**
+
2505 * @brief Reads out the currently configured driver transmit queue size for the specified handle.
+
2506 *
+
2507 * @param[in] pHandle bRAWcap handle to read from.
+
2508 *
+
2509 * @param[out] pSize Will contain the currently configured driver transmit queue size, afterwards.
+
2510 *
+
2511 * @return
+
2512 * Status | Description
+
2513 * ---------------------------------------------- | -----------------------------------------------------------
+
2514 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2515 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2516 */
+
2517_BRAWCAP_API_FUNC(brawcap_status_t)
+
2518brawcap_tx_driver_queue_size_get(brawcap_handle_t* const pHandle, brawcap_queue_size_t* const pSize);
+
2519
+
2520/**
+
2521 * @brief Reads out the available transmit timestamp modes for the specified handle.
+
2522 *
+
2523 * Some of the timestamp capabilities depend on the features provided by the underlying adapter.
+
2524 * Those modes are named with "adapter".
+
2525 *
+
2526 * @param[in] pHandle bRAWcap handle to read from.
+
2527 *
+
2528 * @param[out] pCapabilities Will contain the available transmit timestamp modes, afterwards.
+
2529 *
+
2530 * @return
+
2531 * Status | Description
+
2532 * ---------------------------------------------- | -----------------------------------------------------------
+
2533 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2534 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2535 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2536 */
+
2537_BRAWCAP_API_FUNC(brawcap_status_t)
+
2538brawcap_tx_timestamp_capabilities(brawcap_handle_t* const pHandle,
+
2539 brawcap_timestamp_capabilities_t* const pCapabilities);
+
2540
+
2541/**
+
2542 * @brief Configures the used transmit time stamping mode for the specified handle.
+
2543 *
+
2544 * @note Only available timestamp modes are accepted. It is recommended to check if a timestamp mode is supported
+
2545 * before setting it. To check if a timestamp mode is available use @ref brawcap_tx_timestamp_capabilities.
+
2546 *
+
2547 * @param[in] pHandle bRAWcap handle to be configured.
+
2548 *
+
2549 * @param[in] mode The transmit timestamp mode to be configured.
+
2550 *
+
2551 * @return
+
2552 * Status | Description
+
2553 * ---------------------------------------------- | -----------------------------------------------------------
+
2554 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2555 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2556 * @ref BRAWCAP_STATUS_ERROR_NOT_AVAILABLE | Specified timestamp mode not available.
+
2557 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2558 */
+
2559_BRAWCAP_API_FUNC(brawcap_status_t)
+
2560brawcap_tx_timestamp_mode_set(brawcap_handle_t* const pHandle, const brawcap_timestamp_mode_t mode);
+
2561
+
2562/**
+
2563 * @brief Reads out the currently configured transmit time stamping mode for the specified handle.
+
2564 *
+
2565 * @param[in] pHandle bRAWcap handle to read from.
+
2566 *
+
2567 * @param[out] pMode Will contain the currently used transmit time stamping mode, afterwards.
+
2568 *
+
2569 * @return
+
2570 * Status | Description
+
2571 * ---------------------------------------------- | -----------------------------------------------------------
+
2572 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2573 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2574 */
+
2575_BRAWCAP_API_FUNC(brawcap_status_t)
+
2576brawcap_tx_timestamp_mode_get(brawcap_handle_t* const pHandle, brawcap_timestamp_mode_t* const pMode);
+
2577
+
2578/**@}*/
+
2579#endif
+
2580
+
2581/************************************************* STATS **************************************************************/
+
2582#if 1
+
2583/**
+
2584 * @addtogroup brawcap_stats
+
2585 * @{
+
2586 */
+
2587
+
2588/**
+
2589 * @brief Reads out the available receive statistic counters for the specified handle.
+
2590 *
+
2591 * @param[in] pHandle bRAWcap handle to read from.
+
2592 *
+
2593 * @param[inout] pStats Will contain the current receive statistic counters, afterwards.
+
2594 * The header of the statistic struct hast to be filled by the caller, before calling this function.
+
2595 * If it is not filled or contains invalid data, the function will fail and return a error.
+
2596 *
+
2597 * @return
+
2598 * Status | Description
+
2599 * ---------------------------------------------- | -----------------------------------------------------------
+
2600 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2601 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2602 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The header was invalid (type or revision).
+
2603 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The specified size in the header was invalid.
+
2604 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2605 */
+
2606_BRAWCAP_API_FUNC(brawcap_status_t)
+
2607brawcap_stats_rx(brawcap_handle_t* const pHandle, brawcap_stats_rx_t* const pStats);
+
2608
+
2609/**
+
2610 * @brief Reads out the available transmit statistic counters for the specified handle.
+
2611 *
+
2612 * @param[in] pHandle bRAWcap handle to read from.
+
2613 *
+
2614 * @param[inout] pStats Will contain the current transmit statistic counters, afterwards.
+
2615 * The header of the statistic struct hast to be filled by the caller, before calling this function.
+
2616 * If it is not filled or contains invalid data, the function will fail and return a error.
+
2617 *
+
2618 * @return
+
2619 * Status | Description
+
2620 * ---------------------------------------------- | -----------------------------------------------------------
+
2621 * @ref BRAWCAP_STATUS_SUCCESS | Success.
+
2622 * @ref BRAWCAP_STATUS_ERROR_INVALID_POINTER | At least one of the given pointer parameters was invalid.
+
2623 * @ref BRAWCAP_STATUS_ERROR_INVALID_PARAM | The header was invalid (type or revision).
+
2624 * @ref BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE | The specified size in the header was invalid.
+
2625 * @ref BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED | Communicating with bRAWcap driver failed.
+
2626 */
+
2627_BRAWCAP_API_FUNC(brawcap_status_t)
+
2628brawcap_stats_tx(brawcap_handle_t* const pHandle, brawcap_stats_tx_t* const pStats);
+
2629
+
2630/**@}*/
+
2631#endif
+
2632
+
2633#if defined(__cplusplus)
+
2634}
+
2635#endif //(__cplusplus)
+
2636
+
2637#endif //BRAWCAP_H
+
brawcap_types_um.h
bRAWcap API - User mode types.
+
brawcap_queue_size_t
UINT32 brawcap_queue_size_t
The number of packets which can be (temporary) buffered by the bRAWcap driver queue.
Definition: brawcap_types_shared.h:94
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
brawcap_version_t
bRAWcap version.
Definition: brawcap_types_shared.h:426
+
brawcap_version_api
brawcap_status_t brawcap_version_api(brawcap_version_t *const pVersion)
Returns loaded bRAWcap library version.
+
brawcap_version_driver
brawcap_status_t brawcap_version_driver(brawcap_handle_t *const pHandle, brawcap_version_t *const pVersion)
Reads current version of loaded bRAWcap driver.
+
brawcap_timestamp_capabilities_t
UINT32 brawcap_timestamp_capabilities_t
Type used for indicating the supported timestamp modes.
Definition: brawcap_types_shared.h:524
+
brawcap_timestamp_value_us_get
brawcap_status_t brawcap_timestamp_value_us_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMicroseconds)
Reads out the timestamp value in seconds and microseconds.
+
brawcap_timestamp_value_ms_get
brawcap_status_t brawcap_timestamp_value_ms_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMilliseconds)
Reads out the timestamp value in seconds and milliseconds.
+
brawcap_timestamp_resolution_ns_get
brawcap_status_t brawcap_timestamp_resolution_ns_get(brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_resolution_ns_t *const pResolution_ns)
Reads out the timestamp resolution of the specified timestamp.
+
brawcap_timestamp_value_us_set
brawcap_status_t brawcap_timestamp_value_us_set(brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 microseconds)
Sets the timestamp value in seconds and microseconds.
+
brawcap_timestamp_t
struct _brawcap_timestamp brawcap_timestamp_t
bRAWcap timestamp object.
Definition: brawcap_types_shared.h:612
+
brawcap_timestamp_value_ns_get
brawcap_status_t brawcap_timestamp_value_ns_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pNanoseconds)
Reads out the timestamp value in seconds and nanoseconds.
+
brawcap_timestamp_resolution_ns_t
UINT32 brawcap_timestamp_resolution_ns_t
Represents the timestamp resolution in nanoseconds.
Definition: brawcap_types_shared.h:533
+
brawcap_timestamp_mode_t
brawcap_timestamp_mode_t
List of different timestamp modes.
Definition: brawcap_types_shared.h:574
+
brawcap_timestamp_value_ms_set
brawcap_status_t brawcap_timestamp_value_ms_set(brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 milliseconds)
Sets the timestamp value in seconds and milliseconds.
+
brawcap_timestamp_mode_get
brawcap_status_t brawcap_timestamp_mode_get(brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_mode_t *const pMode)
Reads out the mode of the specified timestamp.
+
brawcap_timestamp_value_ns_set
brawcap_status_t brawcap_timestamp_value_ns_set(brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 nanoseconds)
Sets the timestamp value in seconds and nanoseconds.
+
brawcap_packet_size_t
UINT16 brawcap_packet_size_t
Type for handling the number of payload bytes per packet.
Definition: brawcap_types_shared.h:670
+
brawcap_packet_payload_set
brawcap_status_t brawcap_packet_payload_set(brawcap_packet_t *const pPacket, const char *const pPayload, const brawcap_packet_size_t length)
Sets the packet payload of the specified packet.
+
brawcap_packet_payload_size_get
brawcap_status_t brawcap_packet_payload_size_get(brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLength)
Reads out the captured payload byte size of the specified packet. This indicates the total byte size ...
+
brawcap_packet_create
brawcap_status_t brawcap_packet_create(brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
Creates a new packet.
+
brawcap_packet_t
struct _brawcap_packet brawcap_packet_t
bRAWcap packet object.
Definition: brawcap_types_shared.h:679
+
brawcap_packet_payload_max_size_get
brawcap_status_t brawcap_packet_payload_max_size_get(brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pMaxPayloadSize)
Reads out the max supported payload byte size of the specified packet. This value was set during pack...
+
brawcap_packet_payload_get
brawcap_status_t brawcap_packet_payload_get(brawcap_packet_t *const pPacket, const char **const pPayload, brawcap_packet_size_t *const pLength)
Reads out the payload of the specified packet.
+
brawcap_packet_length_on_wire_get
brawcap_status_t brawcap_packet_length_on_wire_get(brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLengthOnWire)
Reads out the length on wire of the specified packet. This value is especially useful for received pa...
+
brawcap_packet_status_get
brawcap_status_t brawcap_packet_status_get(brawcap_packet_t *const pPacket, brawcap_status_t *const pStatus)
Reads out the status for the specified packet. The status will be set updated during reception/transm...
+
brawcap_packet_timestamp_get
brawcap_status_t brawcap_packet_timestamp_get(brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
Reads out the timestamp object for the specified packet.
+
brawcap_packet_free
brawcap_status_t brawcap_packet_free(brawcap_packet_t *pPacket)
Frees the specified packet. When this function is called the specified packet becomes invalid and it´...
+
brawcap_buffer_t
struct _brawcap_buffer brawcap_buffer_t
bRAWcap packet buffer object.
Definition: brawcap_types_shared.h:742
+
brawcap_buffer_back
brawcap_status_t brawcap_buffer_back(brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
Reads out the last buffered packet of the specified packet buffer.
+
brawcap_buffer_front
brawcap_status_t brawcap_buffer_front(brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
Reads out the first buffered packet of the specified packet buffer.
+
brawcap_buffer_add_back
brawcap_status_t brawcap_buffer_add_back(brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
Adds the specified packet at the end of the specified packet buffer.
+
brawcap_buffer_free
brawcap_status_t brawcap_buffer_free(brawcap_buffer_t *pBuffer)
Frees the specified packet buffer. When this function is called the specified packet buffer becomes i...
+
brawcap_buffer_packet_count_t
UINT32 brawcap_buffer_packet_count_t
Type for handling the number of packets which can be stored in a packet buffer.
Definition: brawcap_types_shared.h:734
+
brawcap_buffer_clear
brawcap_status_t brawcap_buffer_clear(brawcap_buffer_t *const pBuffer)
Clears the specified packet buffer.
+
brawcap_buffer_add_front
brawcap_status_t brawcap_buffer_add_front(brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
Adds the specified packet at the front of the specified packet buffer.
+
brawcap_buffer_at_index
brawcap_status_t brawcap_buffer_at_index(brawcap_buffer_t *const pBuffer, const brawcap_buffer_packet_count_t index, brawcap_packet_t **const pPacket)
Reads out a buffered packet at the index of the specified packet buffer.
+
brawcap_buffer_capacity
brawcap_status_t brawcap_buffer_capacity(brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCapacity)
Reads out the total number of packets which can be buffered by the specified packet buffer....
+
brawcap_buffer_count
brawcap_status_t brawcap_buffer_count(brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCount)
Reads out the number of currently buffered packets in the specified packet buffer.
+
brawcap_buffer_create
brawcap_status_t brawcap_buffer_create(brawcap_buffer_t **const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize, const brawcap_buffer_packet_count_t numPackets)
Creates a new packet buffer.
+
brawcap_buffer_add_at_index
brawcap_status_t brawcap_buffer_add_at_index(brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket, const brawcap_buffer_packet_count_t index)
Inserts the specified packet at index/position into the specified packet buffer.
+
brawcap_buffer_iterator_free
brawcap_status_t brawcap_buffer_iterator_free(brawcap_buffer_iterator_t *const pIterator)
Frees the specified iterator. When this function is called the specified iterator becomes invalid and...
+
brawcap_buffer_iterator_t
struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
bRAWcap packet buffer iterator object.
Definition: brawcap_types_shared.h:770
+
brawcap_buffer_iterator_eval
brawcap_packet_t * brawcap_buffer_iterator_eval(brawcap_buffer_iterator_t *const pIterator)
Returns the buffered packet for the specified iterator.
+
brawcap_buffer_iterator_prev
brawcap_status_t brawcap_buffer_iterator_prev(brawcap_buffer_iterator_t *const pIterator)
Decreases the iterator to the previous buffered packet.
+
brawcap_buffer_iterator_create
brawcap_status_t brawcap_buffer_iterator_create(brawcap_buffer_iterator_t **const pIterator, brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t startPosition)
Creates a new iterator for the specified buffer.
+
brawcap_buffer_iterator_next
brawcap_status_t brawcap_buffer_iterator_next(brawcap_buffer_iterator_t *const pIterator)
Increments the iterator to the next buffered packet.
+
brawcap_adapter_ipv4_t
IPv4 address.
Definition: brawcap_types_um.h:263
+
brawcap_adapter_ipv6_t
IPv6 address.
Definition: brawcap_types_um.h:273
+
brawcap_adapter_mac_by_handle
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_adapter_notify_unregister
brawcap_status_t brawcap_adapter_notify_unregister()
Unregisters the calling process from receiving adapter change notifications.
+
brawcap_adapter_name_by_handle
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_adapter_mtu
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_adapter_list_at
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_adapter_speed_rx
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_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)
Reads out the currently set friendly name of the specified adapter.
+
brawcap_adapter_list_count
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_adapter_ipv4
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_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)
Registers the specified handle for receiving adapter change notifications.
+
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)
Reads out the current transmit speed of the specified adapter.
+
brawcap_adapter_friendly_name
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_adapter_description
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_adapter_ipv6_by_handle
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_adapter_notify_handle_callback_t
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 th...
Definition: brawcap_types_um.h:418
+
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)
Reads out the current receive speed of the specified adapter.
+
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)
Reads out the current operation state of the specified adapter.
+
brawcap_adapter_mac_t
UINT8 brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH]
Fixed size array describing a MAC address.
Definition: brawcap_types_um.h:249
+
brawcap_adapter_connection_state_t
brawcap_adapter_connection_state_t
List of adapter connection states. Values indicating the current adapter connection state (uplink/cab...
Definition: brawcap_types_um.h:306
+
brawcap_adapter_mtu_by_handle
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.
+
brawcap_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_connection
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_adapter_ipv6
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_adapter_speed_t
brawcap_adapter_speed_t
List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed.
Definition: brawcap_types_um.h:287
+
brawcap_adapter_list_update
brawcap_status_t brawcap_adapter_list_update()
Updates the list of supported adapters. This function searches the current machine for supported adap...
+
brawcap_adapter_ipv4_by_handle
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_adapter_notify_callback_t
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 su...
Definition: brawcap_types_um.h:400
+
brawcap_adapter_mac
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_adapter_connection_by_handle
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_adapter_description_by_handle
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_adapter_operation_state_t
brawcap_adapter_operation_state_t
List of adapter operation states. Values indicating the current adapter operation state (adapter driv...
Definition: brawcap_types_um.h:317
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
brawcap_adapter_notify_register
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_adapter_speed_tx
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_adapter_mtu_t
UINT64 brawcap_adapter_mtu_t
Type for handling the adapter maximum transmission unit (MTU).
Definition: brawcap_types_um.h:337
+
brawcap_adapter_notify_handle_unregister
brawcap_status_t brawcap_adapter_notify_handle_unregister(brawcap_handle_t *const pHandle)
Unregisters the specified handle from receiving adapter change notifications.
+
brawcap_adapter_operation
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_rx_min_packets_set
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_rx_packet
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_rx_direction_get
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_rx_buffer_detach
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_rx_timeout_get
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_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)
Starts the internal receive loop.
+
brawcap_rx_vlan_tagging_get
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_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)
Sets the driver queue size (in number of packets) for the specified handle.
+
brawcap_rx_timeout_set
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_rx_vlan_tagging_set
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_rx_timestamp_capabilities
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_rx_direction_set
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_rx_promiscuous_mode_set
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_rx_stop
brawcap_status_t brawcap_rx_stop(brawcap_handle_t *const pHandle)
Stops the internal receive loop.
+
brawcap_rx_promiscuous_mode_get
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_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)
Reads out the currently configured driver receive queue size for the specified handle.
+
brawcap_rx_timestamp_mode_set
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_rx_buffer_attach
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_rx_filter_set
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_rx_min_packets_get
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_rx_min_packets_t
UINT32 brawcap_rx_min_packets_t
Type for handling the minimum amount of packets to copy before a bRAWcap receive will return....
Definition: brawcap_types_shared.h:1047
+
brawcap_rx_filter_get
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_rx_timestamp_mode_get
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_rx_timeout_t
UINT16 brawcap_rx_timeout_t
Type for handling receive timeouts in number of milliseconds. The timeout specifies the maximum block...
Definition: brawcap_types_shared.h:1037
+
brawcap_rx_callback_t
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 braw...
Definition: brawcap_types_um.h:471
+
brawcap_rx_direction_t
brawcap_rx_direction_t
List of supported receive directions.
Definition: brawcap_types_shared.h:1074
+
brawcap_filter_mask_array_t
UINT8 brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a filter byte mask.
Definition: brawcap_types_shared.h:900
+
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)
Sets the bytes to capture of the specified filter.
+
brawcap_filter_create
brawcap_status_t brawcap_filter_create(brawcap_filter_t **const pFilter, const brawcap_filter_type_t type)
Creates a new filter.
+
brawcap_filter_t
struct _brawcap_filter brawcap_filter_t
bRAWcap filter object.
Definition: brawcap_types_shared.h:973
+
brawcap_filter_deactivate
brawcap_status_t brawcap_filter_deactivate(brawcap_filter_t *const pFilter)
Sets the specified filter to inactive.
+
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)
Reads out the configured bytes to capture of the specified filter.
+
brawcap_filter_is_activated
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_filter_type_t
brawcap_filter_type_t
List of filter types.
Definition: brawcap_types_shared.h:927
+
brawcap_filter_ignore_bits_array_t
UINT8 brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a byte wise bitfield.
Definition: brawcap_types_shared.h:912
+
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)
Sets the filter parameters for the specified filter.
+
brawcap_filter_indicate_get
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.
+
brawcap_filter_type_get
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_filter_free
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 me...
+
brawcap_filter_byte_length_t
brawcap_packet_size_t brawcap_filter_byte_length_t
Type for specifying the byte filter length.
Definition: brawcap_types_shared.h:917
+
brawcap_filter_indicate_set
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_filter_activate
brawcap_status_t brawcap_filter_activate(brawcap_filter_t *const pFilter)
Sets the specified filter to active.
+
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)
Reads out the filter mask parameters for the specified filter.
+
brawcap_tx_driver_queue_size_get
brawcap_status_t brawcap_tx_driver_queue_size_get(brawcap_handle_t *const pHandle, brawcap_queue_size_t *const pSize)
Reads out the currently configured driver transmit queue size for the specified handle.
+
brawcap_tx_timestamp_capabilities
brawcap_status_t brawcap_tx_timestamp_capabilities(brawcap_handle_t *const pHandle, brawcap_timestamp_capabilities_t *const pCapabilities)
Reads out the available transmit timestamp modes for the specified handle.
+
brawcap_tx_packet
brawcap_status_t brawcap_tx_packet(brawcap_handle_t *const pHandle, brawcap_packet_t *const pPacket)
Transmits a single packet on the specified handle.
+
brawcap_tx_timestamp_mode_set
brawcap_status_t brawcap_tx_timestamp_mode_set(brawcap_handle_t *const pHandle, const brawcap_timestamp_mode_t mode)
Configures the used transmit time stamping mode for the specified handle.
+
brawcap_tx_timestamp_mode_get
brawcap_status_t brawcap_tx_timestamp_mode_get(brawcap_handle_t *const pHandle, brawcap_timestamp_mode_t *const pMode)
Reads out the currently configured transmit time stamping mode for the specified handle.
+
brawcap_tx_stop
brawcap_status_t brawcap_tx_stop(brawcap_handle_t *const pHandle)
Stops the internal transmit loop.
+
brawcap_tx_start
brawcap_status_t brawcap_tx_start(brawcap_handle_t *const pHandle, brawcap_tx_callback_t const callback, void *pUser)
Starts the internal transmit loop.
+
brawcap_tx_callback_t
void(* brawcap_tx_callback_t)(brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)
Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has ...
Definition: brawcap_types_um.h:501
+
brawcap_tx_driver_queue_size_set
brawcap_status_t brawcap_tx_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_tx_buffer_send
brawcap_status_t brawcap_tx_buffer_send(brawcap_handle_t *const pHandle, brawcap_buffer_t *const pBuffer, const BOOLEAN synchronized)
Pushes the specified buffer to the specified handle transmit queue.
+
brawcap_stats_rx_t
The bRAWcap receive statistics.
Definition: brawcap_types_shared.h:1303
+
brawcap_stats_tx_t
The bRAWcap transmit statistics.
Definition: brawcap_types_shared.h:1421
+
brawcap_stats_rx
brawcap_status_t brawcap_stats_rx(brawcap_handle_t *const pHandle, brawcap_stats_rx_t *const pStats)
Reads out the available receive statistic counters for the specified handle.
+
brawcap_stats_tx
brawcap_status_t brawcap_stats_tx(brawcap_handle_t *const pHandle, brawcap_stats_tx_t *const pStats)
Reads out the available transmit statistic counters for the specified handle.
+
_BRAWCAP_API_FUNC
#define _BRAWCAP_API_FUNC(returnType)
Dynamic/automatic function import for loading/including.
Definition: brawcap_types_um.h:45
+
brawcap_log_level_get
brawcap_status_t brawcap_log_level_get(const brawcap_log_type_t type, brawcap_log_level_t *const pLevel)
Reads the level(s) for the given log type.
+
brawcap_log_type_t
brawcap_log_type_t
List of bRAWcap log types.
Definition: brawcap_types_um.h:129
+
brawcap_log_levels_set
brawcap_status_t brawcap_log_levels_set(const UINT32 type, const UINT32 level, const char *pKey)
Sets the current log levels for the given log types to the specified log levels.
+
brawcap_log_level_set
brawcap_status_t brawcap_log_level_set(const brawcap_log_type_t type, const brawcap_log_level_t level, const char *pKey)
Sets the current log level for the given log type to the specified log level.
+
brawcap_log_level_t
brawcap_log_level_t
List of bRAWcap log levels.
Definition: brawcap_types_um.h:77
+
+ + + + + + diff --git a/sdk/c/doc/html/a00038.html b/sdk/c/doc/html/a00038.html new file mode 100644 index 0000000..1f113b6 --- /dev/null +++ b/sdk/c/doc/html/a00038.html @@ -0,0 +1,495 @@ + + + + + + + + +bRAWcap: brawcap_types_shared.h File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
+Data Structures | +Macros | +Typedefs | +Enumerations
+
brawcap_types_shared.h File Reference
+
+
+ +

bRAWcap API - Shared types. +More...

+ +

Go to the source code of this file.

+ + + + + + + + + + + + + + + + + + + + + + + +

+Data Structures

struct  brawcap_version_fragments_t
 Struct containing the separated version parts. More...
 
union  brawcap_version_t
 bRAWcap version. More...
 
struct  brawcap_bpf_insn_t
 A single BPF pseudo-instruction. More...
 
struct  brawcap_bpf_program_t
 A BPF pseudo-assembly program. More...
 
struct  brawcap_stats_header_t
 Header describing given bRAWcap stats structure. More...
 
struct  brawcap_stats_rx_t
 The bRAWcap receive statistics. More...
 
struct  brawcap_stats_tx_t
 The bRAWcap transmit statistics. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define BRAWCAP_HANDLES_PER_ADAPTER_MAX   5
 Specifies the maximum supported bRAWcap handles per adapter.
 
+#define BRAWCAP_SUCCESS(status)   (status == 0)
 Checks if the returned status indicates a success with no additional info.
 
+#define BRAWCAP_ERROR(status)   (status < 0)
 Checks if the returned status is a error.
 
+#define BRAWCAP_WARNING(status)   (status > 0 && status < 2000)
 Checks if the returned status is a warning.
 
+#define BRAWCAP_INFO(status)   (status >= 2000 && status < 4000)
 Checks if the returned status is a info.
 
+#define BRAWCAP_TIMESTAMP_MODE_SYSL_AVAILABLE(_capabilities)   (_capabilities & 0x01)
 Checks if timestamp mode system low precision is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_SYSH_AVAILABLE(_capabilities)   (_capabilities & 0x02)
 Checks if timestamp mode system high precision is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_SW_AVAILABLE(_capabilities)   (_capabilities & 0x04)
 Checks if timestamp mode software is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYS_AVAILABLE(_capabilities)   (_capabilities & 0x08)
 Checks if timestamp mode adapter system is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SW_AVAILABLE(_capabilities)   (_capabilities & 0x10)
 Checks if timestamp mode adapter software is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_HW_AVAILABLE(_capabilities)   (_capabilities & 0x20)
 Checks if timestamp mode adapter hardware is supported.
 
#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN   0
 If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_SEC   1000000000
 Number of nanoseconds per second.
 
+#define BRAWCAP_TIMESTAMP_US_PER_SEC   1000000
 Number of microseconds per second.
 
+#define BRAWCAP_TIMESTAMP_MS_PER_SEC   1000
 Number of milliseconds per second.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_US   1000
 Number of nanoseconds per microsecond.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_MS   1000000
 Number of nanoseconds per millisecond.
 
#define BRAWCAP_PACKET_SIZE_MAX   9018
 The maximum supported (byte) size for a single packet payload.
 
#define BRAWCAP_PACKET_SIZE_MIN   14
 The minimum required (byte) size for a single packet payload.
 
+#define BRAWCAP_BUFFER_PACKETS_MAX   100000
 The maximum amount of packets, which can be stored in a packet buffer.
 
+#define BRAWCAP_BUFFER_PACKETS_MIN   1
 The minimum amount of packets, which a packet buffer must have.
 
+#define BRAWCAP_FILTER_BYTE_MAX_LENGTH   64U
 The maximum supported filter byte mask length in bytes.
 
#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_TX_DRIVER_QUEUE_SIZE_DEFAULT   512
 Default size in number of packets for driver transmit queues.
 
+#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MIN   256
 Minimum size in number of packets supported for driver transmit queues.
 
+#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX   4096
 Maximum size in number of packets supported for driver transmit queues.
 
+#define BRAWCAP_TX_TIMESTAMP_MODE_DEFAULT   BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
 Default timestamp mode for transmitted packets.
 
+#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterReceivedPacketsTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterReceivedBytesTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterDroppedPacketsTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_tx_t::adapterCompletedPacketsTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID)
 Indicates if the brawcap_stats_tx_t::adapterCompletedBytesTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID )
 Indicates if the brawcap_stats_tx_t::adapterCanceledPacketsTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_SIZEOF_REVISION_1   _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_rx_t, handleDroppedPacketsToLong)
 Returns the size of receive statistics revision 1.
 
+#define BRAWCAP_STATS_TX_SIZEOF_REVISION_1   _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_tx_t, handleCompletedBytesTotal)
 Returns the size of transmit statistics revision 1.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Typedefs

typedef UINT32 brawcap_queue_size_t
 The number of packets which can be (temporary) buffered by the bRAWcap driver queue.
 
typedef UINT32 brawcap_timestamp_capabilities_t
 Type used for indicating the supported timestamp modes.
 
typedef UINT32 brawcap_timestamp_resolution_ns_t
 Represents the timestamp resolution in nanoseconds.
 
typedef struct _brawcap_timestamp brawcap_timestamp_t
 bRAWcap timestamp object.
 
typedef UINT16 brawcap_packet_size_t
 Type for handling the number of payload bytes per packet.
 
typedef struct _brawcap_packet brawcap_packet_t
 bRAWcap packet object.
 
typedef UINT32 brawcap_buffer_packet_count_t
 Type for handling the number of packets which can be stored in a packet buffer.
 
typedef struct _brawcap_buffer brawcap_buffer_t
 bRAWcap packet buffer object.
 
typedef struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
 bRAWcap packet buffer iterator object.
 
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.
 
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.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + +

+Enumerations

enum  brawcap_status_t {
+  BRAWCAP_STATUS_SUCCESS = 0 +,
+  BRAWCAP_STATUS_ERROR_FAILED = -1 +,
+  BRAWCAP_STATUS_ERROR_NOT_AVAILABLE = -2 +,
+  BRAWCAP_STATUS_ERROR_INVALID_POINTER = -3 +,
+  BRAWCAP_STATUS_ERROR_INVALID_PARAM = -4 +,
+  BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE = -5 +,
+  BRAWCAP_STATUS_ERROR_NOT_FOUND = -6 +,
+  BRAWCAP_STATUS_ERROR_IN_USE = -7 +,
+  BRAWCAP_STATUS_ERROR_BEYOND_MTU = -8 +,
+  BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED = -9 +,
+  BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE = -10 +,
+  BRAWCAP_STATUS_ERROR_OVERRUN = -11 +,
+  BRAWCAP_STATUS_WARNING_DEMO_MODE = 1 +,
+  BRAWCAP_STATUS_WARNING_PENDING = 2 +,
+  BRAWCAP_STATUS_WARNING_LIMIT_REACHED = 3 +,
+  BRAWCAP_STATUS_WARNING_CANCELED = 4 +,
+  BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED = 5 +,
+  BRAWCAP_STATUS_WARNING_NO_UPLINK = 6 +,
+  BRAWCAP_STATUS_INFO_NOT_RUNNING = 2000 +,
+  BRAWCAP_STATUS_INFO_NOT_ATTACHED = 2001 +,
+  BRAWCAP_STATUS_INFO_NOT_REGISTERED = 2002 +,
+  BRAWCAP_STATUS_INFO_ALREADY_REGISTERED = 2003 +,
+  BRAWCAP_STATUS_INFO_NO_DATA = 2004 +,
+  BRAWCAP_STATUS_INFO_TIMEOUT = 2005 +
+ }
 bRAWcap status/return codes. More...
 
enum  brawcap_timestamp_mode_t {
+  BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP = 0x00 +,
+  BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC = 0x01 +,
+  BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC = 0x02 +,
+  BRAWCAP_TIMESTAMP_MODE_SOFTWARE = 0x04 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM = 0x08 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE = 0x10 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE = 0x20 +
+ }
 List of different timestamp modes. More...
 
enum  brawcap_filter_type_t {
+  BRAWCAP_FILTER_TYPE_BYTE_MASK = 0 +,
+  BRAWCAP_FILTER_TYPE_BPF = 1 +
+ }
 List of filter types. More...
 
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...
 
enum  brawcap_stats_type_t {
+  BRAWCAP_STATS_TYPE_RX = 1 +,
+  BRAWCAP_STATS_TYPE_TX = 2 +
+ }
 List of all available statistic types. More...
 
enum  brawcap_stats_rx_revision_t { BRAWCAP_STATS_RX_REVISION_1 = 1 + }
 List of all available receive statistic revisions. More...
 
enum  brawcap_stats_tx_revision_t { BRAWCAP_STATS_TX_REVISION_1 = 1 + }
 List of all available transmit statistic revisions. More...
 
+

Detailed Description

+

bRAWcap API - Shared types.

+

The file includes all (data)types and defines used for bRAWcap (kernel and user space).

+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00038_source.html b/sdk/c/doc/html/a00038_source.html new file mode 100644 index 0000000..6ae1f84 --- /dev/null +++ b/sdk/c/doc/html/a00038_source.html @@ -0,0 +1,1768 @@ + + + + + + + + +bRAWcap: brawcap_types_shared.h Source File + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
brawcap_types_shared.h
+
+
+Go to the documentation of this file.
1/**
+
2 * @file brawcap_types_shared.h
+
3 *
+
4 * @brief bRAWcap API - Shared types.
+
5 *
+
6 * The file includes all (data)types and defines used for bRAWcap (kernel and user space).
+
7 *
+
8 * @copyright
+
9 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
10 *
+
11 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
12 *
+
13 * Redistribution in source or any other form, with or without modification, is not permitted.
+
14 *
+
15 *
+
16 * You may use this code under the according license terms of b-plus.
+
17 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
18 */
+
19#ifndef BRAWCAP_TYPES_SHARED_H
+
20#define BRAWCAP_TYPES_SHARED_H
+
21
+
22// Include required Windows headers for datatypes.
+
23#if 1
+
24#if !defined(_WIN64)
+
25 #error Architecture not defined (please define "_WIN64").
+
26#else
+
27 #ifdef WINNT
+
28 #include <sdkddkver.h>
+
29 #include <basetsd.h>
+
30 #include <minwindef.h>
+
31 #else
+
32 #define WIN32_LEAN_AND_MEAN
+
33 #include <Windows.h>
+
34 #endif
+
35#endif
+
36#endif
+
37
+
38// Define required BPF structs if the BPF header is not included.
+
39#if 1
+
40#ifndef BRAWCAP_BPF_INCLUDED
+
41 #define _BRAWCAP_DEFINE_BPF_STRUCTS_INTERNAL
+
42 #ifndef _BRAWCAP_EXPORT
+
43 #pragma message("<bRAWcap> Please define 'BRAWCAP_BPF_INCLUDED' if you get any redefinition errors on because of BPF.")
+
44 #endif
+
45#endif
+
46#endif
+
47
+
48/************************************************ GENERIC ************************************************************/
+
49#if 1
+
50/**
+
51 * @example{lineno} 03_generic_handle_opener.c
+
52 *
+
53 * This example shows how to open and close bRAWcap handles to each available adapter on the machine.
+
54 * If any unexpected status is returned, it will close all handles and print the unexpected status to console.
+
55 * Therefore @ref brawcap_last_status is used.
+
56 */
+
57
+
58/**
+
59 * @defgroup brawcap_generics Generics
+
60 * @brief Contains generic types and functions of bRAWcap.
+
61 *
+
62 * Everything in here is not part of any specific module, instead those types and functions are relevant for many
+
63 * other modules. It contains for example functions to @ref brawcap_open "open/create" and @ref brawcap_close "close"
+
64 * a @ref brawcap_handle_t "bRAWcap handle".
+
65 *
+
66 * List of examples:
+
67 * 1. @ref 03_generic_handle_opener.c "Handle Opener"
+
68 * @{
+
69 */
+
70
+
71/**
+
72 * @brief Specifies the maximum supported bRAWcap handles per adapter.
+
73 *
+
74 * @attention If this number of handles is reached (for a specific adapter) each additional @ref brawcap_open "open"
+
75 * will fail.
+
76 */
+
77#define BRAWCAP_HANDLES_PER_ADAPTER_MAX 5
+
78
+
79/**
+
80 * @brief The number of packets which can be (temporary) buffered by the bRAWcap driver queue.
+
81 *
+
82 * The total number of packets which can be buffered by the driver queue is limited to:
+
83 * - receive: @ref BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX
+
84 * - transmit: @ref BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX
+
85 *
+
86 * @note Each bRAWcap handle has it´s own driver queue. Therefore the total memory consumption by the driver
+
87 * depends on the number of adapters and handles to each adapter, and also on how large the driver queue is specified.
+
88 *
+
89 * @attention Larger driver queues can minimize packet drops due to more resources. Especially in cases where the user
+
90 * application requires longer than expected to pick up (call receive) on the handle. But it has to be said that
+
91 * large queues shouldn´t be required in optimized configurations and that they can consume a lot of memory if they
+
92 * are not configured with care.
+
93 */
+
94typedef UINT32 brawcap_queue_size_t;
+
95
+
96/**@}*/
+
97#endif
+
98
+
99/************************************************** STATUS ***********************************************************/
+
100#if 1
+
101/**
+
102 * @defgroup brawcap_status Status
+
103 * @brief Contains all status/return codes of bRAWcap.
+
104 *
+
105 * If a bRAWcap function completed successfully and with no additional information it will indicate
+
106 * @ref BRAWCAP_STATUS_SUCCESS.
+
107 *
+
108 * If an error occurs the status code will always be negative.
+
109 *
+
110 * A status which indicates a warning, will always have a positive value (range 1 to 1999).
+
111 *
+
112 * While a status with additional information is always represented by high positive value (range 2000 to 4000).
+
113 *
+
114 * It is also possible to request the last "non successful" status for the current thread again with
+
115 * @ref brawcap_last_status. This function works similar to the one defined by the Windows API (GetLastError()).
+
116 * @{
+
117 */
+
118
+
119/**
+
120 * @brief Checks if the returned status indicates a success with no additional info.
+
121 */
+
122#define BRAWCAP_SUCCESS(status) (status == 0)
+
123
+
124/**
+
125 * @brief Checks if the returned status is a error.
+
126 */
+
127#define BRAWCAP_ERROR(status) (status < 0)
+
128
+
129/**
+
130 * @brief Checks if the returned status is a warning.
+
131 */
+
132#define BRAWCAP_WARNING(status) (status > 0 && status < 2000)
+
133
+
134/**
+
135 * @brief Checks if the returned status is a info.
+
136 */
+
137#define BRAWCAP_INFO(status) (status >= 2000 && status < 4000)
+
138
+
139/**
+
140 * @brief bRAWcap status/return codes.
+
141 *
+
142 * Each status is defined with a descriptive name, which indicates it´s reason.
+
143 * To check for the status code type use one of the defined macros:
+
144 * - Status indicates @ref BRAWCAP_SUCCESS "success"
+
145 * - Status indicates @ref BRAWCAP_ERROR "error"
+
146 * - Status indicates @ref BRAWCAP_WARNING "warning"
+
147 * - Status indicates @ref BRAWCAP_INFO "info"
+
148 */
+
149typedef enum _brawcap_status
+
150{
+
151 // SUCCESS (== 0)
+
152 BRAWCAP_STATUS_SUCCESS = 0, /*!< Executed successfully, with no additional information. */
+
153
+
154 // ERROR (< 0)
+
155 #if 1
+
156 /**
+
157 * @brief Detected a - not further specified - failure.
+
158 *
+
159 * This shouldn´t happen at all and mostly indicates a issue in OS abstraction.
+
160 * If it happens in a specific situation, please check the system resources (CPU load, memory usage...).
+
161 * If the issue can not be located, feel free to contact our support.
+
162 */
+
163 BRAWCAP_STATUS_ERROR_FAILED = -1,
+
164 /**
+
165 * @brief Function is not available.
+
166 *
+
167 * This may be returned due to several conditions:
+
168 * - bRAWcap license does not include the requested feature.
+
169 * - The current machine does not support the feature.
+
170 * - Higher API registration privilege is required.
+
171 */
+
172 BRAWCAP_STATUS_ERROR_NOT_AVAILABLE = -2,
+
173 /**
+
174 * @brief At least one specified pointer parameter was invalid.
+
175 *
+
176 * This is a caller issue.
+
177 * Please check the provided pointers to solve this issue.
+
178 */
+
179 BRAWCAP_STATUS_ERROR_INVALID_POINTER = -3,
+
180 /**
+
181 * @brief At least one parameter content is invalid.
+
182 *
+
183 * This is a caller issue.
+
184 * Please check the provided parameters and their contents to solve this issue.
+
185 */
+
186 BRAWCAP_STATUS_ERROR_INVALID_PARAM = -4,
+
187 /**
+
188 * @brief At least one parameter is out of bounds.
+
189 *
+
190 * This is a caller issue.
+
191 * Please check if the provided parameters fit to the given parameter limitations.
+
192 */
+
193 BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE = -5,
+
194 /**
+
195 * @brief Given parameter not found.
+
196 *
+
197 * This is in general a caller issue.
+
198 * For example it can occur if the function expects a local adapter name and the
+
199 * provided name did not match any of the currently available adapters.
+
200 */
+
201 BRAWCAP_STATUS_ERROR_NOT_FOUND = -6,
+
202 /**
+
203 * @brief Indicates that operation failed because the provided object is still in use.
+
204 *
+
205 * This may happen if another thread uses the same object or another operation for the object is still outstanding.
+
206 */
+
207 BRAWCAP_STATUS_ERROR_IN_USE = -7,
+
208 /**
+
209 * @brief The packet size is beyond adapter MTU.
+
210 *
+
211 * This status is especially for transmitted packets.
+
212 * It will be applied if the packet could not be transmitted because
+
213 * it´s length is beyond the configured adapter MTU.
+
214 */
+
215 BRAWCAP_STATUS_ERROR_BEYOND_MTU = -8,
+
216 /**
+
217 * @brief Communication with the driver failed.
+
218 *
+
219 * This indicates an error between library and driver communication.
+
220 *
+
221 * To fix such issues, make sure that the loaded library version matches with the driver version.
+
222 *
+
223 * In general it is not allowed to mix up library and driver versions.
+
224 * Applications shall always use the deployed bRAWcap library from the system
+
225 * and not deploy it´s own copy of it.
+
226 *
+
227 * If driver and library version matches and this error still occurs, please contact our support.
+
228 */
+
229 BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED = -9,
+
230 /**
+
231 * @brief bRAWcap is not activated (on a specific adapter).
+
232 *
+
233 * This will be returned if bRAWcap driver is not available (anymore)
+
234 * for the specified bRAWcap handle.
+
235 * For example if the driver was deactivated meanwhile.
+
236 */
+
237 BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE = -10,
+
238 /**
+
239 * @brief A buffer overrun was detected.
+
240 *
+
241 * This is the case if:
+
242 * - The provided buffer length was to short for the content.
+
243 * - A bRAWcap packet buffer has reached it´s "packet" capacity.
+
244 */
+
245 BRAWCAP_STATUS_ERROR_OVERRUN = -11,
+
246 #endif
+
247
+
248 // WARNING (1 to 1999)
+
249 #if 1
+
250 /**
+
251 * @brief The operation was not executed due to demo mode limitations.
+
252 *
+
253 * This should only be returned if there is no valid license for the requested feature.
+
254 * For more information about demo limitation see chapter @ref demo-mode "Demo Mode" in the manual.
+
255 */
+
256 BRAWCAP_STATUS_WARNING_DEMO_MODE = 1,
+
257 /**
+
258 * @brief Will be returned if another operation for the same resource is pending.
+
259 *
+
260 * This could be the case for functions which will initiate a receive/transmit while another
+
261 * receive/transmit is already pending on the specified handle.
+
262 * In general it is not allowed to use receive/transmits in parallel on the same handle.
+
263 * For example if a receive is @ref brawcap_rx_start "started", @ref brawcap_rx_packet cannot be used until the
+
264 * receive is @ref brawcap_rx_stop "stopped". Same applies to transmissions.
+
265 */
+
266 BRAWCAP_STATUS_WARNING_PENDING = 2,
+
267 /**
+
268 * @brief Indicates that a bRAWcap limitation is reached.
+
269 *
+
270 * This could be the case if there are already max supported number of handles to the same adapter
+
271 * and the caller tries to open another one.
+
272 */
+
273 BRAWCAP_STATUS_WARNING_LIMIT_REACHED = 3,
+
274 /**
+
275 * @brief Indicates that a operation was canceled.
+
276 *
+
277 * For example if a packet transmission was initiated and it is somehow canceled.
+
278 * This could be the case due to bRAWcap driver deactivation.
+
279 * If so this status will be applied for each packet which was canceled (not transmitted).
+
280 */
+
281 BRAWCAP_STATUS_WARNING_CANCELED = 4,
+
282 /**
+
283 * @brief Indicates that not all of the specified content/payload was processed.
+
284 *
+
285 * It will be returned for example if not all packets of a bRAWcap packet buffer was transmitted.
+
286 * If so the user should check the status of each packet inside the buffer for further information.
+
287 */
+
288 BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED = 5,
+
289 /**
+
290 * @brief Indicates that there is currently no uplink on the given adapter.
+
291 *
+
292 * It will be returned if the user tries to send packets to a adapter which has currently no uplink.
+
293 */
+
294 BRAWCAP_STATUS_WARNING_NO_UPLINK = 6,
+
295 #endif
+
296
+
297 // INFO (2000 - 3999)
+
298 #if 1
+
299 /**
+
300 * @brief No operation running.
+
301 *
+
302 * This will be returned if the user tries to stop something which is currently not running.
+
303 * For example when trying to stop receiving while it is not running.
+
304 */
+
305 BRAWCAP_STATUS_INFO_NOT_RUNNING = 2000,
+
306 /**
+
307 * @brief Indicates that the given object is not attached.
+
308 *
+
309 * Will be returned for example if the user tries to detach a packet buffer
+
310 * which is currently not attached to a handle.
+
311 */
+
312 BRAWCAP_STATUS_INFO_NOT_ATTACHED = 2001,
+
313 /**
+
314 * @brief Indicates that the given object is not registered.
+
315 *
+
316 * Will be returned if user tries to unregister from a bRAWcap notification
+
317 * which was not registered before.
+
318 */
+
319 BRAWCAP_STATUS_INFO_NOT_REGISTERED = 2002,
+
320 /**
+
321 * @brief Indicates that the given object was already registered.
+
322 *
+
323 * Will be returned if user tries to register for something again
+
324 * which is already registered.
+
325 */
+
326 BRAWCAP_STATUS_INFO_ALREADY_REGISTERED = 2003,
+
327 /**
+
328 * @brief Indicates that a function returns without any data.
+
329 *
+
330 * This could be the case if a receive function returns without any received packet.
+
331 * For example if the configured receive timeout is reached.
+
332 */
+
333 BRAWCAP_STATUS_INFO_NO_DATA = 2004,
+
334 /**
+
335 * @brief Indicates that a function returned because of a timeout.
+
336 *
+
337 * This could be the case if a function has not finished it´s processing until a configured timeout is reached.
+
338 */
+
339 BRAWCAP_STATUS_INFO_TIMEOUT = 2005,
+
340 #endif
+
341} brawcap_status_t;
+
342
+
343/**@}*/
+
344#endif
+
345
+
346/************************************************* VERSION ***********************************************************/
+
347#if 1
+
348/**
+
349 * @example{lineno} 04_version_comparator.c
+
350 *
+
351 * This example shows how to read library (/API) and driver version of bRAWcap.
+
352 * After reading the versions it will check if both versions match.
+
353 */
+
354
+
355/**
+
356 * @defgroup brawcap_version Version
+
357 * @brief Types and functions for operating with bRAWcap version(s).
+
358 *
+
359 * Here our bRAWcap version structure is defined. This structure allows easy access to each part of the version
+
360 * and due to it´s union the complete value can be used for easy version compares.
+
361 *
+
362 * There are currently two functions to retrieve a version.
+
363 * One for the @ref brawcap_version_api "version of the loaded library" and another one for the
+
364 * @ref brawcap_version_driver "version of the loaded bRAWcap driver" on the machine.
+
365 *
+
366 * @attention In general both versions shall be equal.
+
367 * This means it is not allowed to deploy copys of the bRAWcap library with any application.
+
368 * Instead always the bRAWcap library from system path shall be used (which will be deployed by the bRAWcap setup).
+
369 * This avoids communication issues between the driver and the library.
+
370 * If there are any issues with driver communication, please check that the driver and library version matches.
+
371 *
+
372 * List of examples:
+
373 * 1. @ref 04_version_comparator.c "Version Comparator"
+
374 * @{
+
375 */
+
376
+
377/**
+
378 * @brief Struct containing the separated version parts.
+
379 */
+
380typedef struct _brawcap_version_fragments
+
381{
+
382 /**
+
383 * @brief Build version.
+
384 *
+
385 * Different for each build.
+
386 * Releases will always have different version by the upper three values.
+
387 * Versions with different build versions only should not appear.
+
388 * API and ABI always stays compatible between different build versions.
+
389 */
+
390 UINT16 build;
+
391 /**
+
392 * @brief Patch version.
+
393 *
+
394 * Different for each bugfix release.
+
395 * Will be increased if the release contains bugfixes only.
+
396 * API and ABI always stays compatible between different patch versions.
+
397 *
+
398 */
+
399 UINT16 patch;
+
400 /**
+
401 * @brief Minor version.
+
402 *
+
403 * Different for each minor release.
+
404 * Will be increased if the release contains new features (and maybe some bugfixes).
+
405 * API always stays compatible between different minor versions.
+
406 */
+
407 UINT16 minor;
+
408 /**
+
409 * @brief Major version.
+
410 *
+
411 * Different for each major release.
+
412 * Will be increased if for example some features have removed or changed in a way which would
+
413 * break the API compatibility.
+
414 * API compatibility between different major versions is not guaranteed.
+
415 */
+
416 UINT16 major;
+
417}brawcap_version_fragments_t;
+
418
+
419/**
+
420 * @brief bRAWcap version.
+
421 *
+
422 * The version is implemented as a union. The complete member allows easy compare between versions.
+
423 * While the fragments allow easy access to each version part (major, minor, patch, build).
+
424 */
+
425typedef union _brawcap_version
+
426{
+
427 brawcap_version_fragments_t fragments; /*!< Separated parts of the version.*/
+
428 UINT64 complete; /*!< Complete version as integer. Use this for comparing versions. */
+
429} brawcap_version_t;
+
430
+
431/**@}*/
+
432#endif
+
433
+
434/*********************************************** TIMESTAMP ***********************************************************/
+
435#if 1
+
436/**
+
437 * @defgroup brawcap_timestamp Timestamp
+
438 * @brief Types and functions for operating with bRAWcap timestamps.
+
439 *
+
440 * At the moment it is not possible to create a standalone @ref brawcap_timestamp_t "timestamp object".
+
441 * Instead a timestamp is always part of a @ref brawcap_packet "packet".
+
442 * To get the timestamp object use @ref brawcap_packet_timestamp_get on a specific packet.
+
443 * This object can be used than for all functions in this module.
+
444 *
+
445 * @attention The user application shall never store a timestamp, instead it should always request it from
+
446 * a packet and only use it as long as the packet itself is valid.
+
447 *
+
448 * List of examples:
+
449 * 1. @ref 08_receive_timestamp_inspector.c "Receive Timestamp Inspector"
+
450 * 2. @ref 05_receive_simple_packet_receiver.c "Simple Packet Receiver"
+
451 * @{
+
452 */
+
453
+
454/**
+
455 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC "system low precision" is supported.
+
456 */
+
457#define BRAWCAP_TIMESTAMP_MODE_SYSL_AVAILABLE(_capabilities) (_capabilities & 0x01)
+
458
+
459/**
+
460 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC "system high precision" is supported.
+
461 */
+
462#define BRAWCAP_TIMESTAMP_MODE_SYSH_AVAILABLE(_capabilities) (_capabilities & 0x02)
+
463
+
464/**
+
465 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_SOFTWARE "software" is supported.
+
466 */
+
467#define BRAWCAP_TIMESTAMP_MODE_SW_AVAILABLE(_capabilities) (_capabilities & 0x04)
+
468
+
469/**
+
470 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM "adapter system" is supported.
+
471 */
+
472#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYS_AVAILABLE(_capabilities) (_capabilities & 0x08)
+
473
+
474/**
+
475 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE "adapter software" is supported.
+
476 */
+
477#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SW_AVAILABLE(_capabilities) (_capabilities & 0x10)
+
478
+
479/**
+
480 * @brief Checks if timestamp mode @ref BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE "adapter hardware" is supported.
+
481 */
+
482#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_HW_AVAILABLE(_capabilities) (_capabilities & 0x20)
+
483
+
484/**
+
485 * @brief If a timestamp resolution is set to this value,
+
486 * it´s resolution is unknown - could not be resolved.
+
487 *
+
488 * For example this can be the case for adapter hardware timestamps,
+
489 * if the adapter does not report it´s clock frequency.
+
490 */
+
491#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN 0
+
492
+
493/**
+
494 * @brief Number of nanoseconds per second.
+
495 */
+
496#define BRAWCAP_TIMESTAMP_NS_PER_SEC 1000000000
+
497
+
498/**
+
499 * @brief Number of microseconds per second.
+
500 */
+
501#define BRAWCAP_TIMESTAMP_US_PER_SEC 1000000
+
502
+
503/**
+
504 * @brief Number of milliseconds per second.
+
505 */
+
506#define BRAWCAP_TIMESTAMP_MS_PER_SEC 1000
+
507
+
508/**
+
509 * @brief Number of nanoseconds per microsecond.
+
510 */
+
511#define BRAWCAP_TIMESTAMP_NS_PER_US 1000
+
512
+
513/**
+
514 * @brief Number of nanoseconds per millisecond.
+
515 */
+
516#define BRAWCAP_TIMESTAMP_NS_PER_MS 1000000
+
517
+
518
+
519/**
+
520 * @brief Type used for indicating the supported timestamp modes.
+
521 *
+
522 * It has to be interpreted as bitfield.
+
523 */
+
524typedef UINT32 brawcap_timestamp_capabilities_t;
+
525
+
526/**
+
527 * @brief Represents the timestamp resolution in nanoseconds.
+
528 *
+
529 * The resolution can be used to check how accurate a timestamp is.
+
530 * For example if it is set to 1.000.000 ns the timestamp has a accuracy of "only" one millisecond.
+
531 * If it is set to 1 ns instead, it would indicate a very precise timestamp with a resolution of one nanosecond.
+
532 */
+
533typedef UINT32 brawcap_timestamp_resolution_ns_t;
+
534
+
535/**
+
536 * @brief List of different timestamp modes.
+
537 *
+
538 * The mode of a timestamp can be used to check when the timestamp is generated (time of trigger).
+
539 * It can also indicate how accurate a timestamp is.
+
540 *
+
541 * Description for the different timestamp types:
+
542 * - System timestamps:
+
543 * - Less accurate
+
544 * - Jumps if the system time itself is jumping.
+
545 * - Source is the system time
+
546 * - Software timestamps:
+
547 * - Good accuracy
+
548 * - Guaranteed to not jump.
+
549 * - Source is almost ever the local TSC (if the CPU supports it).
+
550 * If not Windows will take the next accurate source for it.
+
551 * For more information on QPC, please see the official
+
552 * <a href=https://learn.microsoft.com/en-us/windows/win32/sysinfo/acquiring-high-resolution-time-stamps> Microsoft documentation </a>.
+
553 * - They will always start from zero and increase with system up time.
+
554 * - Hardware timestamps:
+
555 * - Highest accuracy because they are not influenced by the system.
+
556 * - Only jumps if the adapter hardware clock jumps.
+
557 * - Source is the adapter hardware clock.
+
558 *
+
559 * @note Adapter timestamps are features provided by the underlying adapter and not part of bRAWcap.
+
560 * bRAWcap only provides those timestamps if the underlying adapter supports it.
+
561 * To check if the underlying adapter supports them use
+
562 * - @ref brawcap_rx_timestamp_capabilities for receive timestamps
+
563 * - @ref brawcap_tx_timestamp_capabilities for transmit timestamps
+
564 *
+
565 * @note More accurate system or software timestamps can increase the overall CPU load a bit.
+
566 * These differences can be neglected in most cases, but if the user is not interested in high-precision timestamps,
+
567 * always timestamps that require less effort should be preferred.
+
568 *
+
569 * @note Trigger position for timestamps created by bRAWcap driver:
+
570 * - Receive: When the packet is recognized by the bRAWcap driver (forwarded from the underlying driver)
+
571 * - Transmit: When the transmission complete event is recognized by the bRAWcap driver
+
572 */
+
573typedef enum _brawcap_timestamp_mode
+
574{
+
575 /**
+
576 * @brief No timestamp.
+
577 */
+
578 BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP = 0x00,
+
579 /**
+
580 * @brief A low precision system timestamp created by bRAWcap driver.
+
581 */
+
582 BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC = 0x01,
+
583 /**
+
584 * @brief A high precision system timestamp created by bRAWcap driver.
+
585 */
+
586 BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC = 0x02,
+
587 /**
+
588 * @brief A software timestamp created by bRAWcap driver.
+
589 */
+
590 BRAWCAP_TIMESTAMP_MODE_SOFTWARE = 0x04,
+
591 /**
+
592 * @brief A system timestamp created by the network adapter driver.
+
593 */
+
594 BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM = 0x08,
+
595 /**
+
596 * @brief A software timestamp created by the network adapter driver.
+
597 */
+
598 BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE = 0x10,
+
599 /**
+
600 * @brief A hardware timestamp created by the network adapter hardware/firmware.
+
601 */
+
602 BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE = 0x20
+
603}brawcap_timestamp_mode_t;
+
604
+
605/**
+
606 * @brief bRAWcap timestamp object.
+
607 *
+
608 * The timestamp object is part of each @ref brawcap_packet "packet" and
+
609 * has to be used for each timestamp module function.
+
610 * To get a timestamp object from a packet use @ref brawcap_packet_timestamp_get.
+
611 */
+
612typedef struct _brawcap_timestamp brawcap_timestamp_t;
+
613
+
614/**@}*/
+
615#endif
+
616
+
617/************************************************ PACKET *************************************************************/
+
618#if 1
+
619/**
+
620 * @defgroup brawcap_packet Packet
+
621 * @brief Types and functions for operating with bRAWcap packets.
+
622 *
+
623 * To create a packet use @ref brawcap_packet_create.
+
624 * If a packet is not required anymore it shall be deleted with @ref brawcap_packet_free.
+
625 *
+
626 * @note It is also possible to use "buffered" packets. Those packets must not be created and freed on their one.
+
627 * Instead they are part of a @ref brawcap_buffer "packet buffer". To access buffered packets use
+
628 * @ref brawcap_buffer_at_index to get a packet on a specific position of the buffer or
+
629 * @ref brawcap_buffer_iterator_eval on a @ref brawcap_buffer_iterator_t "packet buffer iterator".
+
630 * The second one is especially useful while iterating the buffer.
+
631 *
+
632 * @attention The user application shall never store buffered packets separately.
+
633 * Instead it should always request packets directly from the packet buffer and only use them as long as the packet
+
634 * buffer itself is valid.
+
635 *
+
636 * List of examples:
+
637 * 1. @ref 05_receive_simple_packet_receiver.c "Simple Packet Receiver"
+
638 * 2. @ref 07_receive_buffered_receiver.c "Buffered Receiver"
+
639 * 3. @ref 08_receive_timestamp_inspector.c "Receive Timestamp Inspector"
+
640 *
+
641 * @{
+
642 */
+
643
+
644/**
+
645 * @brief The maximum supported (byte) size for a single packet payload.
+
646 *
+
647 * This value corresponds to jumbo frame size (9000 Bytes) + Ethernet header (14 Bytes) + single VLAN header (4 Bytes).
+
648 */
+
649#define BRAWCAP_PACKET_SIZE_MAX 9018
+
650
+
651/**
+
652 * @brief The minimum required (byte) size for a single packet payload.
+
653 *
+
654 * This corresponds to Ethernet header size.
+
655 *
+
656 * @note The Ethernet standard defines a minimum packet length of 64 Bytes (including 4 Byte for Ethernet FCS).
+
657 * If smaller packets are sent the network adapter will automatically add some padding at the end of the payload.
+
658 * The padding contains zeros only and after the last padding/payload byte the Ethernet FCS will be added.
+
659 */
+
660#define BRAWCAP_PACKET_SIZE_MIN 14
+
661
+
662/**
+
663 * @brief Type for handling the number of payload bytes per packet.
+
664 *
+
665 * Typically the packet payload size is set to the adapters max transmission unit (MTU) size + Ethernet header size
+
666 * and maybe a single VLAN header.
+
667 * Packet payload sizes have to be between @ref BRAWCAP_PACKET_SIZE_MIN and @ref BRAWCAP_PACKET_SIZE_MAX,
+
668 * values below/beyond are not accepted.
+
669 */
+
670typedef UINT16 brawcap_packet_size_t;
+
671
+
672/**
+
673 * @brief bRAWcap packet object.
+
674 *
+
675 * The packet object has to be used for each packet module function.
+
676 * Packet objects can be @ref brawcap_packet_create "created" and @ref brawcap_packet_free "freed"
+
677 * or retrieved from a @ref brawcap_buffer "packet buffer".
+
678 */
+
679typedef struct _brawcap_packet brawcap_packet_t;
+
680
+
681/**@}*/
+
682#endif
+
683
+
684/************************************************* BUFFER *************************************************************/
+
685#if 1
+
686/**
+
687 * @defgroup brawcap_buffer Packet Buffer
+
688 * @brief Types and functions for operating with bRAWcap packet buffers.
+
689 *
+
690 * To create a new packet buffer use @ref brawcap_buffer_create.
+
691 * If a packet buffer is not required anymore it shall be deleted with @ref brawcap_buffer_free.
+
692 *
+
693 * Packet buffers can be used for
+
694 * - Receiving:
+
695 * To use a buffer for receiving on a bRAWcap handle it has to be @ref brawcap_rx_buffer_attach "attached" to it.
+
696 * If it shall not be used anymore for receiving it should be @ref brawcap_rx_buffer_detach "detached".
+
697 *
+
698 * - Transmitting:
+
699 * For transmitting a packet buffer, fill up the buffer with packets and than @ref brawcap_tx_buffer_send "send"
+
700 * it on a handle. This will place the buffer into the transmission queue of the specified handle.
+
701 *
+
702 * @attention The packet buffer will be locked down after attaching/sending to a specific handle.
+
703 * This means that it cannot be accessed by user application as long as it is pending for transmission or attached for
+
704 * receiving. If the user application tries to access a locked buffer a error will be returned by the specific
+
705 * packet buffer function.
+
706 *
+
707 * A packet buffer can be accessed if:
+
708 * - It is not attached for receiving.
+
709 * - No transmission is pending.
+
710 * - While receiving - from inside the @ref brawcap_rx_callback_t "receive callback".
+
711 * - While transmitting - from inside the @ref brawcap_tx_callback_t "transmit callback".
+
712 *
+
713 * List of examples:
+
714 * 1. @ref 07_receive_buffered_receiver.c "Buffered Receiver"
+
715 * @{
+
716 */
+
717
+
718/**
+
719 * @brief The maximum amount of packets, which can be stored in a packet buffer.
+
720 */
+
721#define BRAWCAP_BUFFER_PACKETS_MAX 100000
+
722
+
723/**
+
724 * @brief The minimum amount of packets, which a packet buffer must have.
+
725 */
+
726#define BRAWCAP_BUFFER_PACKETS_MIN 1
+
727
+
728/**
+
729 * @brief Type for handling the number of packets which can be stored in a packet buffer.
+
730 *
+
731 * The total amount of packets per packet buffer has to be between @ref BRAWCAP_BUFFER_PACKETS_MIN -
+
732 * @ref BRAWCAP_BUFFER_PACKETS_MAX.
+
733 */
+
734typedef UINT32 brawcap_buffer_packet_count_t;
+
735
+
736/**
+
737 * @brief bRAWcap packet buffer object.
+
738 *
+
739 * The packet buffer object has to be used for each packet buffer module function.
+
740 * Packet buffers can be @ref brawcap_buffer_create "created" and @ref brawcap_buffer_free "freed".
+
741 */
+
742typedef struct _brawcap_buffer brawcap_buffer_t;
+
743
+
744/********************************************* BUFFER ITERATOR ********************************************************/
+
745#if 1
+
746/**
+
747 * @defgroup brawcap_buffer_iterator Packet Buffer Iterator
+
748 * @brief bRAWcap packet buffer iterators.
+
749 *
+
750 * To create a new packet buffer iterator use @ref brawcap_buffer_iterator_create.
+
751 * If a packet buffer iterator is not required anymore it shall be deleted with @ref brawcap_buffer_iterator_free.
+
752 *
+
753 * @note Iterators should only be used as long as the packet buffer for which it was created is still available.
+
754 *
+
755 * @attention Packet buffer iterators are not synchronized. This means that if the packet buffer for which the iterator
+
756 * was created is modified meanwhile, the iterator is not updated.
+
757 *
+
758 * List of examples:
+
759 * 1. @ref 07_receive_buffered_receiver.c "Buffered Receiver"
+
760 * @{
+
761 */
+
762
+
763/**
+
764 * @brief bRAWcap packet buffer iterator object.
+
765 *
+
766 * The packet buffer object has to be used for each packet buffer iterator module function.
+
767 * Packet buffer iterators can be @ref brawcap_buffer_iterator_create "created" and @ref brawcap_buffer_iterator_free
+
768 * "freed".
+
769 */
+
770typedef struct _brawcap_buffer_iterator brawcap_buffer_iterator_t;
+
771
+
772/**@}*/
+
773#endif
+
774
+
775/**@}*/
+
776#endif
+
777
+
778/************************************************** ADAPTER **********************************************************/
+
779#if 1
+
780/**
+
781 * @example{lineno} 01_adapter_property_reader.c
+
782 *
+
783 * This example shows how to get all currently available adapters on the machine.
+
784 * And how to get the properties for each adapter.
+
785 * The adapters and their properties will be printed to command line output.
+
786 *
+
787 * @attention This example requires a valid bRAWcap license.
+
788 * Reading adapter properties is not part of the demo.
+
789 */
+
790
+
791/**
+
792 * @example{lineno} 02_adapter_change_notifier.c
+
793 *
+
794 * This example shows how to register and handle adapter change notifications.
+
795 * It will print each received notification to command line.
+
796 * Each output will also include the change reason and the new adapter property value.
+
797 *
+
798 * @attention This example requires a valid bRAWcap license.
+
799 * Reading adapter properties is not part of the demo.
+
800 */
+
801
+
802/**
+
803 * @defgroup brawcap_adapter Adapter
+
804 * @brief Types and functions for handling bRAWcap (Ethernet) adapters.
+
805 *
+
806 * This module provides many features that facilitate the detection of bRAWcap (Ethernet) adapters.
+
807 * It allows to scan the local machine for available and supported adapters,
+
808 * to resolve many useful adapter properties for each adapter and also an adapter change notification.
+
809 *
+
810 * Adapter change notifications inform your application directly when any of the available properties have changed,
+
811 * or when a new adapter has been found or an existing one has been removed (e.g. by disabling the interface).
+
812 *
+
813 * When you use these functions, they make all calls to the Windows API - related to adapter handling - obsolete.
+
814 *
+
815 * List of examples:
+
816 * 1. @ref 01_adapter_property_reader.c "Adapter Property Reader"
+
817 * 2. @ref 02_adapter_change_notifier.c "Adapter Change Notifier"
+
818 * @{
+
819 */
+
820
+
821/**@}*/
+
822#endif
+
823
+
824/************************************************** RECEIVE **********************************************************/
+
825#if 1
+
826/**
+
827 * @example{lineno} 05_receive_simple_packet_receiver.c
+
828 *
+
829 * This example shows how to use the bRAWcap single packet receive feature.
+
830 * It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet
+
831 * to store received data to. For each received packet it will print the packet information to console.
+
832 */
+
833
+
834/**
+
835 * @example{lineno} 07_receive_buffered_receiver.c
+
836 *
+
837 * This example shows how to use the bRAWcap single packet receive feature.
+
838 * It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet
+
839 * to store received data to. For each received packet it will print the packet information to console.
+
840 */
+
841
+
842/**
+
843 * @example{lineno} 08_receive_timestamp_inspector.c
+
844 *
+
845 * This example shows how to configure the different timestamp modes and read timestamp information from single
+
846 * received packets.
+
847 * It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet
+
848 * to store received data to and applies the configured timestamp mode. For each received packet it will print
+
849 * it´s applied timestamp info.
+
850 */
+
851
+
852/**
+
853 * @defgroup brawcap_receive Receive
+
854 * @brief Types and functions for bRAWcap receiving.
+
855 *
+
856 * List of examples:
+
857 * 1. @ref 05_receive_simple_packet_receiver.c "Simple Packet Receiver"
+
858 * 2. @ref 07_receive_buffered_receiver.c "Buffered Receiver"
+
859 * 3. @ref 08_receive_timestamp_inspector.c "Timestamp Inspector"
+
860 * @{
+
861 */
+
862
+
863/********************************************** RECEIVE FILTER *******************************************************/
+
864#if 1
+
865/**
+
866 * @example{lineno} 06_filter_firewall.c
+
867 *
+
868 * This example shows how bRAWcap can be used to filter (discard) specific packets by using a byte filter.
+
869 */
+
870
+
871/**
+
872 * @defgroup brawcap_filter Receive Filter
+
873 * @brief Types and functions for operating with bRAWcap receive filters.
+
874 *
+
875 * To create a new filter use @ref brawcap_filter_create.
+
876 * If a filter is not required anymore it shall be deleted with @ref brawcap_filter_free.
+
877 *
+
878 * @note Applying filters to handles:<br>
+
879 * Each bRAWcap handle has it´s own filter instance.
+
880 * Therefore after applying the filter to a bRAWcap handle the filter may be reused to apply the
+
881 * same (or a different) filter to another handle or freed if not required anymore.
+
882 *
+
883 * List of examples:
+
884 * 1. @ref 06_filter_firewall.c "Firewall"
+
885 * @{
+
886 */
+
887
+
888/**
+
889 * @brief The maximum supported filter byte mask length in bytes.
+
890 */
+
891#define BRAWCAP_FILTER_BYTE_MAX_LENGTH 64U
+
892
+
893/**
+
894 * @brief Fixed size array for storing a filter byte mask.
+
895 *
+
896 * @note It is not necessary to set all bytes.
+
897 * If the used filter does not require the complete mask length.
+
898 * bRAWcap evaluates only the bytes up to the specified filter length.
+
899 */
+
900typedef UINT8 brawcap_filter_mask_array_t [BRAWCAP_FILTER_BYTE_MAX_LENGTH];
+
901
+
902/**
+
903 * @brief Fixed size array for storing a byte wise bitfield.
+
904 *
+
905 * This allows to ignore specific bits in the specified filter byte mask.
+
906 * Each bit which is set to one is ignored in the filter byte mask.
+
907 *
+
908 * @note It is not necessary to set all bytes.
+
909 * If the used filter does not require the complete mask length.
+
910 * bRAWcap evaluates only the bytes up to the specified filter length.
+
911 */
+
912typedef UINT8 brawcap_filter_ignore_bits_array_t [BRAWCAP_FILTER_BYTE_MAX_LENGTH];
+
913
+
914/**
+
915 * @brief Type for specifying the byte filter length.
+
916 */
+
917typedef brawcap_packet_size_t brawcap_filter_byte_length_t;
+
918
+
919/**
+
920 * @brief List of filter types.
+
921 *
+
922 * @note Currently only the byte filter is supported.
+
923 * A BPF (Berkley Packet Filter) filter, which is equivalent to the one which libpcap uses,
+
924 * may be added in the future.
+
925 */
+
926typedef enum _brawcap_filter_type
+
927{
+
928 /**
+
929 * @brief A bRAWcap byte filter.
+
930 */
+
931 BRAWCAP_FILTER_TYPE_BYTE_MASK = 0,
+
932 /**
+
933 * @brief A Berkley Packet Filter.
+
934 */
+
935 BRAWCAP_FILTER_TYPE_BPF = 1
+
936}brawcap_filter_type_t;
+
937 typedef struct bpf_insn* brawcap_bpf_insn_t;
+
938
+
939 typedef struct bpf_program* brawcap_bpf_program_t;
+
940#ifdef _BRAWCAP_DEFINE_BPF_STRUCTS_INTERNAL
+
941 /**
+
942 * @brief A single BPF pseudo-instruction.
+
943 *
+
944 * Contains a single instruction for the BPF.
+
945 */
+
946 struct bpf_insn
+
947 {
+
948 USHORT code; /*!< Instruction type and addressing mode. */
+
949 UCHAR jt; /*!< Jump if true. */
+
950 UCHAR jf; /*!< Jump if false. */
+
951 UINT32 k; /*!< Generic field used for various purposes. */
+
952 };
+
953
+
954 /**
+
955 * @brief A BPF pseudo-assembly program.
+
956 *
+
957 * The BPF program can be used to filter incoming packets.
+
958 * To get a BPF program it has to be generated/compiled from a BPF filter string, first.
+
959 */
+
960 struct bpf_program
+
961 {
+
962 UINT bf_len; /*!< Indicates the number of instructions of the program. */
+
963 struct bpf_insn* bf_insns; /*!< A pointer to the first instruction of the program. */
+
964 };
+
965#endif
+
966
+
967/**
+
968 * @brief bRAWcap filter object.
+
969 *
+
970 * The filter object can be accessed with the bRAWcap filter functions.
+
971 * Filters can be @ref brawcap_filter_create "created" and @ref brawcap_filter_free "freed".
+
972 */
+
973typedef struct _brawcap_filter brawcap_filter_t;
+
974
+
975/**@}*/
+
976#endif
+
977
+
978/**
+
979 * @brief Default minimum packets to copy value which has to be received before any receive function return
+
980 * even if configured timeout exceeds.
+
981 *
+
982 * @note bRAWcap waits at least up to 10 times the configured timeout before finally returning if
+
983 * the minimum number of packets has not yet been received.
+
984 *
+
985 * @warning If a timeout of zero which is equivalent to infinite wait is configured it blocks until
+
986 * the minimum amount of packets are received and will not return earlier.
+
987 */
+
988#define BRAWCAP_RX_COPY_PACKETS_DEFAULT 0
+
989
+
990/**
+
991 * @brief Default timeout in milliseconds after which a bRAWcap receive returns,
+
992 * even if buffer is not yet full but the configured receive min packets to copy must be reached.
+
993 */
+
994#define BRAWCAP_RX_TIMEOUT_MS_DEFAULT 10
+
995
+
996/**
+
997 * @brief Default receive timestamp mode which will be used.
+
998 */
+
999#define BRAWCAP_RX_TIMESTAMP_MODE_DEFAULT BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
+
1000
+
1001/**
+
1002 * @brief Default VLAN tagging mode which will be used.
+
1003 */
+
1004#define BRAWCAP_RX_VLAN_TAGGING_DEFAULT FALSE
+
1005
+
1006/**
+
1007 * @brief Default size for driver receive queues in number of packets.
+
1008 */
+
1009#define BRAWCAP_RX_DRIVER_QUEUE_SIZE_DEFAULT 4096
+
1010
+
1011/**
+
1012 * @brief Maximum supported receive timeout in number of milliseconds.
+
1013 */
+
1014#define BRAWCAP_RX_TIMEOUT_MS_MAX 5000
+
1015
+
1016/**
+
1017 * @brief Maximum size (in number of packets) supported for driver receive queues.
+
1018 */
+
1019#define BRAWCAP_RX_DRIVER_QUEUE_SIZE_MAX 40000
+
1020
+
1021/**
+
1022 * @brief Default receive direction which will be used.
+
1023 */
+
1024#define BRAWCAP_RX_DIRECTION_DEFAULT BRAWCAP_RX_DIRECTION_BOTH
+
1025
+
1026/**
+
1027 * @brief Type for handling receive timeouts in number of milliseconds.
+
1028 * The timeout specifies the maximum blocking time in milliseconds for pending bRAWcap receives.
+
1029 * If a packet is received or the receive buffer is full before the timeout is reached, receive will return earlier.
+
1030 *
+
1031 * @attention A receive timeout value of zero corresponds to an infinite wait.
+
1032 * This means that bRAWcap receive will only return if
+
1033 * - @ref brawcap_rx_packet - a packet is received,
+
1034 * - @ref brawcap_rx_start - the minimum amount of packets to copy is reached (see @ref brawcap_rx_min_packets_t)
+
1035 * or the attached buffer is full - whichever comes first.
+
1036 */
+
1037typedef UINT16 brawcap_rx_timeout_t;
+
1038
+
1039/**
+
1040 * @brief Type for handling the minimum amount of packets to copy before a bRAWcap receive will return.
+
1041 * It specifies how many packets should be received before a pending receive returns.
+
1042 * Reading more packets in a single call can improve the performance but leads to higher latency.
+
1043 *
+
1044 * @note This setting is only used with looped receive (@ref brawcap_rx_start) and has no impact on single packet
+
1045 * reception (@ref brawcap_rx_packet).
+
1046 */
+
1047typedef UINT32 brawcap_rx_min_packets_t;
+
1048
+
1049/**
+
1050 * @brief List of receive modes.
+
1051 */
+
1052typedef enum _brawcap_rx_mode
+
1053{
+
1054 /**
+
1055 * @brief Received packets are stored in a user created bRAWcap packet (buffer) and provided to the
+
1056 * calling application for processing.
+
1057 */
+
1058 BRAWCAP_RX_MODE_LIVE = 1,
+
1059 /**
+
1060 * @brief Received packets are directly written to disk.
+
1061 *
+
1062 * @note Dumping mode is not yet supported and may be added to later releases.
+
1063 */
+
1064 BRAWCAP_RX_MODE_DUMP = 2
+
1065}brawcap_rx_mode_t;
+
1066
+
1067/**
+
1068 * @brief List of supported receive directions.
+
1069 *
+
1070 * The receive direction allows the select for which direction (transmit/receive) the packets shall be captured.
+
1071 * This setting can be seen as some kind of generic receive filter.
+
1072 */
+
1073typedef enum _brawcap_rx_direction
+
1074{
+
1075 /**
+
1076 * @brief Stops to receive packets of any direction.
+
1077 */
+
1078 BRAWCAP_RX_DIRECTION_UNKNOWN = 0x00,
+
1079 /**
+
1080 * @brief Only received packets by the network adapter will be received.
+
1081 */
+
1082 BRAWCAP_RX_DIRECTION_IN = 0x01,
+
1083 /**
+
1084 * @brief Only transmitted packets by bRAWcap or upper network stack drivers will be received.
+
1085 * This allows some kind of loopback for packets which are transmitted to the network.
+
1086 *
+
1087 * @note This currently does not include packets sent to localhost (IP 127.0.0.1), because they are
+
1088 * not transmitted/received via a real network adapter. Instead Windows creates a separate "virtual" adapter
+
1089 * for localhost communication. This adapter is currently not supported by bRAWcap.
+
1090 */
+
1091 BRAWCAP_RX_DIRECTION_OUT = 0x02,
+
1092 /**
+
1093 * @brief Both transmitted packets by bRAWcap or upper network stack drivers and received packets from the
+
1094 * underlying network adapter will be received.
+
1095 */
+
1096 BRAWCAP_RX_DIRECTION_BOTH = 0x03
+
1097}brawcap_rx_direction_t;
+
1098
+
1099/**@}*/
+
1100#endif
+
1101
+
1102/************************************************* TRANSMIT **********************************************************/
+
1103#if 1
+
1104/**
+
1105 * @defgroup brawcap_transmit Transmit
+
1106 * @brief Types and functions for bRAWcap transmitting.
+
1107 * @{
+
1108 */
+
1109
+
1110/**
+
1111 * @brief Default size in number of packets for driver transmit queues.
+
1112 */
+
1113#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT 512
+
1114
+
1115/**
+
1116 * @brief Minimum size in number of packets supported for driver transmit queues.
+
1117 */
+
1118#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MIN 256
+
1119
+
1120/**
+
1121 * @brief Maximum size in number of packets supported for driver transmit queues.
+
1122 */
+
1123#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX 4096
+
1124
+
1125/**
+
1126 * @brief Default timestamp mode for transmitted packets.
+
1127 */
+
1128#define BRAWCAP_TX_TIMESTAMP_MODE_DEFAULT BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
+
1129
+
1130/**@}*/
+
1131#endif
+
1132
+
1133/*************************************************** STATS ***********************************************************/
+
1134#if 1
+
1135/**
+
1136 * @defgroup brawcap_stats Statistics
+
1137 * @brief Types and functions for bRAWcap statistics.
+
1138 * @{
+
1139 */
+
1140
+
1141/**
+
1142 * @internal
+
1143 * @brief Returns the offset from the first member to the last member in number of bytes.
+
1144*/
+
1145#define _BRAWCAP_LAST_M_OFFSET(type, lastMember) ((LONG)(LONG_PTR)&(((type *)0)->lastMember))
+
1146/**
+
1147 * @internal
+
1148 * @brief Returns the size of the last member in number of bytes.
+
1149 */
+
1150#define _BRAWCAP_LAST_M_SIZE(type, lastMember) (sizeof(((type *)0)->lastMember))
+
1151/**
+
1152 * @internal
+
1153 * @brief Returns the total byte size of the structure, depending on the structure and its last member.
+
1154 * @warning It is very important to always update the lastMember if the struct is going to be extended.
+
1155 */
+
1156#define _BRAWCAP_SIZEOF_STRUCT(type, lastMember) \
+
1157 (_BRAWCAP_LAST_M_OFFSET(type, lastMember) + _BRAWCAP_LAST_M_SIZE(type, lastMember))
+
1158
+
1159/**
+
1160 * @internal
+
1161 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterReceivedPacketsTotal member of the receive stats is valid.
+
1162 * @endinternal
+
1163 */
+
1164#define _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID 0x00000001
+
1165/**
+
1166 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterReceivedPacketsTotal member of the given receive stats is
+
1167 * valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1168 */
+
1169#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID(__stats_rx) \
+
1170 (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID)
+
1171/**
+
1172 * @internal
+
1173 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterReceivedBytesTotal member of the receive stats is valid.
+
1174 * @endinternal
+
1175 */
+
1176#define _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID 0x00000002
+
1177/**
+
1178 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterReceivedBytesTotal member of the given receive stats is valid.
+
1179 * This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1180 */
+
1181#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID(__stats_rx) \
+
1182 (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID)
+
1183/**
+
1184 * @internal
+
1185 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterDroppedPacketsTotal member of the receive stats is valid.
+
1186 * @endinternal
+
1187 */
+
1188#define _BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID 0x00000004
+
1189/**
+
1190 * @brief Indicates if the @ref brawcap_stats_rx_t.adapterDroppedPacketsTotal member of the given receive stats is
+
1191 * valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1192 */
+
1193#define BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID(__stats_rx) \
+
1194 (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID)
+
1195
+
1196/**
+
1197 * @internal
+
1198 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCompletedPacketsTotal member of the transmit stats is valid.
+
1199 * @endinternal
+
1200 */
+
1201#define _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID 0x00000001
+
1202/**
+
1203 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCompletedPacketsTotal member of the given transmit stats is
+
1204 * valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1205 */
+
1206#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID(__stats_tx) \
+
1207 (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID)
+
1208/**
+
1209 * @internal
+
1210 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCompletedBytesTotal member of the transmit stats is valid.
+
1211 * @endinternal
+
1212 */
+
1213#define _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID 0x00000002
+
1214/**
+
1215 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCompletedBytesTotal member of the given transmit stats is
+
1216 * valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1217 */
+
1218#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID(__stats_tx) \
+
1219 (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID)
+
1220/**
+
1221 * @internal
+
1222 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCanceledPacketsTotal member of the transmit stats is valid.
+
1223 * @endinternal
+
1224 */
+
1225#define _BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID 0x00000004
+
1226/**
+
1227 * @brief Indicates if the @ref brawcap_stats_tx_t.adapterCanceledPacketsTotal member of the given transmit stats is
+
1228 * valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
+
1229 */
+
1230#define BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID(__stats_tx) \
+
1231 (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID )
+
1232
+
1233/**
+
1234 * @brief Header describing given bRAWcap stats structure.
+
1235 *
+
1236 * @attention If your create a new bRAWcap stats structure you must always initialize
+
1237 * the header first before make use of it.
+
1238 * This is required to allow backward compatibility for applications using older versions.
+
1239 */
+
1240typedef struct _brawcap_stats_header
+
1241{
+
1242 /**
+
1243 * @brief Indicates which type of stats it is.
+
1244 */
+
1245 BYTE type;
+
1246 /**
+
1247 * @brief Indicates the revision of the stats.
+
1248 * @note It is preferred to always use the latest version available in your bRAWcap header file.
+
1249 * But you can also use older versions if you dont want to access members added in the newer versions.
+
1250 */
+
1251 BYTE revision;
+
1252 /**
+
1253 * @brief Should be set to the size of the structure depending on it´s type and revision.
+
1254 * You should use the BRAWCAP_STATS_..._SIZEOF_REVISION_X macros for initializing this member.
+
1255 */
+
1256 UINT16 size;
+
1257}brawcap_stats_header_t;
+
1258
+
1259/**
+
1260 * @brief List of all available statistic types.
+
1261 */
+
1262typedef enum _brawcap_stats_type
+
1263{
+
1264 /**
+
1265 * @brief Type for receive stats.
+
1266 */
+
1267 BRAWCAP_STATS_TYPE_RX = 1,
+
1268 /**
+
1269 * @brief Type for transmit stats.
+
1270 */
+
1271 BRAWCAP_STATS_TYPE_TX = 2
+
1272}brawcap_stats_type_t;
+
1273
+
1274/**
+
1275 * @brief List of all available receive statistic revisions.
+
1276 */
+
1277typedef enum _brawcap_stats_rx_revision
+
1278{
+
1279 /**
+
1280 * @brief Revision 1 for receive stats.
+
1281 */
+
1282 BRAWCAP_STATS_RX_REVISION_1 = 1
+
1283}brawcap_stats_rx_revision_t;
+
1284
+
1285/**
+
1286 * @brief The bRAWcap receive statistics.
+
1287 *
+
1288 * This can be used to retrieve all available bRAWcap statistics and counters related to receive path.
+
1289 * After creating the structure, its header has to be initialized.
+
1290 *
+
1291 * The @ref brawcap_stats_header_t.type shall be set to @ref BRAWCAP_STATS_TYPE_RX.
+
1292 *
+
1293 * The @ref brawcap_stats_header_t.revision shall be set to one of the following values:
+
1294 * - @ref BRAWCAP_STATS_RX_REVISION_1
+
1295 *
+
1296 * The @ref brawcap_stats_header_t.size shall be set depending on your selected version by using the macro:
+
1297 * - @ref BRAWCAP_STATS_RX_SIZEOF_REVISION_1 (if selected revision is @ref BRAWCAP_STATS_RX_REVISION_1)
+
1298 *
+
1299 * @attention User is responsible for initializing the structure header before using it.
+
1300 * Otherwise it may lead to undefined behaviour.
+
1301 */
+
1302typedef struct _brawcap_stats_rx
+
1303{
+
1304 /**
+
1305 * @brief Header for receive statistics.
+
1306 * This has to be always initialized by the user after creation before using it.
+
1307 */
+
1308 brawcap_stats_header_t header;
+
1309 /**
+
1310 * @brief Bitfield indicating which counters provided by the underlying network adapter driver are valid.
+
1311 */
+
1312 UINT32 adapterValid;
+
1313 /**
+
1314 * @brief Total number of received packets by the underlying network adapter.
+
1315 * @note You should check if the network adapter supports this counter with
+
1316 * @ref BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID.
+
1317 * If the counter is not supported it will be always zero.
+
1318 */
+
1319 UINT64 adapterReceivedPacketsTotal;
+
1320 /**
+
1321 * @brief Total number of received bytes by the underlying network adapter.
+
1322 * @note You should check if the network adapter supports this counter with
+
1323 * @ref BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID.
+
1324 * If the counter is not supported it will be always zero.
+
1325 */
+
1326 UINT64 adapterReceivedBytesTotal;
+
1327 /**
+
1328 * @brief Total number of received bytes by the underlying network adapter.
+
1329 * @note You should check if the network adapter supports this counter with
+
1330 * @ref BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID.
+
1331 * If the counter is not supported it will be always zero.
+
1332 */
+
1333 UINT64 adapterDroppedPacketsTotal;
+
1334 /**
+
1335 * @brief The total number of indicated packets to the upper network stack by bRAWcap on the corresponding adapter.
+
1336 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1337 */
+
1338 UINT64 driverIndicatedPacketsTotal;
+
1339 /**
+
1340 * @brief The total number of received packets by bRAWcap on the corresponding adapter.
+
1341 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter..
+
1342 */
+
1343 UINT64 driverReceivedPacketsTotal;
+
1344 /**
+
1345 * @brief The total number of received packets by the given bRAWcap handle.
+
1346 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1347 */
+
1348 UINT64 handleReceivedPacketsTotal;
+
1349 /**
+
1350 * @brief The total number of packets which have matched the given bRAWcap handle filter.
+
1351 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1352 */
+
1353 UINT64 handleReceivedPacketsMatched;
+
1354 /**
+
1355 * @brief The total number of packets which was queued to the handles driver queue.
+
1356 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1357 */
+
1358 UINT64 handleReceivedPacketsQueued;
+
1359 /**
+
1360 * @brief The total number of packets which could be directly delivered to user space memory.
+
1361 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1362 */
+
1363 UINT64 handleReceivedPacketsDirect;
+
1364 /**
+
1365 * @brief The total number of received bytes by the given bRAWcap handle.
+
1366 * @note This counter relates to a handle and will be deleted when the handle is closed
+
1367 */
+
1368 UINT64 handleReceivedBytesTotal;
+
1369 /**
+
1370 * @brief The total number of packets which was dropped for the handle (sum of all reasons).
+
1371 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1372 */
+
1373 UINT64 handleDroppedPacketsTotal;
+
1374 /**
+
1375 * @brief The total number of packets which was dropped for the handle because of resources (driver queue overrun).
+
1376 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1377 */
+
1378 UINT64 handleDroppedPacketsQueue;
+
1379 /**
+
1380 * @brief The total number of packets which was dropped for the handle their length exceeds the handles configured max
+
1381 * packet size.
+
1382 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1383 */
+
1384 UINT64 handleDroppedPacketsToLong;
+
1385}brawcap_stats_rx_t;
+
1386
+
1387/**
+
1388 * @brief Returns the size of receive statistics revision 1.
+
1389 */
+
1390#define BRAWCAP_STATS_RX_SIZEOF_REVISION_1 _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_rx_t, handleDroppedPacketsToLong)
+
1391
+
1392/**
+
1393 * @brief List of all available transmit statistic revisions.
+
1394 */
+
1395typedef enum _brawcap_stats_tx_revision
+
1396{
+
1397 /**
+
1398 * @brief Revision 1 for transmit stats.
+
1399 */
+
1400 BRAWCAP_STATS_TX_REVISION_1 = 1
+
1401}brawcap_stats_tx_revision_t;
+
1402
+
1403/**
+
1404 * @brief The bRAWcap transmit statistics.
+
1405 *
+
1406 * This can be used to retrieve all available bRAWcap statistics and counters related to transmit path.
+
1407 * After creating the structure, its header has to be initialized.
+
1408 *
+
1409 * The @ref brawcap_stats_header_t.type shall be set to @ref BRAWCAP_STATS_TYPE_TX.
+
1410 *
+
1411 * The @ref brawcap_stats_header_t.revision shall be set to one of the following values:
+
1412 * - @ref BRAWCAP_STATS_TX_REVISION_1
+
1413 *
+
1414 * The @ref brawcap_stats_header_t.size shall be set depending on your selected version by using the macro:
+
1415 * - @ref BRAWCAP_STATS_TX_SIZEOF_REVISION_1 (if selected revision is @ref BRAWCAP_STATS_TX_REVISION_1)
+
1416 *
+
1417 * @attention User is responsible for initializing the structure header before using it.
+
1418 * Otherwise it may lead to undefined behaviour.
+
1419 */
+
1420typedef struct _brawcap_stats_tx
+
1421{
+
1422 /**
+
1423 * @brief Header for transmit statistics.
+
1424 * This has to be always initialized by the user after creation before using it.
+
1425 */
+
1426 brawcap_stats_header_t header;
+
1427 /**
+
1428 * @brief Bitfield indicating which counters provided by the underlying network adapter driver are valid.
+
1429 *
+
1430 */
+
1431 UINT32 adapterValid;
+
1432 /**
+
1433 * @brief Total number of (completed) transmitted packets by the underlying network adapter.
+
1434 * @note You should check if the network adapter supports this counter with
+
1435 * @ref BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID.
+
1436 * If the counter is not supported it will be always zero.
+
1437 */
+
1438 UINT64 adapterCompletedPacketsTotal;
+
1439 /**
+
1440 * @brief Total number of (completed) transmitted bytes by the underlying network adapter.
+
1441 * @note You should check if the network adapter supports this counter with
+
1442 * @ref BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID.
+
1443 * If the counter is not supported it will be always zero.
+
1444 */
+
1445 UINT64 adapterCompletedBytesTotal;
+
1446 /**
+
1447 * @brief Total number of canceled transmitted packets by the underlying network adapter.
+
1448 * @note You should check if the network adapter supports this counter with
+
1449 * @ref BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID.
+
1450 * If the counter is not supported it will be always zero.
+
1451 */
+
1452 UINT64 adapterCanceledPacketsTotal;
+
1453 /**
+
1454 * @brief Total number of initiated packets to transmit by the bRAWcap driver on the corresponding adapter.
+
1455 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1456 */
+
1457 UINT64 driverInitiatedPacketsTotal;
+
1458 /**
+
1459 * @brief Initiated packets to transmit from upper network stack detected by bRAWcap driver on
+
1460 * the corresponding adapter.
+
1461 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1462 */
+
1463 UINT64 driverInitiatedPacketsStack;
+
1464 /**
+
1465 * @brief Initiated packets to transmit from bRAWcap driver itself on the corresponding adapter.
+
1466 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1467 */
+
1468 UINT64 driverInitiatedPacketsHandles;
+
1469 /**
+
1470 * @brief Total number of canceled packets to transmit by the bRAWcap driver on the corresponding adapter.
+
1471 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1472 */
+
1473 UINT64 driverCanceledPacketsTotal;
+
1474 /**
+
1475 * @brief Canceled packets to transmit from the upper network stack detected by bRAWcap driver on the
+
1476 * corresponding adapter.
+
1477 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1478 */
+
1479 UINT64 driverCanceledPacketsStack;
+
1480 /**
+
1481 * @brief Canceled packets to transmit from bRAWcap driver itself on the corresponding adapter.
+
1482 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1483 */
+
1484 UINT64 driverCanceledPacketsHandles;
+
1485 /**
+
1486 * @brief Total number of completed transmitted packets detected by bRAWcap driver on the corresponding adapter.
+
1487 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1488 */
+
1489 UINT64 driverCompletedPacketsTotal;
+
1490 /**
+
1491 * @brief Completed packets to transmit from the upper network stack detected by bRAWcap driver on the corresponding
+
1492 * adapter.
+
1493 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1494 */
+
1495 UINT64 driverCompletedPacketsStack;
+
1496 /**
+
1497 * @brief Completed packets to transmit from the bRAWcap driver itself on the corresponding adapter.
+
1498 * @note This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
1499 */
+
1500 UINT64 driverCompletedPacketsHandles;
+
1501 /**
+
1502 * @brief Total number of initiated packets to transmit for the handle.
+
1503 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1504 */
+
1505 UINT64 handleInitiatedPacketsTotal;
+
1506 /**
+
1507 * @brief Total number of canceled packets to transmit for the handle.
+
1508 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1509 */
+
1510 UINT64 handleCanceledPacketsTotal;
+
1511 /**
+
1512 * @brief Total number of completed transmitted packets for the handle.
+
1513 * @note This counter relates to a handle and will be deleted when the handle is closed.
+
1514 */
+
1515 UINT64 handleCompletedPacketsTotal;
+
1516
+
1517 UINT64 handleCompletedBytesTotal;
+
1518}brawcap_stats_tx_t;
+
1519
+
1520/**
+
1521 * @brief Returns the size of transmit statistics revision 1.
+
1522 */
+
1523#define BRAWCAP_STATS_TX_SIZEOF_REVISION_1 _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_tx_t, handleCompletedBytesTotal)
+
1524
+
1525/**@}*/
+
1526#endif
+
1527
+
1528#endif // BRAWCAP_TYPES_SHARED_H
+
brawcap_queue_size_t
UINT32 brawcap_queue_size_t
The number of packets which can be (temporary) buffered by the bRAWcap driver queue.
Definition: brawcap_types_shared.h:94
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_STATUS_INFO_NOT_ATTACHED
@ BRAWCAP_STATUS_INFO_NOT_ATTACHED
Indicates that the given object is not attached.
Definition: brawcap_types_shared.h:312
+
BRAWCAP_STATUS_ERROR_IN_USE
@ BRAWCAP_STATUS_ERROR_IN_USE
Indicates that operation failed because the provided object is still in use.
Definition: brawcap_types_shared.h:207
+
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE
@ BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE
bRAWcap is not activated (on a specific adapter).
Definition: brawcap_types_shared.h:237
+
BRAWCAP_STATUS_ERROR_FAILED
@ BRAWCAP_STATUS_ERROR_FAILED
Detected a - not further specified - failure.
Definition: brawcap_types_shared.h:163
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_ERROR_INVALID_PARAM
@ BRAWCAP_STATUS_ERROR_INVALID_PARAM
At least one parameter content is invalid.
Definition: brawcap_types_shared.h:186
+
BRAWCAP_STATUS_ERROR_OVERRUN
@ BRAWCAP_STATUS_ERROR_OVERRUN
A buffer overrun was detected.
Definition: brawcap_types_shared.h:245
+
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED
@ BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED
Communication with the driver failed.
Definition: brawcap_types_shared.h:229
+
BRAWCAP_STATUS_WARNING_LIMIT_REACHED
@ BRAWCAP_STATUS_WARNING_LIMIT_REACHED
Indicates that a bRAWcap limitation is reached.
Definition: brawcap_types_shared.h:273
+
BRAWCAP_STATUS_ERROR_NOT_FOUND
@ BRAWCAP_STATUS_ERROR_NOT_FOUND
Given parameter not found.
Definition: brawcap_types_shared.h:201
+
BRAWCAP_STATUS_INFO_ALREADY_REGISTERED
@ BRAWCAP_STATUS_INFO_ALREADY_REGISTERED
Indicates that the given object was already registered.
Definition: brawcap_types_shared.h:326
+
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE
@ BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE
At least one parameter is out of bounds.
Definition: brawcap_types_shared.h:193
+
BRAWCAP_STATUS_WARNING_NO_UPLINK
@ BRAWCAP_STATUS_WARNING_NO_UPLINK
Indicates that there is currently no uplink on the given adapter.
Definition: brawcap_types_shared.h:294
+
BRAWCAP_STATUS_INFO_TIMEOUT
@ BRAWCAP_STATUS_INFO_TIMEOUT
Indicates that a function returned because of a timeout.
Definition: brawcap_types_shared.h:339
+
BRAWCAP_STATUS_ERROR_INVALID_POINTER
@ BRAWCAP_STATUS_ERROR_INVALID_POINTER
At least one specified pointer parameter was invalid.
Definition: brawcap_types_shared.h:179
+
BRAWCAP_STATUS_INFO_NOT_REGISTERED
@ BRAWCAP_STATUS_INFO_NOT_REGISTERED
Indicates that the given object is not registered.
Definition: brawcap_types_shared.h:319
+
BRAWCAP_STATUS_WARNING_PENDING
@ BRAWCAP_STATUS_WARNING_PENDING
Will be returned if another operation for the same resource is pending.
Definition: brawcap_types_shared.h:266
+
BRAWCAP_STATUS_ERROR_BEYOND_MTU
@ BRAWCAP_STATUS_ERROR_BEYOND_MTU
The packet size is beyond adapter MTU.
Definition: brawcap_types_shared.h:215
+
BRAWCAP_STATUS_WARNING_CANCELED
@ BRAWCAP_STATUS_WARNING_CANCELED
Indicates that a operation was canceled.
Definition: brawcap_types_shared.h:281
+
BRAWCAP_STATUS_INFO_NOT_RUNNING
@ BRAWCAP_STATUS_INFO_NOT_RUNNING
No operation running.
Definition: brawcap_types_shared.h:305
+
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE
@ BRAWCAP_STATUS_ERROR_NOT_AVAILABLE
Function is not available.
Definition: brawcap_types_shared.h:172
+
BRAWCAP_STATUS_INFO_NO_DATA
@ BRAWCAP_STATUS_INFO_NO_DATA
Indicates that a function returns without any data.
Definition: brawcap_types_shared.h:333
+
BRAWCAP_STATUS_WARNING_DEMO_MODE
@ BRAWCAP_STATUS_WARNING_DEMO_MODE
The operation was not executed due to demo mode limitations.
Definition: brawcap_types_shared.h:256
+
BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED
@ BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED
Indicates that not all of the specified content/payload was processed.
Definition: brawcap_types_shared.h:288
+
brawcap_version_fragments_t
Struct containing the separated version parts.
Definition: brawcap_types_shared.h:381
+
brawcap_version_t
bRAWcap version.
Definition: brawcap_types_shared.h:426
+
brawcap_version_fragments_t::minor
UINT16 minor
Minor version.
Definition: brawcap_types_shared.h:407
+
brawcap_version_fragments_t::major
UINT16 major
Major version.
Definition: brawcap_types_shared.h:416
+
brawcap_version_fragments_t::patch
UINT16 patch
Patch version.
Definition: brawcap_types_shared.h:399
+
brawcap_version_fragments_t::build
UINT16 build
Build version.
Definition: brawcap_types_shared.h:390
+
brawcap_version_t::complete
UINT64 complete
Definition: brawcap_types_shared.h:428
+
brawcap_version_t::fragments
brawcap_version_fragments_t fragments
Definition: brawcap_types_shared.h:427
+
brawcap_timestamp_capabilities_t
UINT32 brawcap_timestamp_capabilities_t
Type used for indicating the supported timestamp modes.
Definition: brawcap_types_shared.h:524
+
brawcap_timestamp_t
struct _brawcap_timestamp brawcap_timestamp_t
bRAWcap timestamp object.
Definition: brawcap_types_shared.h:612
+
brawcap_timestamp_resolution_ns_t
UINT32 brawcap_timestamp_resolution_ns_t
Represents the timestamp resolution in nanoseconds.
Definition: brawcap_types_shared.h:533
+
brawcap_timestamp_mode_t
brawcap_timestamp_mode_t
List of different timestamp modes.
Definition: brawcap_types_shared.h:574
+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC
@ BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC
A high precision system timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:586
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE
A hardware timestamp created by the network adapter hardware/firmware.
Definition: brawcap_types_shared.h:602
+
BRAWCAP_TIMESTAMP_MODE_SOFTWARE
@ BRAWCAP_TIMESTAMP_MODE_SOFTWARE
A software timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:590
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM
A system timestamp created by the network adapter driver.
Definition: brawcap_types_shared.h:594
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE
A software timestamp created by the network adapter driver.
Definition: brawcap_types_shared.h:598
+
BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
@ BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
No timestamp.
Definition: brawcap_types_shared.h:578
+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
@ BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
A low precision system timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:582
+
brawcap_packet_size_t
UINT16 brawcap_packet_size_t
Type for handling the number of payload bytes per packet.
Definition: brawcap_types_shared.h:670
+
brawcap_packet_t
struct _brawcap_packet brawcap_packet_t
bRAWcap packet object.
Definition: brawcap_types_shared.h:679
+
brawcap_buffer_t
struct _brawcap_buffer brawcap_buffer_t
bRAWcap packet buffer object.
Definition: brawcap_types_shared.h:742
+
brawcap_buffer_packet_count_t
UINT32 brawcap_buffer_packet_count_t
Type for handling the number of packets which can be stored in a packet buffer.
Definition: brawcap_types_shared.h:734
+
brawcap_buffer_iterator_t
struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
bRAWcap packet buffer iterator object.
Definition: brawcap_types_shared.h:770
+
brawcap_rx_mode_t
brawcap_rx_mode_t
List of receive modes.
Definition: brawcap_types_shared.h:1053
+
brawcap_rx_min_packets_t
UINT32 brawcap_rx_min_packets_t
Type for handling the minimum amount of packets to copy before a bRAWcap receive will return....
Definition: brawcap_types_shared.h:1047
+
brawcap_rx_timeout_t
UINT16 brawcap_rx_timeout_t
Type for handling receive timeouts in number of milliseconds. The timeout specifies the maximum block...
Definition: brawcap_types_shared.h:1037
+
brawcap_rx_direction_t
brawcap_rx_direction_t
List of supported receive directions.
Definition: brawcap_types_shared.h:1074
+
BRAWCAP_RX_MODE_LIVE
@ BRAWCAP_RX_MODE_LIVE
Received packets are stored in a user created bRAWcap packet (buffer) and provided to the calling app...
Definition: brawcap_types_shared.h:1058
+
BRAWCAP_RX_MODE_DUMP
@ BRAWCAP_RX_MODE_DUMP
Received packets are directly written to disk.
Definition: brawcap_types_shared.h:1064
+
BRAWCAP_RX_DIRECTION_UNKNOWN
@ BRAWCAP_RX_DIRECTION_UNKNOWN
Stops to receive packets of any direction.
Definition: brawcap_types_shared.h:1078
+
BRAWCAP_RX_DIRECTION_IN
@ BRAWCAP_RX_DIRECTION_IN
Only received packets by the network adapter will be received.
Definition: brawcap_types_shared.h:1082
+
BRAWCAP_RX_DIRECTION_OUT
@ BRAWCAP_RX_DIRECTION_OUT
Only transmitted packets by bRAWcap or upper network stack drivers will be received....
Definition: brawcap_types_shared.h:1091
+
BRAWCAP_RX_DIRECTION_BOTH
@ BRAWCAP_RX_DIRECTION_BOTH
Both transmitted packets by bRAWcap or upper network stack drivers and received packets from the unde...
Definition: brawcap_types_shared.h:1096
+
bpf_insn
A single BPF pseudo-instruction.
Definition: brawcap_types_shared.h:947
+
bpf_program
A BPF pseudo-assembly program.
Definition: brawcap_types_shared.h:961
+
bpf_insn::jt
UCHAR jt
Definition: brawcap_types_shared.h:949
+
bpf_insn::k
UINT32 k
Definition: brawcap_types_shared.h:951
+
bpf_insn::jf
UCHAR jf
Definition: brawcap_types_shared.h:950
+
bpf_program::bf_len
UINT bf_len
Definition: brawcap_types_shared.h:962
+
bpf_program::bf_insns
struct bpf_insn * bf_insns
Definition: brawcap_types_shared.h:963
+
bpf_insn::code
USHORT code
Definition: brawcap_types_shared.h:948
+
BRAWCAP_FILTER_BYTE_MAX_LENGTH
#define BRAWCAP_FILTER_BYTE_MAX_LENGTH
The maximum supported filter byte mask length in bytes.
Definition: brawcap_types_shared.h:891
+
brawcap_filter_mask_array_t
UINT8 brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a filter byte mask.
Definition: brawcap_types_shared.h:900
+
brawcap_filter_t
struct _brawcap_filter brawcap_filter_t
bRAWcap filter object.
Definition: brawcap_types_shared.h:973
+
brawcap_filter_type_t
brawcap_filter_type_t
List of filter types.
Definition: brawcap_types_shared.h:927
+
brawcap_filter_ignore_bits_array_t
UINT8 brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a byte wise bitfield.
Definition: brawcap_types_shared.h:912
+
brawcap_filter_byte_length_t
brawcap_packet_size_t brawcap_filter_byte_length_t
Type for specifying the byte filter length.
Definition: brawcap_types_shared.h:917
+
BRAWCAP_FILTER_TYPE_BPF
@ BRAWCAP_FILTER_TYPE_BPF
A Berkley Packet Filter.
Definition: brawcap_types_shared.h:935
+
BRAWCAP_FILTER_TYPE_BYTE_MASK
@ BRAWCAP_FILTER_TYPE_BYTE_MASK
A bRAWcap byte filter.
Definition: brawcap_types_shared.h:931
+
brawcap_stats_header_t
Header describing given bRAWcap stats structure.
Definition: brawcap_types_shared.h:1241
+
brawcap_stats_rx_t
The bRAWcap receive statistics.
Definition: brawcap_types_shared.h:1303
+
brawcap_stats_tx_t
The bRAWcap transmit statistics.
Definition: brawcap_types_shared.h:1421
+
brawcap_stats_tx_t::driverInitiatedPacketsHandles
UINT64 driverInitiatedPacketsHandles
Initiated packets to transmit from bRAWcap driver itself on the corresponding adapter.
Definition: brawcap_types_shared.h:1468
+
brawcap_stats_rx_t::handleDroppedPacketsTotal
UINT64 handleDroppedPacketsTotal
The total number of packets which was dropped for the handle (sum of all reasons).
Definition: brawcap_types_shared.h:1373
+
brawcap_stats_tx_t::driverCompletedPacketsStack
UINT64 driverCompletedPacketsStack
Completed packets to transmit from the upper network stack detected by bRAWcap driver on the correspo...
Definition: brawcap_types_shared.h:1495
+
brawcap_stats_rx_t::driverReceivedPacketsTotal
UINT64 driverReceivedPacketsTotal
The total number of received packets by bRAWcap on the corresponding adapter.
Definition: brawcap_types_shared.h:1343
+
brawcap_stats_rx_t::handleReceivedPacketsMatched
UINT64 handleReceivedPacketsMatched
The total number of packets which have matched the given bRAWcap handle filter.
Definition: brawcap_types_shared.h:1353
+
brawcap_stats_tx_t::handleCompletedPacketsTotal
UINT64 handleCompletedPacketsTotal
Total number of completed transmitted packets for the handle.
Definition: brawcap_types_shared.h:1515
+
brawcap_stats_header_t::revision
BYTE revision
Indicates the revision of the stats.
Definition: brawcap_types_shared.h:1251
+
brawcap_stats_rx_t::adapterDroppedPacketsTotal
UINT64 adapterDroppedPacketsTotal
Total number of received bytes by the underlying network adapter.
Definition: brawcap_types_shared.h:1333
+
brawcap_stats_rx_t::adapterReceivedPacketsTotal
UINT64 adapterReceivedPacketsTotal
Total number of received packets by the underlying network adapter.
Definition: brawcap_types_shared.h:1319
+
brawcap_stats_tx_t::adapterCanceledPacketsTotal
UINT64 adapterCanceledPacketsTotal
Total number of canceled transmitted packets by the underlying network adapter.
Definition: brawcap_types_shared.h:1452
+
brawcap_stats_rx_t::handleReceivedPacketsDirect
UINT64 handleReceivedPacketsDirect
The total number of packets which could be directly delivered to user space memory.
Definition: brawcap_types_shared.h:1363
+
brawcap_stats_rx_t::handleReceivedPacketsQueued
UINT64 handleReceivedPacketsQueued
The total number of packets which was queued to the handles driver queue.
Definition: brawcap_types_shared.h:1358
+
brawcap_stats_rx_t::handleDroppedPacketsToLong
UINT64 handleDroppedPacketsToLong
The total number of packets which was dropped for the handle their length exceeds the handles configu...
Definition: brawcap_types_shared.h:1384
+
brawcap_stats_tx_t::driverCompletedPacketsHandles
UINT64 driverCompletedPacketsHandles
Completed packets to transmit from the bRAWcap driver itself on the corresponding adapter.
Definition: brawcap_types_shared.h:1500
+
brawcap_stats_tx_t::adapterCompletedBytesTotal
UINT64 adapterCompletedBytesTotal
Total number of (completed) transmitted bytes by the underlying network adapter.
Definition: brawcap_types_shared.h:1445
+
brawcap_stats_header_t::size
UINT16 size
Should be set to the size of the structure depending on it´s type and revision. You should use the BR...
Definition: brawcap_types_shared.h:1256
+
brawcap_stats_tx_t::driverInitiatedPacketsStack
UINT64 driverInitiatedPacketsStack
Initiated packets to transmit from upper network stack detected by bRAWcap driver on the correspondin...
Definition: brawcap_types_shared.h:1463
+
brawcap_stats_tx_t::driverInitiatedPacketsTotal
UINT64 driverInitiatedPacketsTotal
Total number of initiated packets to transmit by the bRAWcap driver on the corresponding adapter.
Definition: brawcap_types_shared.h:1457
+
brawcap_stats_tx_t::adapterCompletedPacketsTotal
UINT64 adapterCompletedPacketsTotal
Total number of (completed) transmitted packets by the underlying network adapter.
Definition: brawcap_types_shared.h:1438
+
brawcap_stats_tx_t::handleCanceledPacketsTotal
UINT64 handleCanceledPacketsTotal
Total number of canceled packets to transmit for the handle.
Definition: brawcap_types_shared.h:1510
+
brawcap_stats_header_t::type
BYTE type
Indicates which type of stats it is.
Definition: brawcap_types_shared.h:1245
+
brawcap_stats_rx_t::handleDroppedPacketsQueue
UINT64 handleDroppedPacketsQueue
The total number of packets which was dropped for the handle because of resources (driver queue overr...
Definition: brawcap_types_shared.h:1378
+
brawcap_stats_tx_t::driverCanceledPacketsTotal
UINT64 driverCanceledPacketsTotal
Total number of canceled packets to transmit by the bRAWcap driver on the corresponding adapter.
Definition: brawcap_types_shared.h:1473
+
brawcap_stats_rx_t::adapterValid
UINT32 adapterValid
Bitfield indicating which counters provided by the underlying network adapter driver are valid.
Definition: brawcap_types_shared.h:1312
+
brawcap_stats_rx_t::handleReceivedPacketsTotal
UINT64 handleReceivedPacketsTotal
The total number of received packets by the given bRAWcap handle.
Definition: brawcap_types_shared.h:1348
+
brawcap_stats_tx_t::driverCanceledPacketsHandles
UINT64 driverCanceledPacketsHandles
Canceled packets to transmit from bRAWcap driver itself on the corresponding adapter.
Definition: brawcap_types_shared.h:1484
+
brawcap_stats_rx_t::header
brawcap_stats_header_t header
Header for receive statistics. This has to be always initialized by the user after creation before us...
Definition: brawcap_types_shared.h:1308
+
brawcap_stats_tx_t::handleInitiatedPacketsTotal
UINT64 handleInitiatedPacketsTotal
Total number of initiated packets to transmit for the handle.
Definition: brawcap_types_shared.h:1505
+
brawcap_stats_rx_t::driverIndicatedPacketsTotal
UINT64 driverIndicatedPacketsTotal
The total number of indicated packets to the upper network stack by bRAWcap on the corresponding adap...
Definition: brawcap_types_shared.h:1338
+
brawcap_stats_tx_t::driverCanceledPacketsStack
UINT64 driverCanceledPacketsStack
Canceled packets to transmit from the upper network stack detected by bRAWcap driver on the correspon...
Definition: brawcap_types_shared.h:1479
+
brawcap_stats_rx_t::adapterReceivedBytesTotal
UINT64 adapterReceivedBytesTotal
Total number of received bytes by the underlying network adapter.
Definition: brawcap_types_shared.h:1326
+
brawcap_stats_rx_t::handleReceivedBytesTotal
UINT64 handleReceivedBytesTotal
The total number of received bytes by the given bRAWcap handle.
Definition: brawcap_types_shared.h:1368
+
brawcap_stats_tx_t::driverCompletedPacketsTotal
UINT64 driverCompletedPacketsTotal
Total number of completed transmitted packets detected by bRAWcap driver on the corresponding adapter...
Definition: brawcap_types_shared.h:1489
+
brawcap_stats_rx_revision_t
brawcap_stats_rx_revision_t
List of all available receive statistic revisions.
Definition: brawcap_types_shared.h:1278
+
brawcap_stats_tx_revision_t
brawcap_stats_tx_revision_t
List of all available transmit statistic revisions.
Definition: brawcap_types_shared.h:1396
+
brawcap_stats_type_t
brawcap_stats_type_t
List of all available statistic types.
Definition: brawcap_types_shared.h:1263
+
BRAWCAP_STATS_RX_REVISION_1
@ BRAWCAP_STATS_RX_REVISION_1
Revision 1 for receive stats.
Definition: brawcap_types_shared.h:1282
+
BRAWCAP_STATS_TX_REVISION_1
@ BRAWCAP_STATS_TX_REVISION_1
Revision 1 for transmit stats.
Definition: brawcap_types_shared.h:1400
+
BRAWCAP_STATS_TYPE_RX
@ BRAWCAP_STATS_TYPE_RX
Type for receive stats.
Definition: brawcap_types_shared.h:1267
+
BRAWCAP_STATS_TYPE_TX
@ BRAWCAP_STATS_TYPE_TX
Type for transmit stats.
Definition: brawcap_types_shared.h:1271
+
+ + + + + + diff --git a/sdk/c/doc/html/a00041.html b/sdk/c/doc/html/a00041.html new file mode 100644 index 0000000..4ac9832 --- /dev/null +++ b/sdk/c/doc/html/a00041.html @@ -0,0 +1,310 @@ + + + + + + + + +bRAWcap: brawcap_types_um.h File Reference + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
+Data Structures | +Macros | +Typedefs | +Enumerations
+
brawcap_types_um.h File Reference
+
+
+ +

bRAWcap API - User mode types. +More...

+
#include "brawcap_types_shared.h"
+
+

Go to the source code of this file.

+ + + + + + + + +

+Data Structures

union  brawcap_adapter_ipv4_t
 IPv4 address. More...
 
union  brawcap_adapter_ipv6_t
 IPv6 address. More...
 
+ + + + + + + + + + + + + +

+Macros

+#define _BRAWCAP_API_FUNC(returnType)   __declspec(dllimport) returnType __cdecl
 Dynamic/automatic function import for loading/including.
 
+#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.
 
#define BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX   2
 Max number of supported packet (receive) buffers per bRAWcap handle.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Typedefs

typedef struct _brawcap_handle brawcap_handle_t
 A bRAWcap handle.
 
+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.
 
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.
 
typedef void(* brawcap_tx_callback_t) (brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)
 Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has finished.
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Enumerations

enum  brawcap_log_level_t {
+  BRAWCAP_LOG_LEVEL_DEBUG = 0x01 +,
+  BRAWCAP_LOG_LEVEL_VERBOSE = 0x02 +,
+  BRAWCAP_LOG_LEVEL_NOTICE = 0x04 +,
+  BRAWCAP_LOG_LEVEL_WARNING = 0x08 +,
+  BRAWCAP_LOG_LEVEL_ERROR = 0x10 +
+ }
 List of bRAWcap log levels. More...
 
enum  brawcap_log_type_t {
+  BRAWCAP_LOG_TYPE_GENERIC = 0x01 +,
+  BRAWCAP_LOG_TYPE_ADAPTER = 0x02 +,
+  BRAWCAP_LOG_TYPE_RECEIVE = 0x04 +,
+  BRAWCAP_LOG_TYPE_TRANSMIT = 0x08 +,
+  BRAWCAP_LOG_TYPE_LICENSE = 0x10 +,
+  BRAWCAP_LOG_TYPE_ALL = 0xFFFF +
+ }
 List of bRAWcap log types. More...
 
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...
 
+

Detailed Description

+

bRAWcap API - User mode types.

+

The file includes all (data)types and defines used for bRAWcap (user space only).

+
Copyright
© 2021 - b-plus technologies GmbH. All rights reserved!
+

All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.

+

Redistribution in source or any other form, with or without modification, is not permitted.

+

You may use this code under the according license terms of b-plus. Please contact b-plus at servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m to get the appropriate terms and conditions.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00041_source.html b/sdk/c/doc/html/a00041_source.html new file mode 100644 index 0000000..184bafe --- /dev/null +++ b/sdk/c/doc/html/a00041_source.html @@ -0,0 +1,702 @@ + + + + + + + + +bRAWcap: brawcap_types_um.h Source File + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + + +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ + +
+
+
brawcap_types_um.h
+
+
+Go to the documentation of this file.
1/**
+
2 * @file brawcap_types_um.h
+
3 *
+
4 * @brief bRAWcap API - User mode types.
+
5 *
+
6 * The file includes all (data)types and defines used for bRAWcap (user space only).
+
7 *
+
8 * @copyright
+
9 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
10 *
+
11 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
12 *
+
13 * Redistribution in source or any other form, with or without modification, is not permitted.
+
14 *
+
15 *
+
16 * You may use this code under the according license terms of b-plus. Please contact b-plus at services@b-plus.com
+
17 * to get the appropriate terms and conditions.
+
18 */
+
19#ifndef BRAWCAP_TYPES_UM_H
+
20#define BRAWCAP_TYPES_UM_H
+
21
+
22#include "brawcap_types_shared.h"
+
23
+
24/**************************************************** LIB ************************************************************/
+
25#if 1
+
26/**
+
27 * @defgroup brawcap_lib Importing
+
28 * @brief Defines required for automatic/dynamic bRAWcap API function importing.
+
29 * @{
+
30 */
+
31
+
32// You should never define _BRAWCAP_EXPORT when including bRAWcap.
+
33#ifdef _BRAWCAP_EXPORT
+
34 /**
+
35 * @internal
+
36 * @brief Dynamic/automatic function export when compiling bRAWcap itself.
+
37 * @warning Only required when building the bRAWcap library.
+
38 * Should never be defined if you include bRAWcap.
+
39 */
+
40 #define _BRAWCAP_API_FUNC(returnType) __declspec(dllexport) returnType __cdecl
+
41#else
+
42 /**
+
43 * @brief Dynamic/automatic function import for loading/including.
+
44 */
+
45 #define _BRAWCAP_API_FUNC(returnType) __declspec(dllimport) returnType __cdecl
+
46#endif
+
47
+
48/**@}*/
+
49#endif
+
50
+
51/************************************************ LOGGING ************************************************************/
+
52#if 1
+
53/**
+
54 * @defgroup brawcap_logging Logging
+
55 * @brief Types and functions for handling/modifying the bRAWcap logging.
+
56 *
+
57 * This module provides some functions for configuring the bRAWcap logging behavior.
+
58 * The bRAWcap logger supports different log levels and types, which allows to configure the logging for specific
+
59 * types independent to each other.
+
60 * Increasing the log level may help during development of the user application which shall use bRAWcap.
+
61 *
+
62 * @note If you think there is a problem with bRAWcap, please enable detailed logging,
+
63 * run your application until the problem occurs and then send the created bRAWcap log files to b-plus.
+
64 *
+
65 * @attention For release builds log levels such as verbose shall be avoided, because they can lead to performance
+
66 * degradation.
+
67 * @{
+
68 */
+
69
+
70/**
+
71 * @brief List of bRAWcap log levels.
+
72 *
+
73 * The log levels allows to (de)activate additional log entries.
+
74 * This can be especially useful during development, to get a more detailed log from bRAWcap.
+
75 */
+
76typedef enum _brawcap_log_level
+
77{
+
78 /**
+
79 * @brief Debug log level is for debugging bRAWcap itself only.
+
80 * Therefore it can only be enabled if the application is registered with higher privilege.
+
81 *
+
82 * @note Default: Deactivated
+
83 */
+
84 BRAWCAP_LOG_LEVEL_DEBUG = 0x01,
+
85 /**
+
86 * @brief Verbose log level will include many informative loggings.
+
87 * Those loggings gives more info why some API calls may fail.
+
88 * This will especially contain those cases in which the caller has provided invalid parameters.
+
89 * It should be activated only for development, testing or error research.
+
90 *
+
91 * @note Default: Deactivated
+
92 */
+
93 BRAWCAP_LOG_LEVEL_VERBOSE = 0x02,
+
94 /**
+
95 * @brief Notice log level will include some loggings which gives information of the current bRAWcap state.
+
96 * This may be disabled to decrease logging to a minimum.
+
97 *
+
98 * @note Default: Activated
+
99 */
+
100 BRAWCAP_LOG_LEVEL_NOTICE = 0x04,
+
101 /**
+
102 * @brief Warning log level will include loggings for unexpected states.
+
103 * This level should never be disabled.
+
104 *
+
105 * @note Default: Activated
+
106 */
+
107 BRAWCAP_LOG_LEVEL_WARNING = 0x08,
+
108 /**
+
109 * @brief Error log level will include loggings if something went completely wrong and bRAWcap could not solve
+
110 * the issue.
+
111 * Those loggings should never appear, if so bRAWcap may be in a invalid state.
+
112 * If loggings contain such a logentry please try to reproduce it again with all log levels enabled
+
113 * and send the logfile (with a short description of how to reproduce it) to b-plus.
+
114 * This should really never be disabled.
+
115 *
+
116 * @note Default: Activated
+
117 */
+
118 BRAWCAP_LOG_LEVEL_ERROR = 0x10
+
119}brawcap_log_level_t;
+
120
+
121/**
+
122 * @brief List of bRAWcap log types.
+
123 *
+
124 * The log types allows to adjust log levels for each type independent.
+
125 * To distinguish between different types each logentry will be prefixed with it´s type, this increases the readability
+
126 * of the logfile.
+
127 */
+
128typedef enum _brawcap_log_type
+
129{
+
130 /**
+
131 * @brief Generic loggings will be used for everything which has no specific type.
+
132 */
+
133 BRAWCAP_LOG_TYPE_GENERIC = 0x01,
+
134 /**
+
135 * @brief Adapter loggings will be used for anything which relates to the local adapter handling.
+
136 */
+
137 BRAWCAP_LOG_TYPE_ADAPTER = 0x02,
+
138 /**
+
139 * @brief Receive loggings will be used for anything which relates to receiving.
+
140 */
+
141 BRAWCAP_LOG_TYPE_RECEIVE = 0x04,
+
142 /**
+
143 * @brief Transmit loggings will be used for anything which relates to transmitting.
+
144 */
+
145 BRAWCAP_LOG_TYPE_TRANSMIT = 0x08,
+
146 /**
+
147 * @brief License loggings will be used for anything which relates to licensing.
+
148 */
+
149 BRAWCAP_LOG_TYPE_LICENSE = 0x10,
+
150
+
151 BRAWCAP_LOG_TYPE_ALL = 0xFFFF
+
152}brawcap_log_type_t;
+
153
+
154/**@}*/
+
155#endif
+
156
+
157/************************************************ GENERIC ************************************************************/
+
158#if 1
+
159/**
+
160 * @addtogroup brawcap_generics
+
161 * @{
+
162 */
+
163
+
164/**
+
165 * @brief A bRAWcap handle.
+
166 *
+
167 * It can be @ref brawcap_open "created/opened" and @ref brawcap_close "deleted/closed".
+
168 * In general every function which communicates with the bRAWcap driver requires a open bRAWcap handle.
+
169 *
+
170 * @attention The number of bRAWcap handles per adapter is limited to @ref BRAWCAP_HANDLES_PER_ADAPTER_MAX.
+
171 * If this limit is reached each additional open on that adapter will fail.
+
172 */
+
173typedef struct _brawcap_handle brawcap_handle_t;
+
174
+
175/**@}*/
+
176#endif
+
177
+
178/*********************************************** TIMESTAMP ***********************************************************/
+
179#if 1
+
180/**
+
181 * @addtogroup brawcap_timestamp
+
182 * @{
+
183 */
+
184
+
185/**@}*/
+
186#endif
+
187
+
188/************************************************ PACKET *************************************************************/
+
189#if 1
+
190/**
+
191 * @addtogroup brawcap_packet
+
192 * @{
+
193 */
+
194
+
195/**@}*/
+
196#endif
+
197
+
198/************************************************* BUFFER *************************************************************/
+
199#if 1
+
200/**
+
201 * @addtogroup brawcap_buffer
+
202 * @{
+
203 */
+
204
+
205/********************************************* BUFFER ITERATOR ********************************************************/
+
206#if 1
+
207/**
+
208 * @addtogroup brawcap_buffer_iterator
+
209 * @{
+
210 */
+
211
+
212/**@}*/
+
213#endif
+
214
+
215/**@}*/
+
216#endif
+
217
+
218/************************************************** ADAPTER **********************************************************/
+
219#if 1
+
220/**
+
221 * @addtogroup brawcap_adapter
+
222 * @{
+
223 */
+
224
+
225/**
+
226 * @brief Required number of bytes for describing a MAC address.
+
227 * The defined length does not containing any delimiters, it represents the number of MAC address digits.
+
228 */
+
229#define BRAWCAP_ADAPTER_MAC_LENGTH 6
+
230
+
231/**
+
232 * @brief The max supported length for an adapter name.
+
233 *
+
234 * @note On Windows a adapter name always corresponds to it´s GUID.
+
235 * Those GUIDs have a fixed length.
+
236 */
+
237#define BRAWCAP_ADAPTER_NAME_LENGTH 40
+
238
+
239/**
+
240 * @brief Type used for counting the available/supported adapters on a machine.
+
241 */
+
242typedef UINT8 brawcap_adapter_count_t;
+
243
+
244/**
+
245 * @brief Fixed size array describing a MAC address.
+
246 *
+
247 * The array only contains the MAC address digits without any delimiters.
+
248 */
+
249typedef UINT8 brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH];
+
250
+
251/**
+
252 * @brief Fixed size array containing a adapter name.
+
253 *
+
254 * @note On Windows a adapter name corresponds always to it´s GUID.
+
255 * Textual GUIDs always have the format "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
+
256 */
+
257typedef char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH];
+
258
+
259/**
+
260 * @brief IPv4 address.
+
261 */
+
262typedef union _brawcap_adapter_ipv4
+
263{
+
264 UINT8 bytes[4]; /*!< IPv4 address as byte array. */
+
265 UINT16 words[2]; /*!< IPv4 address as word array (each element has two Bytes). */
+
266 UINT32 addr; /*!< IPv4 address as single integer value. */
+
267} brawcap_adapter_ipv4_t;
+
268
+
269/**
+
270 * @brief IPv6 address.
+
271 */
+
272typedef union _brawcap_adapter_ipv6
+
273{
+
274 UINT8 bytes[16]; /*!< IPv6 address as byte array. */
+
275 UINT16 words[8]; /*!< IPv6 address as word array (each element has two Bytes). */
+
276 UINT64 qwords[2]; /*!< IPv6 address as large word array (each element has eight Bytes). */
+
277} brawcap_adapter_ipv6_t;
+
278
+
279/**
+
280 * @brief List of bRAWcap adapter speeds.
+
281 * Values indicating the current adapter uplink speed.
+
282 *
+
283 * @note The speed should be always equal for rx and tx,
+
284 * but both can be requested independent of each other.
+
285 */
+
286typedef enum _brawcap_adapter_speed
+
287{
+
288 BRAWCAP_ADAPTER_SPEED_UNKNOWN = 0ULL, /*!< Speed unknown */
+
289 BRAWCAP_ADAPTER_SPEED_10M = 10ULL, /*!< 10 MBit/s */
+
290 BRAWCAP_ADAPTER_SPEED_100M = 100ULL, /*!< 100 MBit/s */
+
291 BRAWCAP_ADAPTER_SPEED_1G = 1000ULL, /*!< 1 GBit/s */
+
292 BRAWCAP_ADAPTER_SPEED_2_5G = 2500ULL, /*!< 2,5 GBit/s */
+
293 BRAWCAP_ADAPTER_SPEED_5G = 5000ULL, /*!< 5 GBit/s */
+
294 BRAWCAP_ADAPTER_SPEED_10G = 10000ULL, /*!< 10 GBit/s*/
+
295 BRAWCAP_ADAPTER_SPEED_25G = 25000ULL, /*!< 25 GBit/s */
+
296 BRAWCAP_ADAPTER_SPEED_40G = 40000ULL, /*!< 40 GBit/s */
+
297 BRAWCAP_ADAPTER_SPEED_50G = 50000ULL, /*!< 50 GBit/s */
+
298 BRAWCAP_ADAPTER_SPEED_100G = 100000ULL /*!< 100 GBit/s */
+
299} brawcap_adapter_speed_t;
+
300
+
301/**
+
302 * @brief List of adapter connection states.
+
303 * Values indicating the current adapter connection state (uplink/cable connected).
+
304 */
+
305typedef enum _brawcap_adapter_connection_state
+
306{
+
307 BRAWCAP_ADAPTER_CONNECTION_UNKNOWN = 0, /*!< Connection state unknown. */
+
308 BRAWCAP_ADAPTER_CONNECTION_UP = 1, /*!< Connection is up (uplink/cable connected). */
+
309 BRAWCAP_ADAPTER_CONNECTION_DOWN = 2 /*!< Connection is down (cable not connected). */
+
310}brawcap_adapter_connection_state_t;
+
311
+
312/**
+
313 * @brief List of adapter operation states.
+
314 * Values indicating the current adapter operation state (adapter driver status).
+
315 */
+
316typedef enum _brawcap_adapter_operation_state
+
317{
+
318 BRAWCAP_ADAPTER_OPERATION_UNKNOWN = 0, /*!< Operation state unknown. */
+
319 BRAWCAP_ADAPTER_OPERATION_UP = 1, /*!< Adapter is running (driver activated). */
+
320 BRAWCAP_ADAPTER_OPERATION_DOWN = 2, /*!< Adapter is down/disabled (driver deactivated). */
+
321 BRAWCAP_ADAPTER_OPERATION_TESTING = 3 /*!< Adapter is in probing state. */
+
322}brawcap_adapter_operation_state_t;
+
323
+
324/**
+
325 * @brief Type for handling the adapter maximum transmission unit (MTU).
+
326 *
+
327 * It describes the maximum bytes per packet which can be received/transmitted on the adapter.
+
328 * Typical values are 1500 bytes for default sized Ethernet and 9000 bytes for jumbo frames.
+
329 *
+
330 * @note In general the MTU does not contain the Ethernet header (14 Bytes).
+
331 * If something like 1514/9014 is displayed by the adapter driver it contains the Ethernet header.
+
332 * If VLAN tagging is activated, VLAN packets require 4 additional bytes for each VLAN tag.
+
333 * There is also a 4 Byte FCS - defined by Ethernet - added to each packet (done by the network adapter).
+
334 * For example a full sized Jumbo Packet with one VLAN Tag can have:
+
335 * 14 Bytes Ethernet header + 4 Bytes VLAN Tag + 9000 Bytes Payload + 4 Bytes FCS = 9022 Bytes.
+
336 */
+
337typedef UINT64 brawcap_adapter_mtu_t;
+
338
+
339/**
+
340 * @brief List of reasons for adapter change notifications.
+
341 * This values indicate why a adapter change notification is received.
+
342 */
+
343typedef enum _brawcap_adapter_notify_reason
+
344{
+
345 /**
+
346 * @brief The notification reason is unknown.
+
347 */
+
348 BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN = 0,
+
349 /**
+
350 * @brief A new bRAWcap adapter was detected.
+
351 * E.g. due to enabling bRAWcap driver on an adapter where it was disabled before.
+
352 */
+
353 BRAWCAP_ADAPTER_NOTIFY_REASON_ADD = 1,
+
354 /**
+
355 * @brief A bRAWcap adapter was removed.
+
356 * E.g. due to disabling bRAWcap driver on an adapter where it was enabled before.
+
357 */
+
358 BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE = 2,
+
359 /**
+
360 * @brief A adapter property has changed.
+
361 * This can have several reasons, for a list of all properties see @ref brawcap_adapter_properties_t.
+
362 */
+
363 BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE = 3
+
364}brawcap_adapter_notify_reason_t;
+
365
+
366/**
+
367 * @brief List of adapter properties.
+
368 * They are used to identify adapter change notifications with a property change reason.
+
369 *
+
370 * @note The property values allow to store several properties in a single bitfield.
+
371 * This makes it possible to indicate several property changes with only one notification.
+
372 */
+
373typedef enum _brawcap_adapter_properties
+
374{
+
375 BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME = 0x0001, /*!< Adapter friendly name changed. */
+
376 BRAWCAP_ADAPTER_PROPERTY_RX_SPEED = 0x0002, /*!< Adapter receive speed changed. */
+
377 BRAWCAP_ADAPTER_PROPERTY_TX_SPEED = 0x0004, /*!< Adapter transmit speed changed. */
+
378 BRAWCAP_ADAPTER_PROPERTY_MTU = 0x0008, /*!< Adapter max transmission unit changed. */
+
379 BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE = 0x0010, /*!< Adapter operation state changed. */
+
380 BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE = 0x0020, /*!< Adapter connection state changed. */
+
381 BRAWCAP_ADAPTER_PROPERTY_IPV4 = 0x0040, /*!< Adapter IPv4 address changed. */
+
382 BRAWCAP_ADAPTER_PROPERTY_IPV6 = 0x0080 /*!< Adapter IPv6 address changed. */
+
383}brawcap_adapter_properties_t;
+
384
+
385/**
+
386 * @brief The general callback for adapter change notifications.
+
387 * It will be called each time a available and supported adapter change is detected.
+
388 *
+
389 * @attention Each application can only register for this callback once.
+
390 *
+
391 * @param[in] name The adapter name on which the change happened.
+
392 *
+
393 * @param[in] reason The reason/type of change (see @ref brawcap_adapter_notify_reason_t).
+
394 *
+
395 * @param[in] properties A bit field with the properties that have changed (see @ref brawcap_adapter_properties_t).
+
396 *
+
397 * @param[in] pUser Pointer to a user defined context.
+
398 * It allows access to user specific data within the callback.
+
399 */
+
400typedef void (*brawcap_adapter_notify_callback_t)(const brawcap_adapter_name_t name,
+
401 const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void* pUser);
+
402
+
403/**
+
404 * @brief The per handle callback for adapter change notifications.
+
405 * It will be called each time a change for the handle underlying adapter (and only for this adapter) is detected.
+
406 *
+
407 * @attention Each handle can register for this callback once.
+
408 *
+
409 * @param[in] pHandle The handle for which the adapter change notification was registered.
+
410 *
+
411 * @param[in] reason The reason/type of change (see @ref brawcap_adapter_notify_reason_t).
+
412 *
+
413 * @param[in] properties A bit field with the properties that have changed (see @ref brawcap_adapter_properties_t).
+
414 *
+
415 * @param[in] pUser Pointer to a user defined context.
+
416 * It allows access to user specific data within the callback.
+
417 */
+
418typedef void (*brawcap_adapter_notify_handle_callback_t)(brawcap_handle_t* const pHandle,
+
419 const brawcap_adapter_notify_reason_t reason, const UINT32 properties, void* pUser);
+
420
+
421/**@}*/
+
422#endif
+
423
+
424/************************************************** RECEIVE **********************************************************/
+
425#if 1
+
426/**
+
427 * @addtogroup brawcap_receive
+
428 * @{
+
429 */
+
430
+
431/********************************************** RECEIVE FILTER *******************************************************/
+
432#if 1
+
433/**
+
434 * @addtogroup brawcap_filter
+
435 * @{
+
436 */
+
437
+
438/**@}*/
+
439#endif
+
440
+
441/**
+
442 * @brief Max number of supported packet (receive) buffers per bRAWcap handle.
+
443 *
+
444 * Limits the number of buffers which can be attached to a single handle with @ref brawcap_rx_buffer_attach.
+
445 */
+
446#define BRAWCAP_RX_BUFFERS_PER_HANDLE_MAX 2
+
447
+
448/**
+
449 * @brief Receive callback which is called each time a receive has finished.
+
450 * Receiving can be started with @ref brawcap_rx_start and has to be stopped with @ref brawcap_rx_stop.
+
451 * Before anything can be received it is necessary to attach packet buffers to the bRAWcap handle.
+
452 * This can be done by creating new bRAWcap buffers (@ref brawcap_buffer_create) and attach it with
+
453 * @ref brawcap_rx_buffer_attach.
+
454 *
+
455 * @note If a handle has multiple buffers attached, the callback may be called in parallel (by different threads).
+
456 *
+
457 * @warning Executing to long in the callback can lead to a bottleneck in reception!
+
458 * It is recommended that the driver always has at least one (free) buffer were it can store the packets to.
+
459 *
+
460 * @param[in] pHandle Handle on which the receive returned.
+
461 *
+
462 * @param[in] status The overall receive status see @ref brawcap_status_t for possible return values.
+
463 *
+
464 * @param[in] pBuffer Pointer to the buffer which has finished receiving.
+
465 * It can be used to access all packets in the buffer and allows to retrieve information
+
466 * for each received packet (e.g. payload, length, timestamp, ...).
+
467 *
+
468 * @param[in] pUser Pointer to a user defined context.
+
469 * It allows access to user specific data within the callback.
+
470 */
+
471typedef void (*brawcap_rx_callback_t)(brawcap_handle_t* const pHandle, const brawcap_status_t status,
+
472 brawcap_buffer_t* const pBuffer, void* pUser);
+
473
+
474/**@}*/
+
475#endif
+
476
+
477/************************************************* TRANSMIT **********************************************************/
+
478#if 1
+
479/**
+
480 * @addtogroup brawcap_transmit
+
481 * @{
+
482 */
+
483
+
484/**
+
485 * @brief Transmit callback which is called each time a transmission initiated with @ref brawcap_tx_buffer_send has
+
486 * finished.
+
487 *
+
488 * @note Before any buffer can be transmitted the tranmission has to be started with @ref brawcap_tx_start and
+
489 * stopped with @ref brawcap_tx_stop.
+
490 *
+
491 * @param[in] pHandle Handle on which the transmission has finished.
+
492 *
+
493 * @param[in] status The overall transmission status see @ref brawcap_status_t for possible return values.
+
494 *
+
495 * @param[in] pBuffer Pointer to the buffer which has finished transmission (initiated with
+
496 * @ref brawcap_tx_buffer_send). It can be used to access all packets in the buffer - after transmission - and allows
+
497 * to retrieve information about each packet (e.g. (transmission) status, timestamp, ...).
+
498 *
+
499 * @param[in] pUser Pointer to a user defined context (allows access to user specific data within the callback).
+
500 */
+
501typedef void (*brawcap_tx_callback_t)(brawcap_handle_t* const pHandle, const brawcap_status_t status,
+
502 brawcap_buffer_t* const pBuffer, void* pUser);
+
503
+
504/**@}*/
+
505#endif
+
506
+
507/*************************************************** STATS ***********************************************************/
+
508#if 1
+
509/**
+
510 * @addtogroup brawcap_stats
+
511 * @{
+
512 */
+
513
+
514/**@}*/
+
515#endif
+
516
+
517#endif // BRAWCAP_TYPES_UM_H
+
brawcap_types_shared.h
bRAWcap API - Shared types.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
brawcap_buffer_t
struct _brawcap_buffer brawcap_buffer_t
bRAWcap packet buffer object.
Definition: brawcap_types_shared.h:742
+
brawcap_adapter_ipv4_t
IPv4 address.
Definition: brawcap_types_um.h:263
+
brawcap_adapter_ipv6_t
IPv6 address.
Definition: brawcap_types_um.h:273
+
brawcap_adapter_ipv4_t::addr
UINT32 addr
Definition: brawcap_types_um.h:266
+
BRAWCAP_ADAPTER_NAME_LENGTH
#define BRAWCAP_ADAPTER_NAME_LENGTH
The max supported length for an adapter name.
Definition: brawcap_types_um.h:237
+
brawcap_adapter_properties_t
brawcap_adapter_properties_t
List of adapter properties. They are used to identify adapter change notifications with a property ch...
Definition: brawcap_types_um.h:374
+
brawcap_adapter_notify_handle_callback_t
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 th...
Definition: brawcap_types_um.h:418
+
brawcap_adapter_mac_t
UINT8 brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH]
Fixed size array describing a MAC address.
Definition: brawcap_types_um.h:249
+
brawcap_adapter_connection_state_t
brawcap_adapter_connection_state_t
List of adapter connection states. Values indicating the current adapter connection state (uplink/cab...
Definition: brawcap_types_um.h:306
+
brawcap_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_speed_t
brawcap_adapter_speed_t
List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed.
Definition: brawcap_types_um.h:287
+
brawcap_adapter_notify_callback_t
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 su...
Definition: brawcap_types_um.h:400
+
brawcap_adapter_operation_state_t
brawcap_adapter_operation_state_t
List of adapter operation states. Values indicating the current adapter operation state (adapter driv...
Definition: brawcap_types_um.h:317
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
BRAWCAP_ADAPTER_MAC_LENGTH
#define BRAWCAP_ADAPTER_MAC_LENGTH
Required number of bytes for describing a MAC address. The defined length does not containing any del...
Definition: brawcap_types_um.h:229
+
brawcap_adapter_notify_reason_t
brawcap_adapter_notify_reason_t
List of reasons for adapter change notifications. This values indicate why a adapter change notificat...
Definition: brawcap_types_um.h:344
+
brawcap_adapter_mtu_t
UINT64 brawcap_adapter_mtu_t
Type for handling the adapter maximum transmission unit (MTU).
Definition: brawcap_types_um.h:337
+
BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE
@ BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE
Definition: brawcap_types_um.h:380
+
BRAWCAP_ADAPTER_PROPERTY_IPV6
@ BRAWCAP_ADAPTER_PROPERTY_IPV6
Definition: brawcap_types_um.h:382
+
BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE
@ BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE
Definition: brawcap_types_um.h:379
+
BRAWCAP_ADAPTER_PROPERTY_RX_SPEED
@ BRAWCAP_ADAPTER_PROPERTY_RX_SPEED
Definition: brawcap_types_um.h:376
+
BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME
@ BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME
Definition: brawcap_types_um.h:375
+
BRAWCAP_ADAPTER_PROPERTY_IPV4
@ BRAWCAP_ADAPTER_PROPERTY_IPV4
Definition: brawcap_types_um.h:381
+
BRAWCAP_ADAPTER_PROPERTY_TX_SPEED
@ BRAWCAP_ADAPTER_PROPERTY_TX_SPEED
Definition: brawcap_types_um.h:377
+
BRAWCAP_ADAPTER_PROPERTY_MTU
@ BRAWCAP_ADAPTER_PROPERTY_MTU
Definition: brawcap_types_um.h:378
+
BRAWCAP_ADAPTER_CONNECTION_UP
@ BRAWCAP_ADAPTER_CONNECTION_UP
Definition: brawcap_types_um.h:308
+
BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
@ BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
Definition: brawcap_types_um.h:307
+
BRAWCAP_ADAPTER_CONNECTION_DOWN
@ BRAWCAP_ADAPTER_CONNECTION_DOWN
Definition: brawcap_types_um.h:309
+
BRAWCAP_ADAPTER_SPEED_5G
@ BRAWCAP_ADAPTER_SPEED_5G
Definition: brawcap_types_um.h:293
+
BRAWCAP_ADAPTER_SPEED_100G
@ BRAWCAP_ADAPTER_SPEED_100G
Definition: brawcap_types_um.h:298
+
BRAWCAP_ADAPTER_SPEED_2_5G
@ BRAWCAP_ADAPTER_SPEED_2_5G
Definition: brawcap_types_um.h:292
+
BRAWCAP_ADAPTER_SPEED_10G
@ BRAWCAP_ADAPTER_SPEED_10G
Definition: brawcap_types_um.h:294
+
BRAWCAP_ADAPTER_SPEED_100M
@ BRAWCAP_ADAPTER_SPEED_100M
Definition: brawcap_types_um.h:290
+
BRAWCAP_ADAPTER_SPEED_40G
@ BRAWCAP_ADAPTER_SPEED_40G
Definition: brawcap_types_um.h:296
+
BRAWCAP_ADAPTER_SPEED_10M
@ BRAWCAP_ADAPTER_SPEED_10M
Definition: brawcap_types_um.h:289
+
BRAWCAP_ADAPTER_SPEED_25G
@ BRAWCAP_ADAPTER_SPEED_25G
Definition: brawcap_types_um.h:295
+
BRAWCAP_ADAPTER_SPEED_UNKNOWN
@ BRAWCAP_ADAPTER_SPEED_UNKNOWN
Definition: brawcap_types_um.h:288
+
BRAWCAP_ADAPTER_SPEED_50G
@ BRAWCAP_ADAPTER_SPEED_50G
Definition: brawcap_types_um.h:297
+
BRAWCAP_ADAPTER_SPEED_1G
@ BRAWCAP_ADAPTER_SPEED_1G
Definition: brawcap_types_um.h:291
+
BRAWCAP_ADAPTER_OPERATION_DOWN
@ BRAWCAP_ADAPTER_OPERATION_DOWN
Definition: brawcap_types_um.h:320
+
BRAWCAP_ADAPTER_OPERATION_UNKNOWN
@ BRAWCAP_ADAPTER_OPERATION_UNKNOWN
Definition: brawcap_types_um.h:318
+
BRAWCAP_ADAPTER_OPERATION_TESTING
@ BRAWCAP_ADAPTER_OPERATION_TESTING
Definition: brawcap_types_um.h:321
+
BRAWCAP_ADAPTER_OPERATION_UP
@ BRAWCAP_ADAPTER_OPERATION_UP
Definition: brawcap_types_um.h:319
+
BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE
@ BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE
A adapter property has changed. This can have several reasons, for a list of all properties see brawc...
Definition: brawcap_types_um.h:363
+
BRAWCAP_ADAPTER_NOTIFY_REASON_ADD
@ BRAWCAP_ADAPTER_NOTIFY_REASON_ADD
A new bRAWcap adapter was detected. E.g. due to enabling bRAWcap driver on an adapter where it was di...
Definition: brawcap_types_um.h:353
+
BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE
@ BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE
A bRAWcap adapter was removed. E.g. due to disabling bRAWcap driver on an adapter where it was enable...
Definition: brawcap_types_um.h:358
+
BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN
@ BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN
The notification reason is unknown.
Definition: brawcap_types_um.h:348
+
brawcap_rx_callback_t
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 braw...
Definition: brawcap_types_um.h:471
+
brawcap_tx_callback_t
void(* brawcap_tx_callback_t)(brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)
Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has ...
Definition: brawcap_types_um.h:501
+
brawcap_log_type_t
brawcap_log_type_t
List of bRAWcap log types.
Definition: brawcap_types_um.h:129
+
brawcap_log_level_t
brawcap_log_level_t
List of bRAWcap log levels.
Definition: brawcap_types_um.h:77
+
BRAWCAP_LOG_TYPE_GENERIC
@ BRAWCAP_LOG_TYPE_GENERIC
Generic loggings will be used for everything which has no specific type.
Definition: brawcap_types_um.h:133
+
BRAWCAP_LOG_TYPE_LICENSE
@ BRAWCAP_LOG_TYPE_LICENSE
License loggings will be used for anything which relates to licensing.
Definition: brawcap_types_um.h:149
+
BRAWCAP_LOG_TYPE_TRANSMIT
@ BRAWCAP_LOG_TYPE_TRANSMIT
Transmit loggings will be used for anything which relates to transmitting.
Definition: brawcap_types_um.h:145
+
BRAWCAP_LOG_TYPE_ADAPTER
@ BRAWCAP_LOG_TYPE_ADAPTER
Adapter loggings will be used for anything which relates to the local adapter handling.
Definition: brawcap_types_um.h:137
+
BRAWCAP_LOG_TYPE_RECEIVE
@ BRAWCAP_LOG_TYPE_RECEIVE
Receive loggings will be used for anything which relates to receiving.
Definition: brawcap_types_um.h:141
+
BRAWCAP_LOG_LEVEL_WARNING
@ BRAWCAP_LOG_LEVEL_WARNING
Warning log level will include loggings for unexpected states. This level should never be disabled.
Definition: brawcap_types_um.h:107
+
BRAWCAP_LOG_LEVEL_ERROR
@ BRAWCAP_LOG_LEVEL_ERROR
Error log level will include loggings if something went completely wrong and bRAWcap could not solve ...
Definition: brawcap_types_um.h:118
+
BRAWCAP_LOG_LEVEL_DEBUG
@ BRAWCAP_LOG_LEVEL_DEBUG
Debug log level is for debugging bRAWcap itself only. Therefore it can only be enabled if the applica...
Definition: brawcap_types_um.h:84
+
BRAWCAP_LOG_LEVEL_VERBOSE
@ BRAWCAP_LOG_LEVEL_VERBOSE
Verbose log level will include many informative loggings. Those loggings gives more info why some API...
Definition: brawcap_types_um.h:93
+
BRAWCAP_LOG_LEVEL_NOTICE
@ BRAWCAP_LOG_LEVEL_NOTICE
Notice log level will include some loggings which gives information of the current bRAWcap state....
Definition: brawcap_types_um.h:100
+
+ + + + + + diff --git a/sdk/c/doc/html/a00047.html b/sdk/c/doc/html/a00047.html new file mode 100644 index 0000000..d02bc91 --- /dev/null +++ b/sdk/c/doc/html/a00047.html @@ -0,0 +1,327 @@ + + + + + + + + +bRAWcap: Generics + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros | +Typedefs | +Functions
+
Generics
+
+
+ +

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:

    +
  1. Handle Opener
    2. +
+

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:

+
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]nameThe name of the adapter to open a bRAWcap handle.
[out]pHandleWill 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.
+
Parameters
+ + +
[in]pHandlebRAWcap handle to be closed.
+
+
+
Returns
+ + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_FAILED A system error occurred.
+
+
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.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00048.html b/sdk/c/doc/html/a00048.html new file mode 100644 index 0000000..980cae4 --- /dev/null +++ b/sdk/c/doc/html/a00048.html @@ -0,0 +1,356 @@ + + + + + + + + +bRAWcap: Status + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros | +Enumerations | +Functions
+
Status
+
+
+ +

Contains all status/return codes of bRAWcap. +More...

+ + + + + + + + + + + + + + +

+Macros

+#define BRAWCAP_SUCCESS(status)   (status == 0)
 Checks if the returned status indicates a success with no additional info.
 
+#define BRAWCAP_ERROR(status)   (status < 0)
 Checks if the returned status is a error.
 
+#define BRAWCAP_WARNING(status)   (status > 0 && status < 2000)
 Checks if the returned status is a warning.
 
+#define BRAWCAP_INFO(status)   (status >= 2000 && status < 4000)
 Checks if the returned status is a info.
 
+ + + + +

+Enumerations

enum  brawcap_status_t {
+  BRAWCAP_STATUS_SUCCESS = 0 +,
+  BRAWCAP_STATUS_ERROR_FAILED = -1 +,
+  BRAWCAP_STATUS_ERROR_NOT_AVAILABLE = -2 +,
+  BRAWCAP_STATUS_ERROR_INVALID_POINTER = -3 +,
+  BRAWCAP_STATUS_ERROR_INVALID_PARAM = -4 +,
+  BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE = -5 +,
+  BRAWCAP_STATUS_ERROR_NOT_FOUND = -6 +,
+  BRAWCAP_STATUS_ERROR_IN_USE = -7 +,
+  BRAWCAP_STATUS_ERROR_BEYOND_MTU = -8 +,
+  BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED = -9 +,
+  BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE = -10 +,
+  BRAWCAP_STATUS_ERROR_OVERRUN = -11 +,
+  BRAWCAP_STATUS_WARNING_DEMO_MODE = 1 +,
+  BRAWCAP_STATUS_WARNING_PENDING = 2 +,
+  BRAWCAP_STATUS_WARNING_LIMIT_REACHED = 3 +,
+  BRAWCAP_STATUS_WARNING_CANCELED = 4 +,
+  BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED = 5 +,
+  BRAWCAP_STATUS_WARNING_NO_UPLINK = 6 +,
+  BRAWCAP_STATUS_INFO_NOT_RUNNING = 2000 +,
+  BRAWCAP_STATUS_INFO_NOT_ATTACHED = 2001 +,
+  BRAWCAP_STATUS_INFO_NOT_REGISTERED = 2002 +,
+  BRAWCAP_STATUS_INFO_ALREADY_REGISTERED = 2003 +,
+  BRAWCAP_STATUS_INFO_NO_DATA = 2004 +,
+  BRAWCAP_STATUS_INFO_TIMEOUT = 2005 +
+ }
 bRAWcap status/return codes. More...
 
+ + + + +

+Functions

brawcap_status_t brawcap_last_status ()
 Reads the last status appeared in bRAWcap, for the calling thread.
 
+

Detailed Description

+

Contains all status/return codes of bRAWcap.

+

If a bRAWcap function completed successfully and with no additional information it will indicate BRAWCAP_STATUS_SUCCESS.

+

If an error occurs the status code will always be negative.

+

A status which indicates a warning, will always have a positive value (range 1 to 1999).

+

While a status with additional information is always represented by high positive value (range 2000 to 4000).

+

It is also possible to request the last "non successful" status for the current thread again with brawcap_last_status. This function works similar to the one defined by the Windows API (GetLastError()).

+

Enumeration Type Documentation

+ +

◆ brawcap_status_t

+ +
+
+ + + + +
enum brawcap_status_t
+
+ +

#include <brawcap_types_shared.h>

+ +

bRAWcap status/return codes.

+

Each status is defined with a descriptive name, which indicates it´s reason. To check for the status code type use one of the defined macros:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Enumerator
BRAWCAP_STATUS_SUCCESS 

Executed successfully, with no additional information.

+
BRAWCAP_STATUS_ERROR_FAILED 

Detected a - not further specified - failure.

+

This shouldn´t happen at all and mostly indicates a issue in OS abstraction. If it happens in a specific situation, please check the system resources (CPU load, memory usage...). If the issue can not be located, feel free to contact our support.

+
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE 

Function is not available.

+

This may be returned due to several conditions:

    +
  • bRAWcap license does not include the requested feature.
    • +
  • The current machine does not support the feature.
    • +
  • Higher API registration privilege is required.
    • +
+
BRAWCAP_STATUS_ERROR_INVALID_POINTER 

At least one specified pointer parameter was invalid.

+

This is a caller issue. Please check the provided pointers to solve this issue.

+
BRAWCAP_STATUS_ERROR_INVALID_PARAM 

At least one parameter content is invalid.

+

This is a caller issue. Please check the provided parameters and their contents to solve this issue.

+
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE 

At least one parameter is out of bounds.

+

This is a caller issue. Please check if the provided parameters fit to the given parameter limitations.

+
BRAWCAP_STATUS_ERROR_NOT_FOUND 

Given parameter not found.

+

This is in general a caller issue. For example it can occur if the function expects a local adapter name and the provided name did not match any of the currently available adapters.

+
BRAWCAP_STATUS_ERROR_IN_USE 

Indicates that operation failed because the provided object is still in use.

+

This may happen if another thread uses the same object or another operation for the object is still outstanding.

+
BRAWCAP_STATUS_ERROR_BEYOND_MTU 

The packet size is beyond adapter MTU.

+

This status is especially for transmitted packets. It will be applied if the packet could not be transmitted because it´s length is beyond the configured adapter MTU.

+
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED 

Communication with the driver failed.

+

This indicates an error between library and driver communication.

+

To fix such issues, make sure that the loaded library version matches with the driver version.

+

In general it is not allowed to mix up library and driver versions. Applications shall always use the deployed bRAWcap library from the system and not deploy it´s own copy of it.

+

If driver and library version matches and this error still occurs, please contact our support.

+
BRAWCAP_STATUS_ERROR_DRIVER_NOT_AVAILABLE 

bRAWcap is not activated (on a specific adapter).

+

This will be returned if bRAWcap driver is not available (anymore) for the specified bRAWcap handle. For example if the driver was deactivated meanwhile.

+
BRAWCAP_STATUS_ERROR_OVERRUN 

A buffer overrun was detected.

+

This is the case if:

    +
  • The provided buffer length was to short for the content.
    • +
  • A bRAWcap packet buffer has reached it´s "packet" capacity.
    • +
+
BRAWCAP_STATUS_WARNING_DEMO_MODE 

The operation was not executed due to demo mode limitations.

+

This should only be returned if there is no valid license for the requested feature. For more information about demo limitation see chapter Demo Mode in the manual.

+
BRAWCAP_STATUS_WARNING_PENDING 

Will be returned if another operation for the same resource is pending.

+

This could be the case for functions which will initiate a receive/transmit while another receive/transmit is already pending on the specified handle. In general it is not allowed to use receive/transmits in parallel on the same handle. For example if a receive is started, brawcap_rx_packet cannot be used until the receive is stopped. Same applies to transmissions.

+
BRAWCAP_STATUS_WARNING_LIMIT_REACHED 

Indicates that a bRAWcap limitation is reached.

+

This could be the case if there are already max supported number of handles to the same adapter and the caller tries to open another one.

+
BRAWCAP_STATUS_WARNING_CANCELED 

Indicates that a operation was canceled.

+

For example if a packet transmission was initiated and it is somehow canceled. This could be the case due to bRAWcap driver deactivation. If so this status will be applied for each packet which was canceled (not transmitted).

+
BRAWCAP_STATUS_WARNING_NOT_ALL_PROCESSED 

Indicates that not all of the specified content/payload was processed.

+

It will be returned for example if not all packets of a bRAWcap packet buffer was transmitted. If so the user should check the status of each packet inside the buffer for further information.

+
BRAWCAP_STATUS_WARNING_NO_UPLINK 

Indicates that there is currently no uplink on the given adapter.

+

It will be returned if the user tries to send packets to a adapter which has currently no uplink.

+
BRAWCAP_STATUS_INFO_NOT_RUNNING 

No operation running.

+

This will be returned if the user tries to stop something which is currently not running. For example when trying to stop receiving while it is not running.

+
BRAWCAP_STATUS_INFO_NOT_ATTACHED 

Indicates that the given object is not attached.

+

Will be returned for example if the user tries to detach a packet buffer which is currently not attached to a handle.

+
BRAWCAP_STATUS_INFO_NOT_REGISTERED 

Indicates that the given object is not registered.

+

Will be returned if user tries to unregister from a bRAWcap notification which was not registered before.

+
BRAWCAP_STATUS_INFO_ALREADY_REGISTERED 

Indicates that the given object was already registered.

+

Will be returned if user tries to register for something again which is already registered.

+
BRAWCAP_STATUS_INFO_NO_DATA 

Indicates that a function returns without any data.

+

This could be the case if a receive function returns without any received packet. For example if the configured receive timeout is reached.

+
BRAWCAP_STATUS_INFO_TIMEOUT 

Indicates that a function returned because of a timeout.

+

This could be the case if a function has not finished it´s processing until a configured timeout is reached.

+
+ +
+
+

Function Documentation

+ +

◆ brawcap_last_status()

+ +
+
+ + + + + + + +
brawcap_status_t brawcap_last_status ()
+
+ +

#include <brawcap.h>

+ +

Reads the last status appeared in bRAWcap, for the calling thread.

+

The last status is only updated if it does not equal BRAWCAP_STATUS_SUCCESS. Which means that this function shall never be used to check if a bRAWcap function succeeded. Instead this should always be checked on each bRAWcap function return value directly and only if something different than BRAWCAP_STATUS_SUCCESS is returned, this function can be used to get the last status again.

+

The last status may be overwritten when the calling thread calls another bRAWcap function. It is therefore recommended to call this function directly after a bRAWcap function to get the status of that function again.

+
Note
If yet, no other status than BRAWCAP_STATUS_SUCCESS occurred for the calling thread, BRAWCAP_STATUS_SUCCESS will be returned.
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS If no other status than success happened for the calling thread.
Any of brawcap_status_t Please see return of last called function for detailed info.
+
+
Examples
03_generic_handle_opener.c, 05_receive_simple_packet_receiver.c, 06_filter_firewall.c, 07_receive_buffered_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00049.html b/sdk/c/doc/html/a00049.html new file mode 100644 index 0000000..2d7756a --- /dev/null +++ b/sdk/c/doc/html/a00049.html @@ -0,0 +1,325 @@ + + + + + + + + +bRAWcap: Version + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Data Structures | +Functions
+
Version
+
+
+ +

Types and functions for operating with bRAWcap version(s). +More...

+ + + + + + + + +

+Data Structures

struct  brawcap_version_fragments_t
 Struct containing the separated version parts. More...
 
union  brawcap_version_t
 bRAWcap version. More...
 
+ + + + + + + +

+Functions

brawcap_status_t brawcap_version_api (brawcap_version_t *const pVersion)
 Returns loaded bRAWcap library version.
 
brawcap_status_t brawcap_version_driver (brawcap_handle_t *const pHandle, brawcap_version_t *const pVersion)
 Reads current version of loaded bRAWcap driver.
 
+

Detailed Description

+

Types and functions for operating with bRAWcap version(s).

+

Here our bRAWcap version structure is defined. This structure allows easy access to each part of the version and due to it´s union the complete value can be used for easy version compares.

+

There are currently two functions to retrieve a version. One for the version of the loaded library and another one for the version of the loaded bRAWcap driver on the machine.

+
Attention
In general both versions shall be equal. This means it is not allowed to deploy copys of the bRAWcap library with any application. Instead always the bRAWcap library from system path shall be used (which will be deployed by the bRAWcap setup). This avoids communication issues between the driver and the library. If there are any issues with driver communication, please check that the driver and library version matches.
+

List of examples:

    +
  1. Version Comparator
    2. +
+

Data Structure Documentation

+ +

◆ brawcap_version_fragments_t

+ +
+
+ + + + +
struct brawcap_version_fragments_t
+
+

Struct containing the separated version parts.

+
+ + + + + + + + + + + + + +
Data Fields
+UINT16 +build +Build version.

Different for each build. Releases will always have different version by the upper three values. Versions with different build versions only should not appear. API and ABI always stays compatible between different build versions.

+
+UINT16 +patch +Patch version.

Different for each bugfix release. Will be increased if the release contains bugfixes only. API and ABI always stays compatible between different patch versions.

+
+UINT16 +minor +Minor version.

Different for each minor release. Will be increased if the release contains new features (and maybe some bugfixes). API always stays compatible between different minor versions.

+
+UINT16 +major +Major version.

Different for each major release. Will be increased if for example some features have removed or changed in a way which would break the API compatibility. API compatibility between different major versions is not guaranteed.

+
+ +
+
+ +

◆ brawcap_version_t

+ +
+
+ + + + +
union brawcap_version_t
+
+

bRAWcap version.

+

The version is implemented as a union. The complete member allows easy compare between versions. While the fragments allow easy access to each version part (major, minor, patch, build).

+
Examples
04_version_comparator.c.
+
+
+ + + + + + + +
Data Fields
+brawcap_version_fragments_t +fragments +

Separated parts of the version.

+
+UINT64 +complete +

Complete version as integer. Use this for comparing versions.

+
+ +
+
+

Function Documentation

+ +

◆ brawcap_version_api()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_version_api (brawcap_version_t *const pVersion)
+
+ +

#include <brawcap.h>

+ +

Returns loaded bRAWcap library version.

+
Parameters
+ + +
[out]pVersionWill contain the loaded library version, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
04_version_comparator.c.
+
+ +
+
+ +

◆ brawcap_version_driver()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_version_driver (brawcap_handle_t *const pHandle,
brawcap_version_t *const pVersion 
)
+
+ +

#include <brawcap.h>

+ +

Reads current version of loaded bRAWcap driver.

+
Note
The driver version is the same for each adapter. Therefore, it doesn´t matter which handle/adapter is used to read the driver version.
+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[out]pVersionWill contain the bRAWcap driver version, 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_DRIVER_IO_FAILED Communicating with bRAWcap driver failed.
+
+
Examples
04_version_comparator.c.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00050.html b/sdk/c/doc/html/a00050.html new file mode 100644 index 0000000..a5ab9d6 --- /dev/null +++ b/sdk/c/doc/html/a00050.html @@ -0,0 +1,847 @@ + + + + + + + + +bRAWcap: Timestamp + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros | +Typedefs | +Enumerations | +Functions
+
Timestamp
+
+
+ +

Types and functions for operating with bRAWcap timestamps. +More...

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define BRAWCAP_TIMESTAMP_MODE_SYSL_AVAILABLE(_capabilities)   (_capabilities & 0x01)
 Checks if timestamp mode system low precision is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_SYSH_AVAILABLE(_capabilities)   (_capabilities & 0x02)
 Checks if timestamp mode system high precision is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_SW_AVAILABLE(_capabilities)   (_capabilities & 0x04)
 Checks if timestamp mode software is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYS_AVAILABLE(_capabilities)   (_capabilities & 0x08)
 Checks if timestamp mode adapter system is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_SW_AVAILABLE(_capabilities)   (_capabilities & 0x10)
 Checks if timestamp mode adapter software is supported.
 
+#define BRAWCAP_TIMESTAMP_MODE_ADAPTER_HW_AVAILABLE(_capabilities)   (_capabilities & 0x20)
 Checks if timestamp mode adapter hardware is supported.
 
#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN   0
 If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_SEC   1000000000
 Number of nanoseconds per second.
 
+#define BRAWCAP_TIMESTAMP_US_PER_SEC   1000000
 Number of microseconds per second.
 
+#define BRAWCAP_TIMESTAMP_MS_PER_SEC   1000
 Number of milliseconds per second.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_US   1000
 Number of nanoseconds per microsecond.
 
+#define BRAWCAP_TIMESTAMP_NS_PER_MS   1000000
 Number of nanoseconds per millisecond.
 
+ + + + + + + + + + +

+Typedefs

typedef UINT32 brawcap_timestamp_capabilities_t
 Type used for indicating the supported timestamp modes.
 
typedef UINT32 brawcap_timestamp_resolution_ns_t
 Represents the timestamp resolution in nanoseconds.
 
typedef struct _brawcap_timestamp brawcap_timestamp_t
 bRAWcap timestamp object.
 
+ + + + +

+Enumerations

enum  brawcap_timestamp_mode_t {
+  BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP = 0x00 +,
+  BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC = 0x01 +,
+  BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC = 0x02 +,
+  BRAWCAP_TIMESTAMP_MODE_SOFTWARE = 0x04 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM = 0x08 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE = 0x10 +,
+  BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE = 0x20 +
+ }
 List of different timestamp modes. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

brawcap_status_t brawcap_timestamp_mode_get (brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_mode_t *const pMode)
 Reads out the mode of the specified timestamp.
 
brawcap_status_t brawcap_timestamp_resolution_ns_get (brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_resolution_ns_t *const pResolution_ns)
 Reads out the timestamp resolution of the specified timestamp.
 
brawcap_status_t brawcap_timestamp_value_ns_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pNanoseconds)
 Reads out the timestamp value in seconds and nanoseconds.
 
brawcap_status_t brawcap_timestamp_value_ns_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 nanoseconds)
 Sets the timestamp value in seconds and nanoseconds.
 
brawcap_status_t brawcap_timestamp_value_us_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMicroseconds)
 Reads out the timestamp value in seconds and microseconds.
 
brawcap_status_t brawcap_timestamp_value_us_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 microseconds)
 Sets the timestamp value in seconds and microseconds.
 
brawcap_status_t brawcap_timestamp_value_ms_get (brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMilliseconds)
 Reads out the timestamp value in seconds and milliseconds.
 
brawcap_status_t brawcap_timestamp_value_ms_set (brawcap_timestamp_t *const pTimestamp, const UINT64 seconds, const UINT32 milliseconds)
 Sets the timestamp value in seconds and milliseconds.
 
+

Detailed Description

+

Types and functions for operating with bRAWcap timestamps.

+

At the moment it is not possible to create a standalone timestamp object. Instead a timestamp is always part of a packet. To get the timestamp object use brawcap_packet_timestamp_get on a specific packet. This object can be used than for all functions in this module.

+
Attention
The user application shall never store a timestamp, instead it should always request it from a packet and only use it as long as the packet itself is valid.
+

List of examples:

    +
  1. Receive Timestamp Inspector
    2. +
  2. Simple Packet Receiver
    3. +
+

Macro Definition Documentation

+ +

◆ BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN

+ +
+
+ + + + +
#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN   0
+
+ +

#include <brawcap_types_shared.h>

+ +

If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.

+

For example this can be the case for adapter hardware timestamps, if the adapter does not report it´s clock frequency.

+
Examples
08_receive_timestamp_inspector.c.
+
+ +
+
+

Typedef Documentation

+ +

◆ brawcap_timestamp_capabilities_t

+ +
+
+ + + + +
typedef UINT32 brawcap_timestamp_capabilities_t
+
+ +

#include <brawcap_types_shared.h>

+ +

Type used for indicating the supported timestamp modes.

+

It has to be interpreted as bitfield.

+ +
+
+ +

◆ brawcap_timestamp_resolution_ns_t

+ +
+
+ + + + +
typedef UINT32 brawcap_timestamp_resolution_ns_t
+
+ +

#include <brawcap_types_shared.h>

+ +

Represents the timestamp resolution in nanoseconds.

+

The resolution can be used to check how accurate a timestamp is. For example if it is set to 1.000.000 ns the timestamp has a accuracy of "only" one millisecond. If it is set to 1 ns instead, it would indicate a very precise timestamp with a resolution of one nanosecond.

+ +
+
+ +

◆ brawcap_timestamp_t

+ +
+
+ + + + +
typedef struct _brawcap_timestamp brawcap_timestamp_t
+
+ +

#include <brawcap_types_shared.h>

+ +

bRAWcap timestamp object.

+

The timestamp object is part of each packet and has to be used for each timestamp module function. To get a timestamp object from a packet use brawcap_packet_timestamp_get.

+ +
+
+

Enumeration Type Documentation

+ +

◆ brawcap_timestamp_mode_t

+ +
+
+ + + + +
enum brawcap_timestamp_mode_t
+
+ +

#include <brawcap_types_shared.h>

+ +

List of different timestamp modes.

+

The mode of a timestamp can be used to check when the timestamp is generated (time of trigger). It can also indicate how accurate a timestamp is.

+

Description for the different timestamp types:

    +
  • System timestamps:
      +
    • Less accurate
      • +
    • Jumps if the system time itself is jumping.
      • +
    • Source is the system time
      • +
    +
    • +
  • Software timestamps:
      +
    • Good accuracy
      • +
    • Guaranteed to not jump.
      • +
    • Source is almost ever the local TSC (if the CPU supports it). If not Windows will take the next accurate source for it. For more information on QPC, please see the official Microsoft documentation .
      • +
    • They will always start from zero and increase with system up time.
      • +
    +
    • +
  • Hardware timestamps:
      +
    • Highest accuracy because they are not influenced by the system.
      • +
    • Only jumps if the adapter hardware clock jumps.
      • +
    • Source is the adapter hardware clock.
      • +
    +
    • +
+
Note
Adapter timestamps are features provided by the underlying adapter and not part of bRAWcap. bRAWcap only provides those timestamps if the underlying adapter supports it. To check if the underlying adapter supports them use +
+
+More accurate system or software timestamps can increase the overall CPU load a bit. These differences can be neglected in most cases, but if the user is not interested in high-precision timestamps, always timestamps that require less effort should be preferred.
+
+Trigger position for timestamps created by bRAWcap driver:
    +
  • Receive: When the packet is recognized by the bRAWcap driver (forwarded from the underlying driver)
    • +
  • Transmit: When the transmission complete event is recognized by the bRAWcap driver
    • +
+
+ + + + + + + + +
Enumerator
BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP 

No timestamp.

+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC 

A low precision system timestamp created by bRAWcap driver.

+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC 

A high precision system timestamp created by bRAWcap driver.

+
BRAWCAP_TIMESTAMP_MODE_SOFTWARE 

A software timestamp created by bRAWcap driver.

+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM 

A system timestamp created by the network adapter driver.

+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE 

A software timestamp created by the network adapter driver.

+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE 

A hardware timestamp created by the network adapter hardware/firmware.

+
+ +
+
+

Function Documentation

+ +

◆ brawcap_timestamp_mode_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_mode_get (brawcap_timestamp_t *const pTimestamp,
brawcap_timestamp_mode_t *const pMode 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the mode of the specified timestamp.

+
Parameters
+ + + +
[in]pTimestampThe timestamp to read from.
[out]pModeWill contain the timestamp mode, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_timestamp_resolution_ns_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_resolution_ns_get (brawcap_timestamp_t *const pTimestamp,
brawcap_timestamp_resolution_ns_t *const pResolution_ns 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the timestamp resolution of the specified timestamp.

+
Note
If the resolution is unknown it will be set to zero (BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN)
+
Parameters
+ + + +
[in]pTimestampThe timestamp to read from.
[out]pResolution_nsWill contain the timestamp resolution in nanoseconds, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_timestamp_value_ns_get()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_ns_get (brawcap_timestamp_t *const pTimestamp,
UINT64 *const pSeconds,
UINT32 *const pNanoseconds 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the timestamp value in seconds and nanoseconds.

+

The values are based on 00:00 01.01.1970.

+

The seconds part contains only whole seconds of the timestamp, while the nanoseconds part contains only the fractional part.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to read from.
[out]pSecondsWill contain the whole seconds of the timestamp, afterwards.
[out]pNanosecondsWill contain the fractional part in nanoseconds, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_timestamp_value_ns_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_ns_set (brawcap_timestamp_t *const pTimestamp,
const UINT64 seconds,
const UINT32 nanoseconds 
)
+
+ +

#include <brawcap.h>

+ +

Sets the timestamp value in seconds and nanoseconds.

+

The values has to be based on 00:00 01.01.1970.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to be modified.
[in]secondsWhole seconds since 00:00 01.01.1970.
[in]nanosecondsThe fractional part in nanoseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999.999.999 nanoseconds.
+
+
+
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 Nanosecond value to high (only fraction of second).
+
+ +
+
+ +

◆ brawcap_timestamp_value_us_get()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_us_get (brawcap_timestamp_t *const pTimestamp,
UINT64 *const pSeconds,
UINT32 *const pMicroseconds 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the timestamp value in seconds and microseconds.

+

The values are based on 00:00 01.01.1970.

+

The seconds part contains only whole seconds of the timestamp, while the microseconds contains only the fractional part.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to read from.
[out]pSecondsWill contain the whole seconds of the timestamp, afterwards.
[out]pMicrosecondsWill contain the fractional part in microseconds, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_timestamp_value_us_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_us_set (brawcap_timestamp_t *const pTimestamp,
const UINT64 seconds,
const UINT32 microseconds 
)
+
+ +

#include <brawcap.h>

+ +

Sets the timestamp value in seconds and microseconds.

+

The values has to be based on 00:00 01.01.1970.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to be modified.
[in]secondsWhole seconds since 00:00 01.01.1970.
[in]microsecondsThe fractional part in microseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999.999 microseconds.
+
+
+
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 Nanosecond value to high (only fraction of second).
+
+ +
+
+ +

◆ brawcap_timestamp_value_ms_get()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_ms_get (brawcap_timestamp_t *const pTimestamp,
UINT64 *const pSeconds,
UINT32 *const pMilliseconds 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the timestamp value in seconds and milliseconds.

+

The values are based on 00:00 01.01.1970.

+

The seconds part contains only whole seconds of the timestamp, while the milliseconds part contains only the fractional part.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to read from.
[out]pSecondsWill contain the whole seconds of the timestamp, afterwards.
[out]pMillisecondsWill contain the fractional part in milliseconds, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_timestamp_value_ms_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_timestamp_value_ms_set (brawcap_timestamp_t *const pTimestamp,
const UINT64 seconds,
const UINT32 milliseconds 
)
+
+ +

#include <brawcap.h>

+ +

Sets the timestamp value in seconds and milliseconds.

+

The values has to be based on 00:00 01.01.1970.

+
Parameters
+ + + + +
[in]pTimestampThe timestamp to be modified.
[in]secondsWhole seconds since 00:00 01.01.1970.
[in]millisecondsThe fractional part in milliseconds. This parameter should only contain the fractional timestamp part. That means that it can never exceed 999 milliseconds.
+
+
+
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 Nanosecond value to high (only fraction of second).
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00051.html b/sdk/c/doc/html/a00051.html new file mode 100644 index 0000000..5dad786 --- /dev/null +++ b/sdk/c/doc/html/a00051.html @@ -0,0 +1,726 @@ + + + + + + + + +bRAWcap: Packet + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros | +Typedefs | +Functions
+
Packet
+
+
+ +

Types and functions for operating with bRAWcap packets. +More...

+ + + + + + + + +

+Macros

#define BRAWCAP_PACKET_SIZE_MAX   9018
 The maximum supported (byte) size for a single packet payload.
 
#define BRAWCAP_PACKET_SIZE_MIN   14
 The minimum required (byte) size for a single packet payload.
 
+ + + + + + + +

+Typedefs

typedef UINT16 brawcap_packet_size_t
 Type for handling the number of payload bytes per packet.
 
typedef struct _brawcap_packet brawcap_packet_t
 bRAWcap packet object.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

brawcap_status_t brawcap_packet_create (brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
 Creates a new packet.
 
brawcap_status_t brawcap_packet_free (brawcap_packet_t *pPacket)
 Frees the specified packet. When this function is called the specified packet becomes invalid and it´s memory is released.
 
brawcap_status_t brawcap_packet_status_get (brawcap_packet_t *const pPacket, brawcap_status_t *const pStatus)
 Reads out the status for the specified packet. The status will be set updated during reception/transmission. It indicates the status of the packet depending on the operation.
 
brawcap_status_t brawcap_packet_timestamp_get (brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
 Reads out the timestamp object for the specified packet.
 
brawcap_status_t brawcap_packet_length_on_wire_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLengthOnWire)
 Reads out the length on wire of the specified packet. This value is especially useful for received packets. It indicates the total packet payload byte size of the packet on wire. This may not equal to the captured payload byte size. Because the payload byte size depends on the configured filter and it´s bytes to capture parameters.
 
brawcap_status_t brawcap_packet_payload_max_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pMaxPayloadSize)
 Reads out the max supported payload byte size of the specified packet. This value was set during packet creation (or buffer creation if it´s a buffered packet).
 
brawcap_status_t brawcap_packet_payload_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLength)
 Reads out the captured payload byte size of the specified packet. This indicates the total byte size of the (captured - if received) packet payload.
 
brawcap_status_t brawcap_packet_payload_get (brawcap_packet_t *const pPacket, const char **const pPayload, brawcap_packet_size_t *const pLength)
 Reads out the payload of the specified packet.
 
brawcap_status_t brawcap_packet_payload_set (brawcap_packet_t *const pPacket, const char *const pPayload, const brawcap_packet_size_t length)
 Sets the packet payload of the specified packet.
 
+

Detailed Description

+

Types and functions for operating with bRAWcap packets.

+

To create a packet use brawcap_packet_create. If a packet is not required anymore it shall be deleted with brawcap_packet_free.

+
Note
It is also possible to use "buffered" packets. Those packets must not be created and freed on their one. Instead they are part of a packet buffer. To access buffered packets use brawcap_buffer_at_index to get a packet on a specific position of the buffer or brawcap_buffer_iterator_eval on a packet buffer iterator. The second one is especially useful while iterating the buffer.
+
Attention
The user application shall never store buffered packets separately. Instead it should always request packets directly from the packet buffer and only use them as long as the packet buffer itself is valid.
+

List of examples:

    +
  1. Simple Packet Receiver
    2. +
  2. Buffered Receiver
    3. +
  3. Receive Timestamp Inspector
    4. +
+

Macro Definition Documentation

+ +

◆ BRAWCAP_PACKET_SIZE_MAX

+ +
+
+ + + + +
#define BRAWCAP_PACKET_SIZE_MAX   9018
+
+ +

#include <brawcap_types_shared.h>

+ +

The maximum supported (byte) size for a single packet payload.

+

This value corresponds to jumbo frame size (9000 Bytes) + Ethernet header (14 Bytes) + single VLAN header (4 Bytes).

+
Examples
05_receive_simple_packet_receiver.c, 07_receive_buffered_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ BRAWCAP_PACKET_SIZE_MIN

+ +
+
+ + + + +
#define BRAWCAP_PACKET_SIZE_MIN   14
+
+ +

#include <brawcap_types_shared.h>

+ +

The minimum required (byte) size for a single packet payload.

+

This corresponds to Ethernet header size.

+
Note
The Ethernet standard defines a minimum packet length of 64 Bytes (including 4 Byte for Ethernet FCS). If smaller packets are sent the network adapter will automatically add some padding at the end of the payload. The padding contains zeros only and after the last padding/payload byte the Ethernet FCS will be added.
+ +
+
+

Typedef Documentation

+ +

◆ brawcap_packet_size_t

+ +
+
+ + + + +
typedef UINT16 brawcap_packet_size_t
+
+ +

#include <brawcap_types_shared.h>

+ +

Type for handling the number of payload bytes per packet.

+

Typically the packet payload size is set to the adapters max transmission unit (MTU) size + Ethernet header size and maybe a single VLAN header. Packet payload sizes have to be between BRAWCAP_PACKET_SIZE_MIN and BRAWCAP_PACKET_SIZE_MAX, values below/beyond are not accepted.

+ +
+
+ +

◆ brawcap_packet_t

+ +
+
+ + + + +
typedef struct _brawcap_packet brawcap_packet_t
+
+ +

#include <brawcap_types_shared.h>

+ +

bRAWcap packet object.

+

The packet object has to be used for each packet module function. Packet objects can be created and freed or retrieved from a packet buffer.

+ +
+
+

Function Documentation

+ +

◆ brawcap_packet_create()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_create (brawcap_packet_t **const pPacket,
const brawcap_packet_size_t maxSize 
)
+
+ +

#include <brawcap.h>

+ +

Creates a new packet.

+

A packet can be used for receiving (single packet based) or transmitting (also single packet based).

+

If a packet is not required anymore it should be freed.

+
Parameters
+ + + +
[out]pPacketWill contain the new created packet, afterwards.
[in]maxSizeThe maximum supported byte size for the packet payload. This value cannot be changed after packet creation and determines how much memory is required for the packet. The packet can only contain payloads up to this value.
+
+
+
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 Packet payload byte size to low/high.
BRAWCAP_STATUS_ERROR_FAILED System error occurred (e.g. out of memory).
+
+
Examples
05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_packet_free()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_packet_free (brawcap_packet_t * pPacket)
+
+ +

#include <brawcap.h>

+ +

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

+
Warning
Freeing a packet is not thread safe and the user is responsible for synchronization.
+
Parameters
+ + +
[in]pPacketThe packet 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
05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_packet_status_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_status_get (brawcap_packet_t *const pPacket,
brawcap_status_t *const pStatus 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the status for the specified packet. The status will be set updated during reception/transmission. It indicates the status of the packet depending on the operation.

+
Parameters
+ + + +
[in]pPacketThe packet to read from.
[out]pStatusWill contain the packet status, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+ +
+
+ +

◆ brawcap_packet_timestamp_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_timestamp_get (brawcap_packet_t *const pPacket,
brawcap_timestamp_t **const pTimestamp 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the timestamp object for the specified packet.

+
Attention
The timestamp is part of the packet itself. Therefore the returned timestamp is only valid as long as the packet itself is valid. The user application shall not store the timestamp object separately and only used it as long as the packet is valid.
+
Parameters
+ + + +
[in]pPacketThe packet to read from.
[out]pTimestampWill contain the timestamp object of the packet, afterwards. This object can be used by the Timestamp module.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
05_receive_simple_packet_receiver.c, and 08_receive_timestamp_inspector.c.
+
+ +
+
+ +

◆ brawcap_packet_length_on_wire_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_length_on_wire_get (brawcap_packet_t *const pPacket,
brawcap_packet_size_t *const pLengthOnWire 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the length on wire of the specified packet. This value is especially useful for received packets. It indicates the total packet payload byte size of the packet on wire. This may not equal to the captured payload byte size. Because the payload byte size depends on the configured filter and it´s bytes to capture parameters.

+
Parameters
+ + + +
[in]pPacketThe packet to read from.
[out]pLengthOnWireWill contain the payload byte length on wire, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
05_receive_simple_packet_receiver.c.
+
+ +
+
+ +

◆ brawcap_packet_payload_max_size_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_payload_max_size_get (brawcap_packet_t *const pPacket,
brawcap_packet_size_t *const pMaxPayloadSize 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the max supported payload byte size of the specified packet. This value was set during packet creation (or buffer creation if it´s a buffered packet).

+
Parameters
+ + + +
[in]pPacketThe packet to read from.
[out]pMaxPayloadSizeWill contain the max packet payload byte size, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+ +
+
+ +

◆ brawcap_packet_payload_size_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_payload_size_get (brawcap_packet_t *const pPacket,
brawcap_packet_size_t *const pLength 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the captured payload byte size of the specified packet. This indicates the total byte size of the (captured - if received) packet payload.

+
Parameters
+ + + +
[in]pPacketThe packet to read from.
[out]pLengthWill contain the captured payload byte size, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_packet_payload_get()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_payload_get (brawcap_packet_t *const pPacket,
const char **const pPayload,
brawcap_packet_size_t *const pLength 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the payload of the specified packet.

+

The function returns a pointer to the beginning of the packet payload.

+
Note
The returned payload pointer should be only accessed as long as the packet is not freed. If post processing is required a copy of the required payload should be done.
+
Attention
Accessing the packet payload is not thread safe and user is responsible for synchronization.
+
Parameters
+ + + + +
[in]pPacketThe packet to read from.
[out]pPayloadWill contain a pointer to the beginning of the packet payload, afterwards.
[out]pLengthWill contain the total length of the packet payload, afterwards.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
05_receive_simple_packet_receiver.c.
+
+ +
+
+ +

◆ brawcap_packet_payload_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_packet_payload_set (brawcap_packet_t *const pPacket,
const char *const pPayload,
const brawcap_packet_size_t length 
)
+
+ +

#include <brawcap.h>

+ +

Sets the packet payload of the specified packet.

+
Note
It is not allowed to set a larger payload than the max byte payload size (specified during packet creation or buffer creation). If a larger payload is specified the function will fail and return an error.
+
Parameters
+ + + + +
[in]pPacketThe packet to be modified.
[in]pPayloadPointer to the beginning of the payload to set.
[in]lengthTotal byte size of the payload to set.
+
+
+
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 The specified payload size exceeds the packet max payload size.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00052.html b/sdk/c/doc/html/a00052.html new file mode 100644 index 0000000..cae513d --- /dev/null +++ b/sdk/c/doc/html/a00052.html @@ -0,0 +1,824 @@ + + + + + + + + +bRAWcap: Packet Buffer + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Modules | +Macros | +Typedefs | +Functions
+
Packet Buffer
+
+
+ +

Types and functions for operating with bRAWcap packet buffers. +More...

+ + + + + +

+Modules

 Packet Buffer Iterator
 bRAWcap packet buffer iterators.
 
+ + + + + + + +

+Macros

+#define BRAWCAP_BUFFER_PACKETS_MAX   100000
 The maximum amount of packets, which can be stored in a packet buffer.
 
+#define BRAWCAP_BUFFER_PACKETS_MIN   1
 The minimum amount of packets, which a packet buffer must have.
 
+ + + + + + + +

+Typedefs

typedef UINT32 brawcap_buffer_packet_count_t
 Type for handling the number of packets which can be stored in a packet buffer.
 
typedef struct _brawcap_buffer brawcap_buffer_t
 bRAWcap packet buffer object.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

brawcap_status_t brawcap_buffer_create (brawcap_buffer_t **const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize, const brawcap_buffer_packet_count_t numPackets)
 Creates a new packet buffer.
 
brawcap_status_t brawcap_buffer_free (brawcap_buffer_t *pBuffer)
 Frees the specified packet buffer. When this function is called the specified packet buffer becomes invalid and it´s memory will be released.
 
brawcap_status_t brawcap_buffer_clear (brawcap_buffer_t *const pBuffer)
 Clears the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_back (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
 Adds the specified packet at the end of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_front (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket)
 Adds the specified packet at the front of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_add_at_index (brawcap_buffer_t *const pBuffer, const brawcap_packet_t *const pPacket, const brawcap_buffer_packet_count_t index)
 Inserts the specified packet at index/position into the specified packet buffer.
 
brawcap_status_t brawcap_buffer_at_index (brawcap_buffer_t *const pBuffer, const brawcap_buffer_packet_count_t index, brawcap_packet_t **const pPacket)
 Reads out a buffered packet at the index of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_front (brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
 Reads out the first buffered packet of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_back (brawcap_buffer_t *const pBuffer, brawcap_packet_t **const pPacket)
 Reads out the last buffered packet of the specified packet buffer.
 
brawcap_status_t brawcap_buffer_count (brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCount)
 Reads out the number of currently buffered packets in the specified packet buffer.
 
brawcap_status_t brawcap_buffer_capacity (brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t *const pPacketCapacity)
 Reads out the total number of packets which can be buffered by the specified packet buffer. This value represents the packet buffer capacity, which is set during buffer creation.
 
+

Detailed Description

+

Types and functions for operating with bRAWcap packet buffers.

+

To create a new packet buffer use brawcap_buffer_create. If a packet buffer is not required anymore it shall be deleted with brawcap_buffer_free.

+

Packet buffers can be used for

+
Attention
The packet buffer will be locked down after attaching/sending to a specific handle. This means that it cannot be accessed by user application as long as it is pending for transmission or attached for receiving. If the user application tries to access a locked buffer a error will be returned by the specific packet buffer function.
+

A packet buffer can be accessed if:

+

List of examples:

    +
  1. Buffered Receiver
    2. +
+

Typedef Documentation

+ +

◆ brawcap_buffer_packet_count_t

+ +
+
+ + + + +
typedef UINT32 brawcap_buffer_packet_count_t
+
+ +

#include <brawcap_types_shared.h>

+ +

Type for handling the number of packets which can be stored in a packet buffer.

+

The total amount of packets per packet buffer has to be between BRAWCAP_BUFFER_PACKETS_MIN - BRAWCAP_BUFFER_PACKETS_MAX.

+ +
+
+ +

◆ brawcap_buffer_t

+ +
+
+ + + + +
typedef struct _brawcap_buffer brawcap_buffer_t
+
+ +

#include <brawcap_types_shared.h>

+ +

bRAWcap packet buffer object.

+

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

+ +
+
+

Function Documentation

+ +

◆ brawcap_buffer_create()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_create (brawcap_buffer_t **const pBuffer,
const brawcap_packet_size_t maxPacketPayloadSize,
const brawcap_buffer_packet_count_t numPackets 
)
+
+ +

#include <brawcap.h>

+ +

Creates a new packet buffer.

+

The created buffer can be used for:

+

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

+
Parameters
+ + + + +
[out]pBufferWill contain the new created packet buffer, afterwards.
[in]maxPacketPayloadSizeSpecifies the max payload byte size for each packet in the buffer. This cannot be changed after buffer creation and controls the memory size required for each packet in the buffer. When trying to set the packet payload of any buffered packet which exceeds this value, it will fail. The value has to be between BRAWCAP_PACKET_SIZE_MIN and BRAWCAP_PACKET_SIZE_MAX.
[in]numPacketsSpecifies how many packets can be stored in the buffer. This value, together with the max packet payload size, will control the total amount of memory required for the packet buffer and cannot be changed after buffer creation. The value has to be between BRAWCAP_BUFFER_PACKETS_MIN and BRAWCAP_BUFFER_PACKETS_MAX.
+
+
+
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 The specified packet payload or number of packets is invalid.
BRAWCAP_STATUS_ERROR_FAILED System error occurred (e.g. out of memory).
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_buffer_free()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_buffer_free (brawcap_buffer_t * pBuffer)
+
+ +

#include <brawcap.h>

+ +

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

+
Warning
Freeing a buffer is not thread safe and the user is responsible for synchronization.
+
Parameters
+ + +
[in]pBufferThe packet buffer to be freed.
+
+
+
Returns
+ + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_buffer_clear()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_buffer_clear (brawcap_buffer_t *const pBuffer)
+
+ +

#include <brawcap.h>

+ +

Clears the specified packet buffer.

+

All buffered packets will be cleared. It may be used to reuse a already created packet buffer. For example this can be useful after transmission of the packet buffer has finished. Reusing a buffer improves performance and should be preferred instead of always creating and freeing packet buffers.

+
Warning
After calling this function all buffered packets in the packet buffer become invalid and shall not be used anymore.
+
Parameters
+ + +
[in]pBufferThe packet buffer to be cleared.
+
+
+
Returns
+ + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
+
+ +
+
+ +

◆ brawcap_buffer_add_back()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_add_back (brawcap_buffer_t *const pBuffer,
const brawcap_packet_t *const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Adds the specified packet at the end of the specified packet buffer.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to be modified.
[in]pPacketThe packet to insert into the buffer.
+
+
+
Returns
+ + + + + + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE The packet payload length is to long for the buffer.
+
+ +
+
+ +

◆ brawcap_buffer_add_front()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_add_front (brawcap_buffer_t *const pBuffer,
const brawcap_packet_t *const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Adds the specified packet at the front of the specified packet buffer.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to be modified.
[in]pPacketThe packet to insert into the buffer.
+
+
+
Returns
+ + + + + + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE The packet payload length is to long for the buffer.
+
+ +
+
+ +

◆ brawcap_buffer_add_at_index()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_add_at_index (brawcap_buffer_t *const pBuffer,
const brawcap_packet_t *const pPacket,
const brawcap_buffer_packet_count_t index 
)
+
+ +

#include <brawcap.h>

+ +

Inserts the specified packet at index/position into the specified packet buffer.

+
Parameters
+ + + + +
[in]pBufferThe packet buffer to be modified.
[in]pPacketThe packet to insert into the buffer.
[in]indexIndex at which the packet should be inserted.
+
+
+
Returns
+ + + + + + + + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_OVERRUN The max number of packets for the buffer is reached.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE The packet payload length is to long for the buffer.
BRAWCAP_STATUS_ERROR_INVALID_PARAM The given index is invalid (exceeds buffer).
+
+ +
+
+ +

◆ brawcap_buffer_at_index()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_at_index (brawcap_buffer_t *const pBuffer,
const brawcap_buffer_packet_count_t index,
brawcap_packet_t **const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Reads out a buffered packet at the index of the specified packet buffer.

+
Parameters
+ + + + +
[in]pBufferThe packet buffer to read from.
[in]indexThe index of the packet.
[out]pPacketWill contain the buffered packet, 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_IN_USE Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_INVALID_PARAM The given index is invalid (exceeds buffer).
+
+ +
+
+ +

◆ brawcap_buffer_front()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_front (brawcap_buffer_t *const pBuffer,
brawcap_packet_t **const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the first buffered packet of the specified packet buffer.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to read from.
[out]pPacketWill contain the buffered packet, 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_IN_USE Buffer is still in use/pending (receive/transmit).
+
+ +
+
+ +

◆ brawcap_buffer_back()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_back (brawcap_buffer_t *const pBuffer,
brawcap_packet_t **const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the last buffered packet of the specified packet buffer.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to read from.
[out]pPacketWill contain the buffered packet, 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_IN_USE Buffer is still in use/pending (receive/transmit).
+
+ +
+
+ +

◆ brawcap_buffer_count()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_count (brawcap_buffer_t *const pBuffer,
brawcap_buffer_packet_count_t *const pPacketCount 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the number of currently buffered packets in the specified packet buffer.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to read from.
[out]pPacketCountWill contain the number of buffered packets, 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_IN_USE Buffer is still in use/pending (receive/transmit).
+
+ +
+
+ +

◆ brawcap_buffer_capacity()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_buffer_capacity (brawcap_buffer_t *const pBuffer,
brawcap_buffer_packet_count_t *const pPacketCapacity 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the total number of packets which can be buffered by the specified packet buffer. This value represents the packet buffer capacity, which is set during buffer creation.

+
Parameters
+ + + +
[in]pBufferThe packet buffer to read from.
[out]pPacketCapacityWill contain the total number of packets which can be buffered, 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_IN_USE Buffer is still in use/pending (receive/transmit).
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00053.html b/sdk/c/doc/html/a00053.html new file mode 100644 index 0000000..608bcd3 --- /dev/null +++ b/sdk/c/doc/html/a00053.html @@ -0,0 +1,396 @@ + + + + + + + + +bRAWcap: Packet Buffer Iterator + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Typedefs | +Functions
+
Packet Buffer Iterator
Packet Buffer
+
+
+ +

bRAWcap packet buffer iterators. +More...

+ + + + + +

+Typedefs

typedef struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
 bRAWcap packet buffer iterator object.
 
+ + + + + + + + + + + + + + + + +

+Functions

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

Detailed Description

+

bRAWcap packet buffer iterators.

+

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

+
Note
Iterators should only be used as long as the packet buffer for which it was created is still available.
+
Attention
Packet buffer iterators are not synchronized. This means that if the packet buffer for which the iterator was created is modified meanwhile, the iterator is not updated.
+

List of examples:

    +
  1. Buffered Receiver
    2. +
+

Typedef Documentation

+ +

◆ brawcap_buffer_iterator_t

+ +
+
+ + + + +
typedef struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
+
+ +

#include <brawcap_types_shared.h>

+ +

bRAWcap packet buffer iterator object.

+

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

+ +
+
+

Function Documentation

+ +

◆ brawcap_buffer_iterator_create()

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

#include <brawcap.h>

+ +

Creates a new iterator for the specified buffer.

+

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

+
Parameters
+ + + + +
[out]pIteratorWill contain the new created iterator.
[in]pBufferThe buffer for which to create the iterator.
[in]startPositionThe start position of the iterator (packet buffer index/position). The specified position must be below the number of currently buffered packets, which can be resolved with brawcap_buffer_count.
+
+
+
Returns
+ + + + + + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_IN_USE Buffer is still in use/pending (receive/transmit).
BRAWCAP_STATUS_ERROR_INVALID_PARAM Start position exceeds number of buffered packets.
BRAWCAP_STATUS_ERROR_FAILED System error occurred (e.g. out of memory).
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_buffer_iterator_free()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_buffer_iterator_free (brawcap_buffer_iterator_t *const pIterator)
+
+ +

#include <brawcap.h>

+ +

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

+
Warning
Freeing a iterator is not thread safe and the user is responsible for synchronization.
+
Parameters
+ + +
[in]pIteratorThe iterator to be freed.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_buffer_iterator_next()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_buffer_iterator_next (brawcap_buffer_iterator_t *const pIterator)
+
+ +

#include <brawcap.h>

+ +

Increments the iterator to the next buffered packet.

+
Parameters
+ + +
[in]pIteratorThe iterator to be incremented.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+ +

◆ brawcap_buffer_iterator_prev()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_buffer_iterator_prev (brawcap_buffer_iterator_t *const pIterator)
+
+ +

#include <brawcap.h>

+ +

Decreases the iterator to the previous buffered packet.

+
Parameters
+ + +
[in]pIteratorThe iterator to be decremented.
+
+
+
Returns
+ + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER At least one of the pointer parameters was invalid.
+
+ +
+
+ +

◆ brawcap_buffer_iterator_eval()

+ +
+
+ + + + + + + + +
brawcap_packet_t * brawcap_buffer_iterator_eval (brawcap_buffer_iterator_t *const pIterator)
+
+ +

#include <brawcap.h>

+ +

Returns the buffered packet for the specified iterator.

+
Parameters
+ + +
[in]pIteratorThe iterator to read from.
+
+
+
Returns
+ + + + + + +
Pointer Description
brawcap_packet_t On success a valid bRAWcap packet object pointer.
NULL Invalid iterator (e.g. beyond the last or first packet).
+
+
Examples
07_receive_buffered_receiver.c.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00054.html b/sdk/c/doc/html/a00054.html new file mode 100644 index 0000000..0b7bdcf --- /dev/null +++ b/sdk/c/doc/html/a00054.html @@ -0,0 +1,2185 @@ + + + + + + + + +bRAWcap: Adapter + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Data Structures | +Macros | +Typedefs | +Enumerations | +Functions
+
Adapter
+
+
+ +

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:

    +
  1. Adapter Property Reader
    2. +
  2. Adapter Change Notifier
    3. +
+

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]nameThe adapter name on which the change happened.
[in]reasonThe reason/type of change (see brawcap_adapter_notify_reason_t).
[in]propertiesA bit field with the properties that have changed (see brawcap_adapter_properties_t).
[in]pUserPointer 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]pHandleThe handle for which the adapter change notification was registered.
[in]reasonThe reason/type of change (see brawcap_adapter_notify_reason_t).
[in]propertiesA bit field with the properties that have changed (see brawcap_adapter_properties_t).
[in]pUserPointer 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]pCountWill 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]indexThe index of the adapter in the adapter list..
[out]nameWill 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]callbackFunction pointer to the callback function which should be executed each time a adapter change is registered.
[in]pUserPointer 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]pHandleHandle to register for adapter notifications.
[in]pUserPointer to a user defined context. This allows access to user specific data within the callback.
[in]callbackFunction 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]pHandleHandle 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]pHandleThe bRAWcap handle to read from.
[out]nameWill 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]nameName of the adapter.
[out]friendlyNamePointer 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]pLengthLength 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]pHandleThe bRAWcap handle to read from.
[out]friendlyNamePointer 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]pLengthLength 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]nameName of the adapter.
[out]descriptionPointer 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]pLengthLength 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]pHandleThe bRAWcap handle to read from.
[out]descriptionPointer 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]pLengthLength 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]nameName of the adapter.
[out]pIpv4Will 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]pHandleThe bRAWcap handle to read from.
[out]pIpv4Will 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]nameName of the adapter.
[out]pIpv6Will 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]pHandleThe bRAWcap handle to read from.
[out]pIpv6Will 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]nameName of the adapter.
[out]macWill 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]pHandleThe bRAWcap handle to read from.
[out]macWill 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]nameName of the adapter.
[out]pSpeedWill 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]pHandleThe bRAWcap handle to read from.
[out]pSpeedWill 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]nameName of the adapter.
[out]pSpeedWill 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]pHandleThe bRAWcap handle to read from.
[out]pSpeedWill 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]nameName of the adapter.
[out]pConnectionWill 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]pHandleThe bRAWcap handle to read from.
[out]pConnectionWill 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]nameName of the adapter.
[out]pOperationWill 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]pHandleThe bRAWcap handle to read from.
[out]pOperationWill 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]nameName of the adapter.
[out]pMtuWill 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]pHandleThe bRAWcap handle to read from.
[out]pMtuWill 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).
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00055.html b/sdk/c/doc/html/a00055.html new file mode 100644 index 0000000..a26f07b --- /dev/null +++ b/sdk/c/doc/html/a00055.html @@ -0,0 +1,1630 @@ + + + + + + + + +bRAWcap: Receive + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Modules | +Macros | +Typedefs | +Enumerations | +Functions
+
Receive
+
+
+ +

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:

    +
  1. Simple Packet Receiver
    2. +
  2. Buffered Receiver
    3. +
  3. Timestamp Inspector
    4. +
+

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_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]pHandleHandle on which the receive returned.
[in]statusThe overall receive status see brawcap_status_t for possible return values.
[in]pBufferPointer 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]pUserPointer 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]pHandlebRAWcap handle to receive from.
[out]pPacketPacket 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]pHandlebRAWcap handle to receive from.
[in]callbackFunction pointer to user application receive callback.
[in]pUserPointer to a user defined context. Can be NULL if no user context is required.
[in]indicateNoPacketsSpecifies 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]pHandlebRAWcap 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]pHandlebRAWcap handle for attaching the buffer.
[in]pBufferPacket 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]pHandlebRAWcap handle from which the buffer is to be detached.
[in]pBufferPacket 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]pHandlebRAWcap handle to be configured.
[in]directionThe 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]pHandlebRAWcap handle to read from.
[out]pDirectionWill 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]pHandlebRAWcap handle to be configured.
[in]minPacketsThe 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]pHandlebRAWcap handle to read from.
[out]pMinPacketsWill 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]pHandlebRAWcap handle to be configured.
[in]timeout_msReceive 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]pHandlebRAWcap handle to read from.
[out]pTimeout_msWill 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]pHandlebRAWcap handle to be modified.
[in]pFilterThe 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]pHandlebRAWcap handle to read from.
[out]pFilterWill 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]pHandlebRAWcap handle to be modified.
[in]enablePromiscuous 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]pHandlebRAWcap handle to read from.
[out]pEnabledWill contain the current promiscuous mode state of the handle, afterwards.
[out]pEnabledAdapterWill 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]pHandlebRAWcap handle to read from.
[out]pCapabilitiesWill 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]pHandlebRAWcap handle to read from.
[out]pModeWill 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]pHandlebRAWcap handle to be configured.
[out]modeThe 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]pHandlebRAWcap handle to be configured.
[in]enableVLAN 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]pHandlebRAWcap handle to read from.
[out]pEnabledWill 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]pHandlebRAWcap handle to be configured.
[in]sizeDriver 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]pHandlebRAWcap handle to read from.
[out]pSizeWill 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.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00056.html b/sdk/c/doc/html/a00056.html new file mode 100644 index 0000000..9a46dee --- /dev/null +++ b/sdk/c/doc/html/a00056.html @@ -0,0 +1,1018 @@ + + + + + + + + +bRAWcap: Receive Filter + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Data Structures | +Macros | +Typedefs | +Enumerations | +Functions
+
Receive Filter
Receive
+
+
+ +

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:

    +
  1. Firewall
    2. +
+

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]pFilterWill contain the new created filter.
[in]typeSpecifies 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]pFilterThe 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]pFilterThe filter to read from.
[out]pTypeWill 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]pFilterThe filter to be modified.
[in]offsetByte offset of the filter. This value specifies at which packet byte offset the first filter byte shall be applied.
[in]lengthByte length of the filter. Specifies the number of bytes used by the filter. This value is limited to BRAWCAP_FILTER_BYTE_MAX_LENGTH.
[in]maskThe 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]ignoreBitsA 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]pFilterThe filter to read from.
[out]pOffsetWill contain the filter byte offset, afterwards.
[out]pLengthWill contain the filter byte length, afterwards.
[out]pMaskWill contain the filter mask bytes, afterwards.
[out]pIgnoreBitsWill 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]pFilterThe 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]pFilterThe 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]pFilterThe filter to read from.
[out]pActiveWill 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]pFilterThe filter to be modified.
[in]offsetThe byte offset, from packet payload beginning, to begin capturing the payload bytes.
[in]lengthThe 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]pFilterThe filter to read from.
[out]pOffsetWill contain the byte offset of the bytes to capture, afterwards.
[out]pLengthWill 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]pFilterThe filter to be modified.
[in]indicateFlag 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]pFilterThe filter to read from.
[out]pIndicateWill 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.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00057.html b/sdk/c/doc/html/a00057.html new file mode 100644 index 0000000..c84c3fd --- /dev/null +++ b/sdk/c/doc/html/a00057.html @@ -0,0 +1,698 @@ + + + + + + + + +bRAWcap: Transmit + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros | +Typedefs | +Functions
+
Transmit
+
+
+ +

Types and functions for bRAWcap transmitting. +More...

+ + + + + + + + + + + + + + +

+Macros

+#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT   512
 Default size in number of packets for driver transmit queues.
 
+#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MIN   256
 Minimum size in number of packets supported for driver transmit queues.
 
+#define BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX   4096
 Maximum size in number of packets supported for driver transmit queues.
 
+#define BRAWCAP_TX_TIMESTAMP_MODE_DEFAULT   BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
 Default timestamp mode for transmitted packets.
 
+ + + + +

+Typedefs

typedef void(* brawcap_tx_callback_t) (brawcap_handle_t *const pHandle, const brawcap_status_t status, brawcap_buffer_t *const pBuffer, void *pUser)
 Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has finished.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

brawcap_status_t brawcap_tx_packet (brawcap_handle_t *const pHandle, brawcap_packet_t *const pPacket)
 Transmits a single packet on the specified handle.
 
brawcap_status_t brawcap_tx_start (brawcap_handle_t *const pHandle, brawcap_tx_callback_t const callback, void *pUser)
 Starts the internal transmit loop.
 
brawcap_status_t brawcap_tx_stop (brawcap_handle_t *const pHandle)
 Stops the internal transmit loop.
 
brawcap_status_t brawcap_tx_buffer_send (brawcap_handle_t *const pHandle, brawcap_buffer_t *const pBuffer, const BOOLEAN synchronized)
 Pushes the specified buffer to the specified handle transmit queue.
 
brawcap_status_t brawcap_tx_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_tx_driver_queue_size_get (brawcap_handle_t *const pHandle, brawcap_queue_size_t *const pSize)
 Reads out the currently configured driver transmit queue size for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_capabilities (brawcap_handle_t *const pHandle, brawcap_timestamp_capabilities_t *const pCapabilities)
 Reads out the available transmit timestamp modes for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_mode_set (brawcap_handle_t *const pHandle, const brawcap_timestamp_mode_t mode)
 Configures the used transmit time stamping mode for the specified handle.
 
brawcap_status_t brawcap_tx_timestamp_mode_get (brawcap_handle_t *const pHandle, brawcap_timestamp_mode_t *const pMode)
 Reads out the currently configured transmit time stamping mode for the specified handle.
 
+

Detailed Description

+

Types and functions for bRAWcap transmitting.

+

Typedef Documentation

+ +

◆ brawcap_tx_callback_t

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

#include <brawcap_types_um.h>

+ +

Transmit callback which is called each time a transmission initiated with brawcap_tx_buffer_send has finished.

+
Note
Before any buffer can be transmitted the tranmission has to be started with brawcap_tx_start and stopped with brawcap_tx_stop.
+
Parameters
+ + + + + +
[in]pHandleHandle on which the transmission has finished.
[in]statusThe overall transmission status see brawcap_status_t for possible return values.
[in]pBufferPointer to the buffer which has finished transmission (initiated with brawcap_tx_buffer_send). It can be used to access all packets in the buffer - after transmission - and allows to retrieve information about each packet (e.g. (transmission) status, timestamp, ...).
[in]pUserPointer to a user defined context (allows access to user specific data within the callback).
+
+
+ +
+
+

Function Documentation

+ +

◆ brawcap_tx_packet()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_packet (brawcap_handle_t *const pHandle,
brawcap_packet_t *const pPacket 
)
+
+ +

#include <brawcap.h>

+ +

Transmits a single packet on the specified handle.

+

The caller must provide a valid packet filled up with the payload to transmit.

+

For creating a packet use brawcap_packet_create. After creating the packet set all the required packet fields and than call this function to initiate a transmission.

+

When transmission has finished (the function returns) the packet fields are updated.

+

To check if the transmission was successful check for the function return status or the packet status itself with brawcap_packet_status_get. If the packet was transmitted and transmit time stamping was enabled the packet timestamp will contain the transmission time, which be accessed with brawcap_packet_timestamp_get.

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to transmit on.
[in,out]pPacketPacket to be transmitted.
+
+
+
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_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_WARNING_NOT_ALL_PROCESSED The transmission failed (or payload was not fully transmitted).
+
+ +
+
+ +

◆ brawcap_tx_start()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_start (brawcap_handle_t *const pHandle,
brawcap_tx_callback_t const callback,
void * pUser 
)
+
+ +

#include <brawcap.h>

+ +

Starts the internal transmit loop.

+

To transmit data using this method push previously filled packet buffers to the handle by using brawcap_tx_buffer_send. After that the buffer will be locked down by the handle and added to it´s transmission queue.

+

For creating a new packet buffer which can be used for transmission use brawcap_buffer_create.

+

When a packet buffer transmission has completed the transmit callback will be called for this handle and with the corresponding packet buffer. From within the callback the buffer can be accessed for post processing (it is unlocked before entering the callback). It is also possible to do post processing from a different thread and after the callback.

+

In general executing to long in the callback can lead to a bottleneck in the transmission. It´s not as critical as it is for receiving but it should be still kept in mind.

+

Like brawcap_tx_packet does, also each packet in transmitted packet buffers will be updated (e.g. packet status, transmission timestamp). The user application can access those updated information after transmission has completed.

+

A completed packet buffer transmission will automatically detach the buffer from the handle. It is not needed to detach it explicitly (which would be required for receive buffers).

+
Note
The buffers are transmitted in the same order they have been added by the user application with brawcap_tx_buffer_send.
+
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 transmission, brawcap_tx_packet can not be used - on this handle - until tranmission is stopped with brawcap_tx_stop, because parallel transmissions are not allowed
+
Parameters
+ + + + +
[in]pHandlebRAWcap handle to transmit on.
[in]callbackFunction pointer to user application transmit callback.
[in]pUserPointer to a user defined context. Can be NULL if no user context is required.
+
+
+
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 transmit is pending or transmission is already started.
+
+ +
+
+ +

◆ brawcap_tx_stop()

+ +
+
+ + + + + + + + +
brawcap_status_t brawcap_tx_stop (brawcap_handle_t *const pHandle)
+
+ +

#include <brawcap.h>

+ +

Stops the internal transmit loop.

+
Parameters
+ + +
[in]pHandlebRAWcap handle to stop transmission on.
+
+
+
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 transmission running.
+
+ +
+
+ +

◆ brawcap_tx_buffer_send()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_buffer_send (brawcap_handle_t *const pHandle,
brawcap_buffer_t *const pBuffer,
const BOOLEAN synchronized 
)
+
+ +

#include <brawcap.h>

+ +

Pushes the specified buffer to the specified handle transmit queue.

+

After pushing a packet buffer to the handle for transmission it is locked down by the handle until transmission has completed (and the transmit callback is called).

+

With the synchronized flag it is possible to activate a synchronized transmission of the specified packet buffer. This means that the driver reads the time gap between each packet in the packet buffer and waits until it has been elapsed before initiating transmission.

+
Attention
For synchronized transmission it is necessary to sort the packets in the buffer by rising timestamp. Furthermore, it is currently not supported to specify a "start time" when the first packet should be transmitted. Therefore if you want to start transmission depending on the first packet timestamp you should wait until the time is reached and after this initiate the transmission by calling this function. The driver itself only evaluates the time gaps between each packet in the buffer.
+
Note
Packet buffers are transmitted in the same order they was pushed to the handle.
+
Invariant
Keep in mind that the packet timestamp is updated after transmission has been completed by the transmission timestamp (depending on the configured timestamp mode). Therefore if there was a packet timestamp set for example to send synchronized, this timestamp will be overwritten.
+
Parameters
+ + + + +
[in]pHandlebRAWcap handle for sending the buffer.
[in]pBufferPacket buffer to be sent.
[in]synchronizedFlag indicating if the packets in the packet buffer should be sent synchronized.
+
+
+
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_tx_driver_queue_size_set()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_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.

+

For transmission the driver queue size may be increased if high data rates should be reached (for example 10GBit/s). With a larger transmission queue the driver can forward more packets to the network adapter at the same time. Therefore if the transmission rate is below the expected value it may be solved by a larger driver queue size.

+

The driver queue size can be adjusted at any time.

+
Note
The default queue size is
+
See also
BRAWCAP_TX_DRIVER_QUEUE_SIZE_DEFAULT (in number of packets). And its max limitation is
+
+BRAWCAP_TX_DRIVER_QUEUE_SIZE_MAX (in number of packets).
+
Attention
Reducing the queue size during runtime may result in packet transmission cancellation. This may be the case if there are more packets pending for transmission than the new size can accommodate.
+
Parameters
+ + + +
[in]pHandlebRAWcap handle to be configured.
[in]sizeDriver transmit 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.
+
+ +
+
+ +

◆ brawcap_tx_driver_queue_size_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_driver_queue_size_get (brawcap_handle_t *const pHandle,
brawcap_queue_size_t *const pSize 
)
+
+ +

#include <brawcap.h>

+ +

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

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[out]pSizeWill contain the currently configured driver transmit 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.
+
+ +
+
+ +

◆ brawcap_tx_timestamp_capabilities()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_timestamp_capabilities (brawcap_handle_t *const pHandle,
brawcap_timestamp_capabilities_t *const pCapabilities 
)
+
+ +

#include <brawcap.h>

+ +

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

+

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

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[out]pCapabilitiesWill contain the available transmit 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.
+
+ +
+
+ +

◆ brawcap_tx_timestamp_mode_set()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_timestamp_mode_set (brawcap_handle_t *const pHandle,
const brawcap_timestamp_mode_t mode 
)
+
+ +

#include <brawcap.h>

+ +

Configures the used transmit 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_tx_timestamp_capabilities.
+
Parameters
+ + + +
[in]pHandlebRAWcap handle to be configured.
[in]modeThe transmit 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.
+
+ +
+
+ +

◆ brawcap_tx_timestamp_mode_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_tx_timestamp_mode_get (brawcap_handle_t *const pHandle,
brawcap_timestamp_mode_t *const pMode 
)
+
+ +

#include <brawcap.h>

+ +

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

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[out]pModeWill contain the currently used transmit 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.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00058.html b/sdk/c/doc/html/a00058.html new file mode 100644 index 0000000..a176f6a --- /dev/null +++ b/sdk/c/doc/html/a00058.html @@ -0,0 +1,704 @@ + + + + + + + + +bRAWcap: Statistics + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Data Structures | +Macros | +Enumerations | +Functions
+
Statistics
+
+
+ +

Types and functions for bRAWcap statistics. +More...

+ + + + + + + + + + + +

+Data Structures

struct  brawcap_stats_header_t
 Header describing given bRAWcap stats structure. More...
 
struct  brawcap_stats_rx_t
 The bRAWcap receive statistics. More...
 
struct  brawcap_stats_tx_t
 The bRAWcap transmit statistics. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterReceivedPacketsTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterReceivedBytesTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID(__stats_rx)    (__stats_rx.adapterValid & _BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_rx_t::adapterDroppedPacketsTotal member of the given receive stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID)
 Indicates if the brawcap_stats_tx_t::adapterCompletedPacketsTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID)
 Indicates if the brawcap_stats_tx_t::adapterCompletedBytesTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID(__stats_tx)    (__stats_tx.adapterValid & _BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID )
 Indicates if the brawcap_stats_tx_t::adapterCanceledPacketsTotal member of the given transmit stats is valid. This statistic is provided from the underlying network adapter driver and may be supported or not.
 
+#define BRAWCAP_STATS_RX_SIZEOF_REVISION_1   _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_rx_t, handleDroppedPacketsToLong)
 Returns the size of receive statistics revision 1.
 
+#define BRAWCAP_STATS_TX_SIZEOF_REVISION_1   _BRAWCAP_SIZEOF_STRUCT(brawcap_stats_tx_t, handleCompletedBytesTotal)
 Returns the size of transmit statistics revision 1.
 
+ + + + + + + + + + +

+Enumerations

enum  brawcap_stats_type_t {
+  BRAWCAP_STATS_TYPE_RX = 1 +,
+  BRAWCAP_STATS_TYPE_TX = 2 +
+ }
 List of all available statistic types. More...
 
enum  brawcap_stats_rx_revision_t { BRAWCAP_STATS_RX_REVISION_1 = 1 + }
 List of all available receive statistic revisions. More...
 
enum  brawcap_stats_tx_revision_t { BRAWCAP_STATS_TX_REVISION_1 = 1 + }
 List of all available transmit statistic revisions. More...
 
+ + + + + + + +

+Functions

brawcap_status_t brawcap_stats_rx (brawcap_handle_t *const pHandle, brawcap_stats_rx_t *const pStats)
 Reads out the available receive statistic counters for the specified handle.
 
brawcap_status_t brawcap_stats_tx (brawcap_handle_t *const pHandle, brawcap_stats_tx_t *const pStats)
 Reads out the available transmit statistic counters for the specified handle.
 
+

Detailed Description

+

Types and functions for bRAWcap statistics.

+

Data Structure Documentation

+ +

◆ brawcap_stats_header_t

+ +
+
+ + + + +
struct brawcap_stats_header_t
+
+

Header describing given bRAWcap stats structure.

+
Attention
If your create a new bRAWcap stats structure you must always initialize the header first before make use of it. This is required to allow backward compatibility for applications using older versions.
+
+ + + + + + + + + + +
Data Fields
+BYTE +type +Indicates which type of stats it is.
+BYTE +revision +Indicates the revision of the stats.
Note
It is preferred to always use the latest version available in your bRAWcap header file. But you can also use older versions if you dont want to access members added in the newer versions.
+
+UINT16 +size +Should be set to the size of the structure depending on it´s type and revision. You should use the BRAWCAP_STATS_..._SIZEOF_REVISION_X macros for initializing this member.
+ +
+
+ +

◆ brawcap_stats_rx_t

+ +
+
+ + + + +
struct brawcap_stats_rx_t
+
+

The bRAWcap receive statistics.

+

This can be used to retrieve all available bRAWcap statistics and counters related to receive path. After creating the structure, its header has to be initialized.

+

The brawcap_stats_header_t::type shall be set to BRAWCAP_STATS_TYPE_RX.

+

The brawcap_stats_header_t::revision shall be set to one of the following values:

+

The brawcap_stats_header_t::size shall be set depending on your selected version by using the macro:

+
Attention
User is responsible for initializing the structure header before using it. Otherwise it may lead to undefined behaviour.
+
Examples
06_filter_firewall.c.
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data Fields
+brawcap_stats_header_t +header +Header for receive statistics. This has to be always initialized by the user after creation before using it.
+UINT32 +adapterValid +Bitfield indicating which counters provided by the underlying network adapter driver are valid.
+UINT64 +adapterReceivedPacketsTotal +Total number of received packets by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_RX_ADAPTER_RECEIVED_PACKETS_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +adapterReceivedBytesTotal +Total number of received bytes by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_RX_ADAPTER_RECEIVED_BYTES_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +adapterDroppedPacketsTotal +Total number of received bytes by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +driverIndicatedPacketsTotal +The total number of indicated packets to the upper network stack by bRAWcap on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverReceivedPacketsTotal +The total number of received packets by bRAWcap on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter..
+
+UINT64 +handleReceivedPacketsTotal +The total number of received packets by the given bRAWcap handle.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleReceivedPacketsMatched +The total number of packets which have matched the given bRAWcap handle filter.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleReceivedPacketsQueued +The total number of packets which was queued to the handles driver queue.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleReceivedPacketsDirect +The total number of packets which could be directly delivered to user space memory.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleReceivedBytesTotal +The total number of received bytes by the given bRAWcap handle.
Note
This counter relates to a handle and will be deleted when the handle is closed
+
+UINT64 +handleDroppedPacketsTotal +The total number of packets which was dropped for the handle (sum of all reasons).
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleDroppedPacketsQueue +The total number of packets which was dropped for the handle because of resources (driver queue overrun).
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleDroppedPacketsToLong +The total number of packets which was dropped for the handle their length exceeds the handles configured max packet size.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+ +
+
+ +

◆ brawcap_stats_tx_t

+ +
+
+ + + + +
struct brawcap_stats_tx_t
+
+

The bRAWcap transmit statistics.

+

This can be used to retrieve all available bRAWcap statistics and counters related to transmit path. After creating the structure, its header has to be initialized.

+

The brawcap_stats_header_t::type shall be set to BRAWCAP_STATS_TYPE_TX.

+

The brawcap_stats_header_t::revision shall be set to one of the following values:

+

The brawcap_stats_header_t::size shall be set depending on your selected version by using the macro:

+
Attention
User is responsible for initializing the structure header before using it. Otherwise it may lead to undefined behaviour.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data Fields
+brawcap_stats_header_t +header +Header for transmit statistics. This has to be always initialized by the user after creation before using it.
+UINT32 +adapterValid +Bitfield indicating which counters provided by the underlying network adapter driver are valid.
+UINT64 +adapterCompletedPacketsTotal +Total number of (completed) transmitted packets by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_TX_ADAPTER_COMPLETED_PACKETS_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +adapterCompletedBytesTotal +Total number of (completed) transmitted bytes by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_TX_ADAPTER_COMPLETED_BYTES_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +adapterCanceledPacketsTotal +Total number of canceled transmitted packets by the underlying network adapter.
Note
You should check if the network adapter supports this counter with BRAWCAP_STATS_TX_ADAPTER_CANCELED_PACKETS_TOTAL_VALID. If the counter is not supported it will be always zero.
+
+UINT64 +driverInitiatedPacketsTotal +Total number of initiated packets to transmit by the bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverInitiatedPacketsStack +Initiated packets to transmit from upper network stack detected by bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverInitiatedPacketsHandles +Initiated packets to transmit from bRAWcap driver itself on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCanceledPacketsTotal +Total number of canceled packets to transmit by the bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCanceledPacketsStack +Canceled packets to transmit from the upper network stack detected by bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCanceledPacketsHandles +Canceled packets to transmit from bRAWcap driver itself on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCompletedPacketsTotal +Total number of completed transmitted packets detected by bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCompletedPacketsStack +Completed packets to transmit from the upper network stack detected by bRAWcap driver on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +driverCompletedPacketsHandles +Completed packets to transmit from the bRAWcap driver itself on the corresponding adapter.
Note
This counter will reset if bRAWcap driver is restarted, or it is deactivated on the adapter.
+
+UINT64 +handleInitiatedPacketsTotal +Total number of initiated packets to transmit for the handle.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleCanceledPacketsTotal +Total number of canceled packets to transmit for the handle.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleCompletedPacketsTotal +Total number of completed transmitted packets for the handle.
Note
This counter relates to a handle and will be deleted when the handle is closed.
+
+UINT64 +handleCompletedBytesTotal +
+ +
+
+

Enumeration Type Documentation

+ +

◆ brawcap_stats_type_t

+ +
+
+ + + + +
enum brawcap_stats_type_t
+
+ +

#include <brawcap_types_shared.h>

+ +

List of all available statistic types.

+ + + +
Enumerator
BRAWCAP_STATS_TYPE_RX 

Type for receive stats.

+
BRAWCAP_STATS_TYPE_TX 

Type for transmit stats.

+
+ +
+
+ +

◆ brawcap_stats_rx_revision_t

+ +
+
+ + + + +
enum brawcap_stats_rx_revision_t
+
+ +

#include <brawcap_types_shared.h>

+ +

List of all available receive statistic revisions.

+ + +
Enumerator
BRAWCAP_STATS_RX_REVISION_1 

Revision 1 for receive stats.

+
+ +
+
+ +

◆ brawcap_stats_tx_revision_t

+ +
+
+ + + + +
enum brawcap_stats_tx_revision_t
+
+ +

#include <brawcap_types_shared.h>

+ +

List of all available transmit statistic revisions.

+ + +
Enumerator
BRAWCAP_STATS_TX_REVISION_1 

Revision 1 for transmit stats.

+
+ +
+
+

Function Documentation

+ +

◆ brawcap_stats_rx()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_stats_rx (brawcap_handle_t *const pHandle,
brawcap_stats_rx_t *const pStats 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the available receive statistic counters for the specified handle.

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[in,out]pStatsWill contain the current receive statistic counters, afterwards. The header of the statistic struct hast to be filled by the caller, before calling this function. If it is not filled or contains invalid data, the function will fail and return a error.
+
+
+
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_INVALID_PARAM The header was invalid (type or revision).
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE The specified size in the header was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED Communicating with bRAWcap driver failed.
+
+
Examples
06_filter_firewall.c.
+
+ +
+
+ +

◆ brawcap_stats_tx()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_stats_tx (brawcap_handle_t *const pHandle,
brawcap_stats_tx_t *const pStats 
)
+
+ +

#include <brawcap.h>

+ +

Reads out the available transmit statistic counters for the specified handle.

+
Parameters
+ + + +
[in]pHandlebRAWcap handle to read from.
[in,out]pStatsWill contain the current transmit statistic counters, afterwards. The header of the statistic struct hast to be filled by the caller, before calling this function. If it is not filled or contains invalid data, the function will fail and return a error.
+
+
+
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_INVALID_PARAM The header was invalid (type or revision).
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE The specified size in the header was invalid.
BRAWCAP_STATUS_ERROR_DRIVER_IO_FAILED Communicating with bRAWcap driver failed.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00059.html b/sdk/c/doc/html/a00059.html new file mode 100644 index 0000000..b8fd686 --- /dev/null +++ b/sdk/c/doc/html/a00059.html @@ -0,0 +1,132 @@ + + + + + + + + +bRAWcap: Importing + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Macros
+
Importing
+
+
+ +

Defines required for automatic/dynamic bRAWcap API function importing. +More...

+ + + + + +

+Macros

+#define _BRAWCAP_API_FUNC(returnType)   __declspec(dllimport) returnType __cdecl
 Dynamic/automatic function import for loading/including.
 
+

Detailed Description

+

Defines required for automatic/dynamic bRAWcap API function importing.

+
+ + + + + + diff --git a/sdk/c/doc/html/a00060.html b/sdk/c/doc/html/a00060.html new file mode 100644 index 0000000..1856bd6 --- /dev/null +++ b/sdk/c/doc/html/a00060.html @@ -0,0 +1,407 @@ + + + + + + + + +bRAWcap: Logging + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
+Enumerations | +Functions
+
Logging
+
+
+ +

Types and functions for handling/modifying the bRAWcap logging. +More...

+ + + + + + + + +

+Enumerations

enum  brawcap_log_level_t {
+  BRAWCAP_LOG_LEVEL_DEBUG = 0x01 +,
+  BRAWCAP_LOG_LEVEL_VERBOSE = 0x02 +,
+  BRAWCAP_LOG_LEVEL_NOTICE = 0x04 +,
+  BRAWCAP_LOG_LEVEL_WARNING = 0x08 +,
+  BRAWCAP_LOG_LEVEL_ERROR = 0x10 +
+ }
 List of bRAWcap log levels. More...
 
enum  brawcap_log_type_t {
+  BRAWCAP_LOG_TYPE_GENERIC = 0x01 +,
+  BRAWCAP_LOG_TYPE_ADAPTER = 0x02 +,
+  BRAWCAP_LOG_TYPE_RECEIVE = 0x04 +,
+  BRAWCAP_LOG_TYPE_TRANSMIT = 0x08 +,
+  BRAWCAP_LOG_TYPE_LICENSE = 0x10 +,
+  BRAWCAP_LOG_TYPE_ALL = 0xFFFF +
+ }
 List of bRAWcap log types. More...
 
+ + + + + + + + + + +

+Functions

brawcap_status_t brawcap_log_level_set (const brawcap_log_type_t type, const brawcap_log_level_t level, const char *pKey)
 Sets the current log level for the given log type to the specified log level.
 
brawcap_status_t brawcap_log_levels_set (const UINT32 type, const UINT32 level, const char *pKey)
 Sets the current log levels for the given log types to the specified log levels.
 
brawcap_status_t brawcap_log_level_get (const brawcap_log_type_t type, brawcap_log_level_t *const pLevel)
 Reads the level(s) for the given log type.
 
+

Detailed Description

+

Types and functions for handling/modifying the bRAWcap logging.

+

This module provides some functions for configuring the bRAWcap logging behavior. The bRAWcap logger supports different log levels and types, which allows to configure the logging for specific types independent to each other. Increasing the log level may help during development of the user application which shall use bRAWcap.

+
Note
If you think there is a problem with bRAWcap, please enable detailed logging, run your application until the problem occurs and then send the created bRAWcap log files to b-plus.
+
Attention
For release builds log levels such as verbose shall be avoided, because they can lead to performance degradation.
+

Enumeration Type Documentation

+ +

◆ brawcap_log_level_t

+ +
+
+ + + + +
enum brawcap_log_level_t
+
+ +

#include <brawcap_types_um.h>

+ +

List of bRAWcap log levels.

+

The log levels allows to (de)activate additional log entries. This can be especially useful during development, to get a more detailed log from bRAWcap.

+ + + + + + +
Enumerator
BRAWCAP_LOG_LEVEL_DEBUG 

Debug log level is for debugging bRAWcap itself only. Therefore it can only be enabled if the application is registered with higher privilege.

+
Note
Default: Deactivated
+
BRAWCAP_LOG_LEVEL_VERBOSE 

Verbose log level will include many informative loggings. Those loggings gives more info why some API calls may fail. This will especially contain those cases in which the caller has provided invalid parameters. It should be activated only for development, testing or error research.

+
Note
Default: Deactivated
+
BRAWCAP_LOG_LEVEL_NOTICE 

Notice log level will include some loggings which gives information of the current bRAWcap state. This may be disabled to decrease logging to a minimum.

+
Note
Default: Activated
+
BRAWCAP_LOG_LEVEL_WARNING 

Warning log level will include loggings for unexpected states. This level should never be disabled.

+
Note
Default: Activated
+
BRAWCAP_LOG_LEVEL_ERROR 

Error log level will include loggings if something went completely wrong and bRAWcap could not solve the issue. Those loggings should never appear, if so bRAWcap may be in a invalid state. If loggings contain such a logentry please try to reproduce it again with all log levels enabled and send the logfile (with a short description of how to reproduce it) to b-plus. This should really never be disabled.

+
Note
Default: Activated
+
+ +
+
+ +

◆ brawcap_log_type_t

+ +
+
+ + + + +
enum brawcap_log_type_t
+
+ +

#include <brawcap_types_um.h>

+ +

List of bRAWcap log types.

+

The log types allows to adjust log levels for each type independent. To distinguish between different types each logentry will be prefixed with it´s type, this increases the readability of the logfile.

+ + + + + + +
Enumerator
BRAWCAP_LOG_TYPE_GENERIC 

Generic loggings will be used for everything which has no specific type.

+
BRAWCAP_LOG_TYPE_ADAPTER 

Adapter loggings will be used for anything which relates to the local adapter handling.

+
BRAWCAP_LOG_TYPE_RECEIVE 

Receive loggings will be used for anything which relates to receiving.

+
BRAWCAP_LOG_TYPE_TRANSMIT 

Transmit loggings will be used for anything which relates to transmitting.

+
BRAWCAP_LOG_TYPE_LICENSE 

License loggings will be used for anything which relates to licensing.

+
+ +
+
+

Function Documentation

+ +

◆ brawcap_log_level_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_log_level_set (const brawcap_log_type_t type,
const brawcap_log_level_t level,
const char * pKey 
)
+
+ +

#include <brawcap.h>

+ +

Sets the current log level for the given log type to the specified log level.

+
Parameters
+ + + + +
[in]typeLog type for which to configure the log level.
[in]levelThe log level to be applied.
[in]pKeyKey required to activate debug logging. For any other log level than BRAWCAP_LOG_LEVEL_DEBUG this parameter is not required and should be set to NULL.
+
+
+
Returns
+ + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE Attempted to enable debug logging with wrong key.
BRAWCAP_STATUS_ERROR_INVALID_PARAM None of the specified log types is available.
+
+ +
+
+ +

◆ brawcap_log_levels_set()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_log_levels_set (const UINT32 type,
const UINT32 level,
const char * pKey 
)
+
+ +

#include <brawcap.h>

+ +

Sets the current log levels for the given log types to the specified log levels.

+
Parameters
+ + + + +
[in]typeLog types for which to configure the log level(s). Value has to be interpreted as bitfield. This allows to (de)activate levels for several types with only one call.
[in]levelThe log levels to be applied. Value has to be interpreted as bitfield. This allows to (de)activate several levels with only one call.
[in]pKeyKey required to activate debug logging. For any other log level than BRAWCAP_LOG_LEVEL_DEBUG this parameter is not required and should be set to NULL.
+
+
+
Returns
+ + + + + + + + +
Status Description
BRAWCAP_STATUS_SUCCESS Success.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE Attempted to enable debug logging with wrong key.
BRAWCAP_STATUS_ERROR_INVALID_PARAM None of the specified log types is available.
+
+ +
+
+ +

◆ brawcap_log_level_get()

+ +
+
+ + + + + + + + + + + + + + + + + + +
brawcap_status_t brawcap_log_level_get (const brawcap_log_type_t type,
brawcap_log_level_t *const pLevel 
)
+
+ +

#include <brawcap.h>

+ +

Reads the level(s) for the given log type.

+
Parameters
+ + + +
[in]typeLog type for which to read the log level. It is only possible to retrieve the log level for one type. Call this function for each type to resolve all log levels.
[out]pLevelWill contain the currently configured log level(s), afterwards. This value shall be interpreted as bitfield, which allows to resolve all log levels for the type with only one call.
+
+
+
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 log types is invalid.
+
+ +
+
+
+ + + + + + diff --git a/sdk/c/doc/html/a00918.html b/sdk/c/doc/html/a00918.html new file mode 100644 index 0000000..7137b45 --- /dev/null +++ b/sdk/c/doc/html/a00918.html @@ -0,0 +1,229 @@ + + + + + + + + +bRAWcap: 03_generic_handle_opener.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
03_generic_handle_opener.c
+
+
+

This example shows how to open and close bRAWcap handles to each available adapter on the machine. If any unexpected status is returned, it will close all handles and print the unexpected status to console. Therefore brawcap_last_status is used.

+
1/**
+
2 * @file 03_generic_handle_opener.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates the usage of the generic bRAWcap functions.
+
5 *
+
6 * It shows how to:
+
7 * - Open a bRAWcap handle
+
8 * - Close a previously opened handle
+
9 * - Check for unexpected status by using @ref brawcap_last_status.
+
10 *
+
11 * This example makes use of C only.
+
12 *
+
13 * @version 1.0
+
14 *
+
15 * @date 2023-03-28
+
16 *
+
17 * @copyright
+
18 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
19 *
+
20 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
21 *
+
22 * Redistribution in source or any other form, with or without modification, is not permitted.
+
23 *
+
24 * You may use this code under the according license terms of b-plus.
+
25 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
26 */
+
27// Include bRAWcap
+
28#include "libbrawcap.h"
+
29
+
30// C STD
+
31#include <stdlib.h> // for malloc & free
+
32#include <stdio.h> // for printf
+
33
+
34int main(int argc, char** argv)
+
35{
+
36 // Set console title
+
37 SetConsoleTitleA("bRAWcap Example - Handle Opener");
+
38
+
39 brawcap_handle_t** pHandleArray = 0;
+
40 brawcap_adapter_count_t numberAdapters = 0;
+
41 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
42
+
43 do
+
44 {
+
45#if 1 // Get number of available adapters
+
46 status = brawcap_adapter_list_count(&numberAdapters);
+
47 if(!BRAWCAP_SUCCESS(status))
+
48 break;
+
49#endif
+
50
+
51#if 1 // Allocate array for storing opened bRAWcap handles
+
52 pHandleArray = (brawcap_handle_t**) calloc(numberAdapters, sizeof(brawcap_handle_t*));
+
53 memset(pHandleArray, 0, numberAdapters);
+
54#endif
+
55
+
56#if 1 // Get name for each available adapter and try to open a bRAWcap handle
+
57 for(int index = 0; index < numberAdapters; ++index)
+
58 {
+
59 brawcap_adapter_name_t name = { '\0'};
+
60 status = brawcap_adapter_list_at(index, name);
+
61 if(!BRAWCAP_SUCCESS(status))
+
62 break;
+
63
+
64 status = brawcap_open(name, &pHandleArray[index]);
+
65 if(!BRAWCAP_SUCCESS(status))
+
66 break;
+
67
+
68 printf("%02d. bRAWcap handle (%p) opened to %s.\n", index + 1, pHandleArray[index], name);
+
69 }
+
70 #endif
+
71 }while(0);
+
72
+
73 printf("\n");
+
74
+
75 // Close all opened handles
+
76 for(int index = numberAdapters - 1; index >= 0; --index)
+
77 {
+
78 if (pHandleArray[index])
+
79 {
+
80 status = brawcap_close(pHandleArray[index]);
+
81 printf("%02d. bRAWcap handle (%p) closed.\n", index + 1, pHandleArray[index]);
+
82 }
+
83 }
+
84
+
85 // Free alloacted handle array
+
86 free(pHandleArray);
+
87
+
88 // If anything unexpected was returned,
+
89 // request the status again and print it to console.
+
90#if 1
+
91 if(!BRAWCAP_SUCCESS(status))
+
92 {
+
93 printf("Unexpected status occurred: %d", brawcap_last_status());
+
94 return -1;
+
95 }
+
96#endif
+
97
+
98 return 0;
+
99}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
+ + + + + + diff --git a/sdk/c/doc/html/a00919.html b/sdk/c/doc/html/a00919.html new file mode 100644 index 0000000..831fbac --- /dev/null +++ b/sdk/c/doc/html/a00919.html @@ -0,0 +1,225 @@ + + + + + + + + +bRAWcap: 04_version_comparator.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
04_version_comparator.c
+
+
+

This example shows how to read library (/API) and driver version of bRAWcap. After reading the versions it will check if both versions match.

+
1/**
+
2 * @file 04_version_comparator.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates how to use the bRAWcap version.
+
5 *
+
6 * It shows how to:
+
7 * - Read library and driver version
+
8 * - Print readable versions
+
9 * - Do a version compare
+
10 *
+
11 * This example makes use of C only.
+
12 *
+
13 * @version 1.0
+
14 *
+
15 * @date 2023-03-28
+
16 *
+
17 * @copyright
+
18 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
19 *
+
20 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
21 *
+
22 * Redistribution in source or any other form, with or without modification, is not permitted.
+
23 *
+
24 * You may use this code under the according license terms of b-plus.
+
25 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
26 */
+
27// Include bRAWcap
+
28#include "libbrawcap.h"
+
29
+
30// C STD
+
31#include <stdio.h> // for printf
+
32
+
33int main(int argc, char** argv)
+
34{
+
35 // Set console title
+
36 SetConsoleTitleA("bRAWcap Example - Version Comparator");
+
37
+
38 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
39 brawcap_adapter_count_t numberAdapters = 0;
+
40 brawcap_version_t apiVersion = {0};
+
41 brawcap_version_t driverVersion = {0};
+
42
+
43 status = brawcap_version_api(&apiVersion);
+
44 if(!BRAWCAP_SUCCESS(status))
+
45 printf("Unexpected status (%d) while reading API(/library) version.\n", status);
+
46 else
+
47 printf("Loaded library/API version is: %u.%u.%u.%u\n", apiVersion.fragments.major, apiVersion.fragments.minor,
+
48 apiVersion.fragments.patch, apiVersion.fragments.build);
+
49
+
50 status = brawcap_adapter_list_count(&numberAdapters);
+
51 if(!BRAWCAP_SUCCESS(status))
+
52 printf("Unexpected status (%d) while reading number of available adapters.\n", status);
+
53 else if(!numberAdapters)
+
54 printf("No adapter available to read driver version.\n");
+
55 else
+
56 {
+
57 brawcap_adapter_name_t name = { '\0' };
+
58 status = brawcap_adapter_list_at(0, name);
+
59 if(!BRAWCAP_SUCCESS(status))
+
60 printf("Unexpected status (%d) while reading adapter name.", status);
+
61 else
+
62 {
+
63 brawcap_handle_t* handle = 0;
+
64 status = brawcap_open(name, &handle);
+
65 if(!BRAWCAP_SUCCESS(status))
+
66 printf("Unexpected status (%d) while handle opening.", status);
+
67 else
+
68 {
+
69 status = brawcap_version_driver(handle, &driverVersion);
+
70 if(!BRAWCAP_SUCCESS(status))
+
71 printf("Unexpected status (%d) while reading driver version.\n", status);
+
72 else
+
73 {
+
74 printf("Loaded driver version is: %u.%u.%u.%u\n", driverVersion.fragments.major,
+
75 driverVersion.fragments.minor, driverVersion.fragments.patch, driverVersion.fragments.build);
+
76
+
77 if(driverVersion.complete == apiVersion.complete)
+
78 printf("Driver and API version MATCH. :-)\n");
+
79 else
+
80 printf("Driver and API version does NOT MATCH. :-(\n");
+
81 }
+
82 brawcap_close(handle);
+
83 }
+
84 }
+
85 }
+
86 return 0;
+
87}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
brawcap_version_t
bRAWcap version.
Definition: brawcap_types_shared.h:426
+
brawcap_version_fragments_t::minor
UINT16 minor
Minor version.
Definition: brawcap_types_shared.h:407
+
brawcap_version_fragments_t::major
UINT16 major
Major version.
Definition: brawcap_types_shared.h:416
+
brawcap_version_fragments_t::patch
UINT16 patch
Patch version.
Definition: brawcap_types_shared.h:399
+
brawcap_version_fragments_t::build
UINT16 build
Build version.
Definition: brawcap_types_shared.h:390
+
brawcap_version_t::complete
UINT64 complete
Definition: brawcap_types_shared.h:428
+
brawcap_version_t::fragments
brawcap_version_fragments_t fragments
Definition: brawcap_types_shared.h:427
+
brawcap_version_api
brawcap_status_t brawcap_version_api(brawcap_version_t *const pVersion)
Returns loaded bRAWcap library version.
+
brawcap_version_driver
brawcap_status_t brawcap_version_driver(brawcap_handle_t *const pHandle, brawcap_version_t *const pVersion)
Reads current version of loaded bRAWcap driver.
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
+ + + + + + diff --git a/sdk/c/doc/html/a00920.html b/sdk/c/doc/html/a00920.html new file mode 100644 index 0000000..6663cbd --- /dev/null +++ b/sdk/c/doc/html/a00920.html @@ -0,0 +1,352 @@ + + + + + + + + +bRAWcap: 01_adapter_property_reader.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
01_adapter_property_reader.c
+
+
+

This example shows how to get all currently available adapters on the machine. And how to get the properties for each adapter. The adapters and their properties will be printed to command line output.

+
Attention
This example requires a valid bRAWcap license. Reading adapter properties is not part of the demo.
+
1/**
+
2 * @file 01_adapter_property_reader.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates the usage of the adapter handling module.
+
5 *
+
6 * It shows how to:
+
7 * - Update and use the adapter list
+
8 * - Read adapter properties
+
9 *
+
10 * This example makes use of C only.
+
11 *
+
12 * @attention This example requires a valid bRAWcap license.
+
13 * Reading adapter properties is not part of the demo.
+
14 *
+
15 * @version 1.0
+
16 *
+
17 * @date 2023-03-24
+
18 *
+
19 * @copyright
+
20 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
21 *
+
22 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
23 *
+
24 * Redistribution in source or any other form, with or without modification, is not permitted.
+
25 *
+
26 * You may use this code under the according license terms of b-plus.
+
27 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
28 */
+
29// Include bRAWcap
+
30#include "libbrawcap.h"
+
31
+
32// C STD
+
33#include <stdlib.h> // for malloc & free
+
34#include <stdio.h> // for printf
+
35
+
36int main(int argc, char** argv)
+
37{
+
38 // Set console title
+
39 SetConsoleTitleA("bRAWcap Example - Adapter Property Reader");
+
40
+
41 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
42
+
43 // Encapsulate all in a single loop.
+
44 // This allow breaking execution if something unexpected happens.
+
45 do
+
46 {
+
47#if 1 // Update list of available adapters
+
48 // NOTE: The list is initialized during loading/initializing bRAWcap.
+
49 status = brawcap_adapter_list_update();
+
50 if(!BRAWCAP_SUCCESS(status))
+
51 break;
+
52#endif
+
53#if 1 // Get number of currently available adapters
+
54 brawcap_adapter_count_t adapterCount = 0;
+
55 status = brawcap_adapter_list_count(&adapterCount);
+
56 if(!BRAWCAP_SUCCESS(status))
+
57 break;
+
58#endif
+
59#if 1 // Now loop through each entry of the list.
+
60 // Here we retrieve all it´s available adapter properties and print them to console.
+
61 for(unsigned int index = 0; index < adapterCount; ++index)
+
62 {
+
63#if 1 // Get adapter name from list
+
64 brawcap_adapter_name_t name = {'\0'};
+
65 status = brawcap_adapter_list_at(index, name);
+
66 if(!BRAWCAP_SUCCESS(status))
+
67 break;
+
68 printf("%02u. Adapter - Name: %s ", index + 1, name);
+
69#endif
+
70#if 1 // Resolve adapter friendly name by using it´s name
+
71 UINT32 friendlyNameLength = 0;
+
72 char* friendlyName = NULL;
+
73 status = brawcap_adapter_friendly_name(name, friendlyName, &friendlyNameLength);
+
74 // We expect this return value because our buffer is not yet initialized (zero).
+
75 // If we use the function like this, it will inform us of the required this by setting friendlyNameLength.
+
76 if(status == BRAWCAP_STATUS_ERROR_OVERRUN)
+
77 {
+
78 // friendlyNameLength is set to the required length, so lets use it to create the buffer
+
79 friendlyName = malloc(friendlyNameLength);
+
80 // Now call the function again with a valid buffer
+
81 status = brawcap_adapter_friendly_name(name, friendlyName, &friendlyNameLength);
+
82 if(!BRAWCAP_SUCCESS(status))
+
83 break;
+
84 }
+
85 else
+
86 break;
+
87 printf("Friendly Name: %s ", friendlyName);
+
88#endif
+
89#if 1 // Resolve adapter description by using it´s name
+
90 UINT32 descriptionLength = 0;
+
91 char* description = NULL;
+
92 status = brawcap_adapter_description(name, description, &descriptionLength);
+
93 // Here we have the same handling like we had for the friendly name...
+
94 if(status == BRAWCAP_STATUS_ERROR_OVERRUN)
+
95 {
+
96 // friendlyNameLength is set to the required length, so lets use it to create the buffer
+
97 description = malloc(descriptionLength);
+
98 // Now call the function again with a valid buffer
+
99 status = brawcap_adapter_description(name, description, &descriptionLength);
+
100 if(!BRAWCAP_SUCCESS(status))
+
101 break;
+
102 }
+
103 else
+
104 break;
+
105 printf("Description: %s ", description);
+
106#endif
+
107#if 1 // Resolve adapter MAC address by using it´s name
+
108 brawcap_adapter_mac_t mac = {0};
+
109 status = brawcap_adapter_mac(name, mac);
+
110 if (!BRAWCAP_SUCCESS(status))
+
111 break;
+
112 printf("MAC: %02X:%02X:%02X:%02X:%02X:%02X ", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
+
113#endif
+
114#if 1 // Resolve adapter operation state by using it´s name
+
115 brawcap_adapter_operation_state_t operationState = BRAWCAP_ADAPTER_OPERATION_UNKNOWN;
+
116 status = brawcap_adapter_operation(name, &operationState);
+
117 if(!BRAWCAP_SUCCESS(status))
+
118 break;
+
119 switch (operationState)
+
120 {
+
121 case BRAWCAP_ADAPTER_OPERATION_UNKNOWN: printf("Operation: %s ", "Unknown"); break;
+
122 case BRAWCAP_ADAPTER_OPERATION_DOWN: printf("Operation: %s ", "Down"); break;
+
123 case BRAWCAP_ADAPTER_OPERATION_TESTING: printf("Operation: %s ", "Testing"); break;
+
124 case BRAWCAP_ADAPTER_OPERATION_UP: printf("Operation: %s ", "Up"); break;
+
125 }
+
126#endif
+
127#if 1 // Resolve adapter connection state by using it´s name
+
128 brawcap_adapter_connection_state_t connectionState = BRAWCAP_ADAPTER_CONNECTION_UNKNOWN;
+
129 status = brawcap_adapter_connection(name, &connectionState);
+
130 if(!BRAWCAP_SUCCESS(status))
+
131 break;
+
132 switch (connectionState)
+
133 {
+
134 case BRAWCAP_ADAPTER_CONNECTION_UNKNOWN: printf("Connection: %s ", "Unknown"); break;
+
135 case BRAWCAP_ADAPTER_CONNECTION_DOWN: printf("Connection: %s ", "Down"); break;
+
136 case BRAWCAP_ADAPTER_CONNECTION_UP: printf("Connection: %s ", "Up"); break;
+
137 }
+
138#endif
+
139#if 1 // Resolve adapter IPv4 address by using it´s name
+
140 brawcap_adapter_ipv4_t ipv4 = {0};
+
141 status = brawcap_adapter_ipv4(name, &ipv4);
+
142 if(!BRAWCAP_SUCCESS(status))
+
143 break;
+
144 printf("IPv4: %u.%u.%u.%u ", ipv4.bytes[0], ipv4.bytes[1], ipv4.bytes[2], ipv4.bytes[3]);
+
145#endif
+
146#if 1 // Resolve adapter IPv6 address by using it´s name
+
147 brawcap_adapter_ipv6_t ipv6 = {0};
+
148 status = brawcap_adapter_ipv6(name, &ipv6);
+
149 if(!BRAWCAP_SUCCESS(status))
+
150 break;
+
151 printf("IPv6: %x:%x:%x:%x:%x:%x:%x:%x ", ipv6.words[0], ipv6.words[1], ipv6.words[2], ipv6.words[3],
+
152 ipv6.words[4], ipv6.words[5], ipv6.words[6], ipv6.words[7]);
+
153#endif
+
154#if 1 // Resolve adapter max transmission unit (MTU) size by using it´s name
+
155 brawcap_adapter_mtu_t mtu = 0;
+
156 status = brawcap_adapter_mtu(name, &mtu);
+
157 if(!BRAWCAP_SUCCESS(status))
+
158 break;
+
159 printf("MTU: %llu ", mtu);
+
160#endif
+
161#if 1 // Resolve adapter receive speed (uplink speed) by using it´s name
+
162 brawcap_adapter_speed_t rxSpeed = BRAWCAP_ADAPTER_SPEED_UNKNOWN;
+
163 status = brawcap_adapter_speed_rx(name, &rxSpeed);
+
164 if(!BRAWCAP_SUCCESS(status))
+
165 break;
+
166 printf("RX Speed: %d MBit/s ", rxSpeed);
+
167#endif
+
168#if 1 // Resolve adapter transmit speed (uplink speed) by using it´s name
+
169 brawcap_adapter_speed_t txSpeed = BRAWCAP_ADAPTER_SPEED_UNKNOWN;
+
170 status = brawcap_adapter_speed_tx(name, &txSpeed);
+
171 if(!BRAWCAP_SUCCESS(status))
+
172 break;
+
173 printf("TX Speed: %d MBit/s\n\n", txSpeed);
+
174#endif
+
175 // We have allocated memory above...
+
176 // So we should not forget to release it.
+
177 //
+
178 // NOTE: Here we have still a memory leak if
+
179 // loop exits due to a break after allocation.
+
180 // But it is only in case of a failure and we ignore it
+
181 // because of simplicity of the example...
+
182 free(friendlyName);
+
183 free(description);
+
184 }
+
185#endif
+
186 }while(0);
+
187
+
188 // We do not handle anything unexpected...
+
189 // Instead just print the last unexpected status to console and leave.
+
190 if(!BRAWCAP_SUCCESS(status))
+
191 {
+
192 printf("Unexpected status returned: %d\n", status);
+
193 return -1;
+
194 }
+
195 return 0;
+
196}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_ERROR_OVERRUN
@ BRAWCAP_STATUS_ERROR_OVERRUN
A buffer overrun was detected.
Definition: brawcap_types_shared.h:245
+
brawcap_adapter_ipv4_t
IPv4 address.
Definition: brawcap_types_um.h:263
+
brawcap_adapter_ipv6_t
IPv6 address.
Definition: brawcap_types_um.h:273
+
brawcap_adapter_ipv4_t::bytes
UINT8 bytes[4]
Definition: brawcap_types_um.h:264
+
brawcap_adapter_ipv6_t::words
UINT16 words[8]
Definition: brawcap_types_um.h:275
+
brawcap_adapter_mtu
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_adapter_list_at
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_adapter_speed_rx
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_adapter_list_count
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_adapter_ipv4
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_adapter_friendly_name
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_adapter_description
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_adapter_mac_t
UINT8 brawcap_adapter_mac_t[BRAWCAP_ADAPTER_MAC_LENGTH]
Fixed size array describing a MAC address.
Definition: brawcap_types_um.h:249
+
brawcap_adapter_connection_state_t
brawcap_adapter_connection_state_t
List of adapter connection states. Values indicating the current adapter connection state (uplink/cab...
Definition: brawcap_types_um.h:306
+
brawcap_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_connection
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_adapter_ipv6
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_adapter_speed_t
brawcap_adapter_speed_t
List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed.
Definition: brawcap_types_um.h:287
+
brawcap_adapter_list_update
brawcap_status_t brawcap_adapter_list_update()
Updates the list of supported adapters. This function searches the current machine for supported adap...
+
brawcap_adapter_mac
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_adapter_operation_state_t
brawcap_adapter_operation_state_t
List of adapter operation states. Values indicating the current adapter operation state (adapter driv...
Definition: brawcap_types_um.h:317
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
brawcap_adapter_speed_tx
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_adapter_mtu_t
UINT64 brawcap_adapter_mtu_t
Type for handling the adapter maximum transmission unit (MTU).
Definition: brawcap_types_um.h:337
+
brawcap_adapter_operation
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_ADAPTER_CONNECTION_UP
@ BRAWCAP_ADAPTER_CONNECTION_UP
Definition: brawcap_types_um.h:308
+
BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
@ BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
Definition: brawcap_types_um.h:307
+
BRAWCAP_ADAPTER_CONNECTION_DOWN
@ BRAWCAP_ADAPTER_CONNECTION_DOWN
Definition: brawcap_types_um.h:309
+
BRAWCAP_ADAPTER_SPEED_UNKNOWN
@ BRAWCAP_ADAPTER_SPEED_UNKNOWN
Definition: brawcap_types_um.h:288
+
BRAWCAP_ADAPTER_OPERATION_DOWN
@ BRAWCAP_ADAPTER_OPERATION_DOWN
Definition: brawcap_types_um.h:320
+
BRAWCAP_ADAPTER_OPERATION_UNKNOWN
@ BRAWCAP_ADAPTER_OPERATION_UNKNOWN
Definition: brawcap_types_um.h:318
+
BRAWCAP_ADAPTER_OPERATION_TESTING
@ BRAWCAP_ADAPTER_OPERATION_TESTING
Definition: brawcap_types_um.h:321
+
BRAWCAP_ADAPTER_OPERATION_UP
@ BRAWCAP_ADAPTER_OPERATION_UP
Definition: brawcap_types_um.h:319
+
+ + + + + + diff --git a/sdk/c/doc/html/a00921.html b/sdk/c/doc/html/a00921.html new file mode 100644 index 0000000..12d2b7d --- /dev/null +++ b/sdk/c/doc/html/a00921.html @@ -0,0 +1,394 @@ + + + + + + + + +bRAWcap: 02_adapter_change_notifier.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
02_adapter_change_notifier.c
+
+
+

This example shows how to register and handle adapter change notifications. It will print each received notification to command line. Each output will also include the change reason and the new adapter property value.

+
Attention
This example requires a valid bRAWcap license. Reading adapter properties is not part of the demo.
+
1/**
+
2 * @file 02_adapter_change_notifier.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates the usage of the adapter handling module.
+
5 *
+
6 * It shows how to:
+
7 * - Receive adapter change notifications
+
8 * - Process change notifications
+
9 *
+
10 * This example makes use of C only.
+
11 *
+
12 * @attention This example requires a valid bRAWcap license.
+
13 * Receiving adapter change notifications and reading their properties is not part of the demo.
+
14 *
+
15 * @version 1.0
+
16 *
+
17 * @date 2023-03-24
+
18 *
+
19 * @copyright
+
20 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
21 *
+
22 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
23 *
+
24 * Redistribution in source or any other form, with or without modification, is not permitted.
+
25 *
+
26 * You may use this code under the according license terms of b-plus.
+
27 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
28 */
+
29// Include bRAWcap
+
30#include "libbrawcap.h"
+
31
+
32// C STD
+
33#include <stdlib.h> // for malloc & free
+
34#include <stdio.h> // for printf
+
35
+
36// Check command line parameters if a custom execution time is specified
+
37void ParseArgs(int argc, char** argv, int* exec_time)
+
38{
+
39 if(argc > 1)
+
40 {
+
41 if(!memcmp(argv[1], "-t", 2))
+
42 {
+
43 char* pEnd = 0;
+
44 *exec_time = strtol(argv[2], &pEnd,0);
+
45 }
+
46 }
+
47}
+
48
+
49void change_notification_callback(const brawcap_adapter_name_t name, const brawcap_adapter_notify_reason_t reason,
+
50 const UINT32 properties, void* pUser)
+
51{
+
52 // We have entered a user context which points to a notification counter.
+
53 // To use it we should first of all check if it is valid and if so cast it to the correct type.
+
54 if(pUser)
+
55 {
+
56 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
57 int* pNotifyCounter = (int*) pUser;
+
58 ++(*pNotifyCounter);
+
59
+
60#if 1 // We always try to print the friendly name too (for readability...)
+
61 // Therefore we must retrieve it from the adapter name.
+
62 // If an adapter is not available anymore we can not resolve it´s friendly name.
+
63 // In this case it will be "null" instead.
+
64 char* friendlyName = 0;
+
65 UINT32 friendlyNameLength = 0;
+
66 if(brawcap_adapter_friendly_name(name, friendlyName, &friendlyNameLength) == BRAWCAP_STATUS_ERROR_OVERRUN)
+
67 {
+
68 friendlyName = malloc(friendlyNameLength);
+
69 status = brawcap_adapter_friendly_name(name, friendlyName, &friendlyNameLength);
+
70 if(status != BRAWCAP_STATUS_SUCCESS)
+
71 {
+
72 printf("Could not resolve adapter friendly name (unexpected status: %d)\n", status);
+
73 free(friendlyName);
+
74 return;
+
75 }
+
76 }
+
77#endif
+
78 printf("\n%03d. Notification\n", *pNotifyCounter);
+
79#if 1 // Now handle the different notification reasons.
+
80 switch (reason)
+
81 {
+
82#if 1 // The given reason is unknown
+
83 case BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN:
+
84 default:
+
85 printf("Unknown notification reason.");
+
86 break;
+
87#endif
+
88#if 1 // The specified adapter was added
+
89 case BRAWCAP_ADAPTER_NOTIFY_REASON_ADD:
+
90 printf("%s (%s) added\n", friendlyName, name);
+
91 break;
+
92#endif
+
93#if 1 // The specified adapter was removed
+
94 case BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE:
+
95 printf("%s (%s) removed\n", friendlyName, name);
+
96 break;
+
97#endif
+
98#if 1 // At least one property of the specified adapter has changed.
+
99 case BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE:
+
100#if 1 // Connection state has changed
+
101 if(properties & BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE)
+
102 {
+
103 brawcap_adapter_connection_state_t connectionState = BRAWCAP_ADAPTER_CONNECTION_UNKNOWN;
+
104 brawcap_adapter_connection(name, &connectionState);
+
105 printf("%s (%s) new connection state: ", friendlyName, name);
+
106 switch (connectionState)
+
107 {
+
108 case BRAWCAP_ADAPTER_CONNECTION_UNKNOWN: printf("%s\n", "Unknown"); break;
+
109 case BRAWCAP_ADAPTER_CONNECTION_DOWN: printf("%s\n", "Down"); break;
+
110 case BRAWCAP_ADAPTER_CONNECTION_UP: printf("%s\n", "Up"); break;
+
111 }
+
112 }
+
113#endif
+
114#if 1 // Friendly name has changed
+
115 if(properties & BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME)
+
116 printf("%s new friendly name: %s\n", name, friendlyName);
+
117#endif
+
118#if 1 // IPv4 has changed
+
119 if(properties & BRAWCAP_ADAPTER_PROPERTY_IPV4)
+
120 {
+
121 brawcap_adapter_ipv4_t ipv4 = {0};
+
122 brawcap_adapter_ipv4(name, &ipv4);
+
123 printf("%s (%s) new IPv4: %u.%u.%u.%u\n", friendlyName, name,
+
124 ipv4.bytes[0], ipv4.bytes[1], ipv4.bytes[2], ipv4.bytes[3]);
+
125 }
+
126#endif
+
127#if 1 // IPv6 has changed
+
128 if(properties & BRAWCAP_ADAPTER_PROPERTY_IPV6)
+
129 {
+
130 brawcap_adapter_ipv6_t ipv6 = {0};
+
131 brawcap_adapter_ipv6(name, &ipv6);
+
132 printf("%s (%s) new IPv6: %x:%x:%x:%x:%x:%x:%x:%x\n", friendlyName, name,
+
133 ipv6.words[0], ipv6.words[1], ipv6.words[2], ipv6.words[3],
+
134 ipv6.words[4], ipv6.words[5], ipv6.words[6], ipv6.words[7]);
+
135 }
+
136#endif
+
137#if 1 // Max transmission unit has changed
+
138 if(properties & BRAWCAP_ADAPTER_PROPERTY_MTU)
+
139 {
+
140 brawcap_adapter_mtu_t mtu = 0;
+
141 brawcap_adapter_mtu(name, &mtu);
+
142 printf("%s (%s) new max transmission unit: %llu\n", friendlyName, name, mtu);
+
143 }
+
144#endif
+
145#if 1 // Operation state has changed
+
146 if(properties & BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE)
+
147 {
+
148 brawcap_adapter_operation_state_t operationState = BRAWCAP_ADAPTER_OPERATION_UNKNOWN;
+
149 brawcap_adapter_operation(name, &operationState);
+
150 printf("%s (%s) new operation state: ", friendlyName, name);
+
151 switch (operationState)
+
152 {
+
153 case BRAWCAP_ADAPTER_OPERATION_UNKNOWN: printf("%s\n", "Unknown"); break;
+
154 case BRAWCAP_ADAPTER_OPERATION_DOWN: printf("%s\n", "Down"); break;
+
155 case BRAWCAP_ADAPTER_OPERATION_TESTING: printf("%s\n", "Testing"); break;
+
156 case BRAWCAP_ADAPTER_OPERATION_UP: printf("%s\n", "Up"); break;
+
157 }
+
158 }
+
159#endif
+
160#if 1 // Receive speed has changed
+
161 if(properties & BRAWCAP_ADAPTER_PROPERTY_RX_SPEED)
+
162 {
+
163 brawcap_adapter_speed_t speed = BRAWCAP_ADAPTER_SPEED_UNKNOWN;
+
164 brawcap_adapter_speed_rx(name, &speed);
+
165 printf("%s (%s) new receive (uplink) speed: %u MBit/s\n", friendlyName, name, speed);
+
166 }
+
167#endif
+
168#if 1 // Transmit speed has changed
+
169 if(properties & BRAWCAP_ADAPTER_PROPERTY_TX_SPEED)
+
170 {
+
171 brawcap_adapter_speed_t speed = BRAWCAP_ADAPTER_SPEED_UNKNOWN;
+
172 brawcap_adapter_speed_tx(name, &speed);
+
173 printf("%s (%s) new transmit (uplink) speed: %u MBit/s\n", friendlyName, name, speed);
+
174 }
+
175#endif
+
176 break;
+
177#endif
+
178 }
+
179 // Don´t forget to free the allocated memory...
+
180 free(friendlyName);
+
181 }
+
182#endif
+
183}
+
184
+
185// Use command line parameter -t to specify a custom execution time.
+
186// If it is not given the execution time is per default 5 minutes.
+
187int main(int argc, char** argv)
+
188{
+
189 // Set console title
+
190 SetConsoleTitleA("bRAWcap Example - Adapter Change Notifier");
+
191
+
192 int exec_time = 300; // 5 minutes
+
193 int runtime_sec = 0;
+
194 ParseArgs(argc, argv, &exec_time);
+
195
+
196 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
197
+
198 // This variable will be entered during registration, to make it available from inside the callback.
+
199 // ATTENTION: You are responsible for checking the pointer inside your callback, before accessing it.
+
200 int notifyCounter = 0;
+
201
+
202 // Register our process for bRAWcap adapter change notifications
+
203 brawcap_adapter_notify_callback_t callback = change_notification_callback;
+
204 status = brawcap_adapter_notify_register(callback, &notifyCounter);
+
205 if(!BRAWCAP_SUCCESS(status))
+
206 {
+
207 printf("Registration for adapter change notification failed (Status: %d). Will stop now...", status);
+
208 return -1;
+
209 }
+
210
+
211 // Our main thread does nothing than waiting until execution time is elapsed.
+
212 // Everything else is done by the thread which is calling our registered callback.
+
213 do
+
214 {
+
215 Sleep(1000);
+
216 } while (++runtime_sec < exec_time);
+
217
+
218 // Unregister bRAWcap adapter change notifications before exiting.
+
219 // NOTE: bRAWcap would automatically unregister on unloading.
+
220 // Therefore unregistering on exiting isn´t required...
+
221 status = brawcap_adapter_notify_unregister();
+
222 if(!BRAWCAP_SUCCESS(status))
+
223 {
+
224 printf("Unregistration for adapter change noTification failed (Status: %d). Will stop now...", status);
+
225 return -1;
+
226 }
+
227
+
228 return 0;
+
229}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_ERROR_OVERRUN
@ BRAWCAP_STATUS_ERROR_OVERRUN
A buffer overrun was detected.
Definition: brawcap_types_shared.h:245
+
brawcap_adapter_ipv4_t
IPv4 address.
Definition: brawcap_types_um.h:263
+
brawcap_adapter_ipv6_t
IPv6 address.
Definition: brawcap_types_um.h:273
+
brawcap_adapter_ipv4_t::bytes
UINT8 bytes[4]
Definition: brawcap_types_um.h:264
+
brawcap_adapter_ipv6_t::words
UINT16 words[8]
Definition: brawcap_types_um.h:275
+
brawcap_adapter_notify_unregister
brawcap_status_t brawcap_adapter_notify_unregister()
Unregisters the calling process from receiving adapter change notifications.
+
brawcap_adapter_mtu
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_adapter_speed_rx
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_adapter_ipv4
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_adapter_friendly_name
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_adapter_connection_state_t
brawcap_adapter_connection_state_t
List of adapter connection states. Values indicating the current adapter connection state (uplink/cab...
Definition: brawcap_types_um.h:306
+
brawcap_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_connection
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_adapter_ipv6
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_adapter_speed_t
brawcap_adapter_speed_t
List of bRAWcap adapter speeds. Values indicating the current adapter uplink speed.
Definition: brawcap_types_um.h:287
+
brawcap_adapter_notify_callback_t
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 su...
Definition: brawcap_types_um.h:400
+
brawcap_adapter_operation_state_t
brawcap_adapter_operation_state_t
List of adapter operation states. Values indicating the current adapter operation state (adapter driv...
Definition: brawcap_types_um.h:317
+
brawcap_adapter_notify_register
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_adapter_speed_tx
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_adapter_notify_reason_t
brawcap_adapter_notify_reason_t
List of reasons for adapter change notifications. This values indicate why a adapter change notificat...
Definition: brawcap_types_um.h:344
+
brawcap_adapter_mtu_t
UINT64 brawcap_adapter_mtu_t
Type for handling the adapter maximum transmission unit (MTU).
Definition: brawcap_types_um.h:337
+
brawcap_adapter_operation
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_ADAPTER_PROPERTY_CONNECTION_STATE
@ BRAWCAP_ADAPTER_PROPERTY_CONNECTION_STATE
Definition: brawcap_types_um.h:380
+
BRAWCAP_ADAPTER_PROPERTY_IPV6
@ BRAWCAP_ADAPTER_PROPERTY_IPV6
Definition: brawcap_types_um.h:382
+
BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE
@ BRAWCAP_ADAPTER_PROPERTY_OPERATION_STATE
Definition: brawcap_types_um.h:379
+
BRAWCAP_ADAPTER_PROPERTY_RX_SPEED
@ BRAWCAP_ADAPTER_PROPERTY_RX_SPEED
Definition: brawcap_types_um.h:376
+
BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME
@ BRAWCAP_ADAPTER_PROPERTY_FRIENDLY_NAME
Definition: brawcap_types_um.h:375
+
BRAWCAP_ADAPTER_PROPERTY_IPV4
@ BRAWCAP_ADAPTER_PROPERTY_IPV4
Definition: brawcap_types_um.h:381
+
BRAWCAP_ADAPTER_PROPERTY_TX_SPEED
@ BRAWCAP_ADAPTER_PROPERTY_TX_SPEED
Definition: brawcap_types_um.h:377
+
BRAWCAP_ADAPTER_PROPERTY_MTU
@ BRAWCAP_ADAPTER_PROPERTY_MTU
Definition: brawcap_types_um.h:378
+
BRAWCAP_ADAPTER_CONNECTION_UP
@ BRAWCAP_ADAPTER_CONNECTION_UP
Definition: brawcap_types_um.h:308
+
BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
@ BRAWCAP_ADAPTER_CONNECTION_UNKNOWN
Definition: brawcap_types_um.h:307
+
BRAWCAP_ADAPTER_CONNECTION_DOWN
@ BRAWCAP_ADAPTER_CONNECTION_DOWN
Definition: brawcap_types_um.h:309
+
BRAWCAP_ADAPTER_SPEED_UNKNOWN
@ BRAWCAP_ADAPTER_SPEED_UNKNOWN
Definition: brawcap_types_um.h:288
+
BRAWCAP_ADAPTER_OPERATION_DOWN
@ BRAWCAP_ADAPTER_OPERATION_DOWN
Definition: brawcap_types_um.h:320
+
BRAWCAP_ADAPTER_OPERATION_UNKNOWN
@ BRAWCAP_ADAPTER_OPERATION_UNKNOWN
Definition: brawcap_types_um.h:318
+
BRAWCAP_ADAPTER_OPERATION_TESTING
@ BRAWCAP_ADAPTER_OPERATION_TESTING
Definition: brawcap_types_um.h:321
+
BRAWCAP_ADAPTER_OPERATION_UP
@ BRAWCAP_ADAPTER_OPERATION_UP
Definition: brawcap_types_um.h:319
+
BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE
@ BRAWCAP_ADAPTER_NOTIFY_REASON_PROPERTY_CHANGE
A adapter property has changed. This can have several reasons, for a list of all properties see brawc...
Definition: brawcap_types_um.h:363
+
BRAWCAP_ADAPTER_NOTIFY_REASON_ADD
@ BRAWCAP_ADAPTER_NOTIFY_REASON_ADD
A new bRAWcap adapter was detected. E.g. due to enabling bRAWcap driver on an adapter where it was di...
Definition: brawcap_types_um.h:353
+
BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE
@ BRAWCAP_ADAPTER_NOTIFY_REASON_REMOVE
A bRAWcap adapter was removed. E.g. due to disabling bRAWcap driver on an adapter where it was enable...
Definition: brawcap_types_um.h:358
+
BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN
@ BRAWCAP_ADAPTER_NOTIFY_REASON_UNKNOWN
The notification reason is unknown.
Definition: brawcap_types_um.h:348
+
+ + + + + + diff --git a/sdk/c/doc/html/a00922.html b/sdk/c/doc/html/a00922.html new file mode 100644 index 0000000..a67d915 --- /dev/null +++ b/sdk/c/doc/html/a00922.html @@ -0,0 +1,328 @@ + + + + + + + + +bRAWcap: 05_receive_simple_packet_receiver.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
05_receive_simple_packet_receiver.c
+
+
+

This example shows how to use the bRAWcap single packet receive feature. It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet to store received data to. For each received packet it will print the packet information to console.

+
1/**
+
2 * @file 05_receive_simple_packet_receiver.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets.
+
5 *
+
6 * It shows how to:
+
7 * - Open a handle to the first available adapter
+
8 * - Create a bRAWcap packet object
+
9 * - Receive single packets from the adapter
+
10 * - Access received packet data.
+
11 *
+
12 * This example makes use of C only.
+
13 *
+
14 * @version 1.1
+
15 *
+
16 * @date 2023-03-30
+
17 *
+
18 * @copyright
+
19 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
20 *
+
21 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
22 *
+
23 * Redistribution in source or any other form, with or without modification, is not permitted.
+
24 *
+
25 * You may use this code under the according license terms of b-plus.
+
26 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
27 */
+
28// Include bRAWcap
+
29#include "libbrawcap.h"
+
30
+
31// C STD
+
32#include <stdio.h> // for printf
+
33
+
34int main(int argc, char** argv)
+
35{
+
36 // Set console title
+
37 SetConsoleTitleA("bRAWcap Example - Simple Packet Receiver");
+
38
+
39 // Some generic helper locals...
+
40 int retVal = 0;
+
41 unsigned char demoModeLogged = 0;
+
42 unsigned long long packetCounter = 0;
+
43
+
44 // Here we will store the status of any bRAWcap function
+
45 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
46
+
47 // Here we store the number of available bRAWcap adapters
+
48 brawcap_adapter_count_t numberAdapters = 0;
+
49 // This will contain our bRAWcap handle to the adapter we want to receive from
+
50 brawcap_handle_t* pHandle = 0;
+
51 // Our local packet for storing received data
+
52 brawcap_packet_t* pPacket = 0;
+
53
+
54 do
+
55 {
+
56 // First check if we have any bRAWcap adapters available.
+
57 // --> This function can only fail if we did something wrong.
+
58 // But we are sure that we did everything right...
+
59 // therefore we do not check it�s status.
+
60 brawcap_adapter_list_count(&numberAdapters);
+
61
+
62 // No adapters... nothing do receive from... lets exit ...
+
63 if (!numberAdapters)
+
64 {
+
65 printf("[WARNING] No bRAWcap adapter available... Will stop now.");
+
66 break;
+
67 }
+
68
+
69 // Get the name of the first adapter.
+
70 // To not overload the example with complex stuff,
+
71 // we always go for the first available adapter.
+
72 brawcap_adapter_name_t name = { '\0' };
+
73 if (!BRAWCAP_SUCCESS(brawcap_adapter_list_at(0, name)))
+
74 {
+
75 printf("[ERROR] Unexpected status while retrieving adapter name: %d", brawcap_last_status());
+
76 retVal = -1;
+
77 break;
+
78 }
+
79
+
80 // Open a handle to the adapter by using the retrieved name.
+
81 if (!BRAWCAP_SUCCESS(brawcap_open(name, &pHandle)))
+
82 {
+
83 printf("[ERROR] Unexpected status while opening handle: %d", brawcap_last_status());
+
84 retVal = -1;
+
85 break;
+
86 }
+
87
+
88 // Create a packet object
+
89 // For simplicity and to make sure that we get all packets,
+
90 // we set the payload size to the max supported value.
+
91 if(!BRAWCAP_SUCCESS(brawcap_packet_create(&pPacket, BRAWCAP_PACKET_SIZE_MAX)))
+
92 {
+
93 printf("[ERROR] Unexpected status while creating packet: %d", brawcap_last_status());
+
94 retVal = -1;
+
95 break;
+
96 }
+
97
+
98 // Some local variables to buffer the packet data, later on.
+
99 brawcap_packet_size_t captureLength = 0;
+
100 brawcap_packet_size_t lengthOnWire = 0;
+
101 brawcap_timestamp_t* pTimestamp = 0;
+
102 UINT64 timestamp_sec = 0;
+
103 UINT32 timestamp_ns = 0;
+
104 const char* pPayload = 0;
+
105
+
106 // Our receive loop, we stay in here until we should stop receiving.
+
107 while(1)
+
108 {
+
109 // Now lets see if we have received a packet...
+
110 status = brawcap_rx_packet(pHandle, pPacket);
+
111
+
112 // Seems like we had success and got some packet data to look at. :-)
+
113 if(BRAWCAP_SUCCESS(status))
+
114 {
+
115 // Check if we made it out of the demo limitation... :-D
+
116 // ... notify the user and go ahead with receiving.
+
117 if (demoModeLogged)
+
118 {
+
119 printf("[NOTICE] DEMO MODE: Limitation period elapsed, receiving is available again.\n");
+
120 demoModeLogged = 0;
+
121 }
+
122
+
123 // --> The bRAWcap functions below can only fail if we did something wrong.
+
124 // But we are sure that we did everything right...
+
125 // therefore we do not check their status.
+
126 brawcap_packet_length_on_wire_get(pPacket, &lengthOnWire);
+
127 brawcap_packet_payload_get(pPacket, &pPayload, &captureLength);
+
128 brawcap_packet_timestamp_get(pPacket, &pTimestamp);
+
129 brawcap_timestamp_value_ns_get(pTimestamp, &timestamp_sec, &timestamp_ns);
+
130
+
131 // Show the user what we received
+
132 printf("%llu. Packet:\n", ++packetCounter);
+
133 printf(" - Capture Length: %04u Bytes\n", captureLength);
+
134 printf(" - Length On Wire: %04u Bytes\n", lengthOnWire);
+
135 printf(" - Timestamp: %llu %09u ns\n", timestamp_sec, timestamp_ns);
+
136 printf(" - Payload: ");
+
137 // Do some nice formatting stuff, to improve readability...
+
138 UINT32 byteCounter = 1;
+
139 for (const char* pByte = pPayload; byteCounter <= captureLength; ++byteCounter)
+
140 {
+
141 printf("%02X ", (unsigned char)*pByte++);
+
142 if (!(byteCounter % 16)) printf("\n ");
+
143 else if(!(byteCounter % 8)) printf(" ");
+
144 }
+
145 printf("\n\n");
+
146 }
+
147 // Hm... we got a very silent connection...
+
148 // ... lets try again...
+
149 else if (status == BRAWCAP_STATUS_INFO_NO_DATA)
+
150 continue;
+
151 // Sad but we do not have a bRAWcap license for this feature... yet. :-(
+
152 // Notify our user about this sad information and
+
153 // wait some time to check if we are allowed to receive again...
+
154 else if (status == BRAWCAP_STATUS_WARNING_DEMO_MODE)
+
155 {
+
156 if (!demoModeLogged)
+
157 {
+
158 demoModeLogged = 1;
+
159 printf("[WARNING] DEMO MODE: Receiving not available.\n");
+
160 }
+
161 Sleep(1000);
+
162 }
+
163 // Ok... Something strange happened here... :-O
+
164 // Better stop now if we do not know how to handle it.
+
165 else
+
166 {
+
167 printf("[ERROR] Unexpected status while receiving packet: %d", brawcap_last_status());
+
168 retVal = -1;
+
169 break;
+
170 }
+
171 }
+
172 }while(0);
+
173
+
174 // We do not want to produce any memory leaks...
+
175 // ... so always cleanup what we have created
+
176 // --> The functions here can only fail if we did something wrong.
+
177 // But we are sure that we did everything right...
+
178 // therefore we do not check their status.
+
179 if (pPacket)
+
180 brawcap_packet_free(pPacket);
+
181 if (pHandle)
+
182 brawcap_close(pHandle);
+
183
+
184 return retVal;
+
185}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_INFO_NO_DATA
@ BRAWCAP_STATUS_INFO_NO_DATA
Indicates that a function returns without any data.
Definition: brawcap_types_shared.h:333
+
BRAWCAP_STATUS_WARNING_DEMO_MODE
@ BRAWCAP_STATUS_WARNING_DEMO_MODE
The operation was not executed due to demo mode limitations.
Definition: brawcap_types_shared.h:256
+
brawcap_timestamp_t
struct _brawcap_timestamp brawcap_timestamp_t
bRAWcap timestamp object.
Definition: brawcap_types_shared.h:612
+
brawcap_timestamp_value_ns_get
brawcap_status_t brawcap_timestamp_value_ns_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pNanoseconds)
Reads out the timestamp value in seconds and nanoseconds.
+
brawcap_packet_size_t
UINT16 brawcap_packet_size_t
Type for handling the number of payload bytes per packet.
Definition: brawcap_types_shared.h:670
+
brawcap_packet_create
brawcap_status_t brawcap_packet_create(brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
Creates a new packet.
+
brawcap_packet_t
struct _brawcap_packet brawcap_packet_t
bRAWcap packet object.
Definition: brawcap_types_shared.h:679
+
BRAWCAP_PACKET_SIZE_MAX
#define BRAWCAP_PACKET_SIZE_MAX
The maximum supported (byte) size for a single packet payload.
Definition: brawcap_types_shared.h:649
+
brawcap_packet_payload_get
brawcap_status_t brawcap_packet_payload_get(brawcap_packet_t *const pPacket, const char **const pPayload, brawcap_packet_size_t *const pLength)
Reads out the payload of the specified packet.
+
brawcap_packet_length_on_wire_get
brawcap_status_t brawcap_packet_length_on_wire_get(brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLengthOnWire)
Reads out the length on wire of the specified packet. This value is especially useful for received pa...
+
brawcap_packet_timestamp_get
brawcap_status_t brawcap_packet_timestamp_get(brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
Reads out the timestamp object for the specified packet.
+
brawcap_packet_free
brawcap_status_t brawcap_packet_free(brawcap_packet_t *pPacket)
Frees the specified packet. When this function is called the specified packet becomes invalid and it´...
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
brawcap_rx_packet
brawcap_status_t brawcap_rx_packet(brawcap_handle_t *const pHandle, brawcap_packet_t *const pPacket)
Receives a single packet from the specified handle.
+
+ + + + + + diff --git a/sdk/c/doc/html/a00923.html b/sdk/c/doc/html/a00923.html new file mode 100644 index 0000000..1204ebb --- /dev/null +++ b/sdk/c/doc/html/a00923.html @@ -0,0 +1,361 @@ + + + + + + + + +bRAWcap: 07_receive_buffered_receiver.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
07_receive_buffered_receiver.c
+
+
+

This example shows how to use the bRAWcap single packet receive feature. It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet to store received data to. For each received packet it will print the packet information to console.

+
1/**
+
2 * @file 07_receive_buffered_receiver.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers.
+
5 *
+
6 * It shows how to:
+
7 * - Open a handle to the first available adapter
+
8 * - Create a bRAWcap packet buffer objects
+
9 * - Start receiving on a handle
+
10 * - Using the receive callback
+
11 * - Iterating through a packet buffer
+
12 * - Accessing a buffered packet
+
13 *
+
14 * This example makes use of C only.
+
15 *
+
16 * @version 1.1
+
17 *
+
18 * @date 2023-03-30
+
19 *
+
20 * @copyright
+
21 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
22 *
+
23 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
24 *
+
25 * Redistribution in source or any other form, with or without modification, is not permitted.
+
26 *
+
27 * You may use this code under the according license terms of b-plus.
+
28 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
29 */
+
30// Include bRAWcap
+
31#include "libbrawcap.h"
+
32
+
33// C STD
+
34#include <stdio.h> // for printf
+
35#include <stdlib.h> // for strtol
+
36
+
37typedef struct receive_counters
+
38{
+
39 unsigned long long packets;
+
40 unsigned long long bytes;
+
41}receive_counters_t;
+
42
+
43typedef struct example_context
+
44{
+
45 unsigned char demoLogged;
+
46 receive_counters_t counters;
+
47}example_context_t;
+
48
+
49
+
50// Check command line parameters if a custom execution time is specified
+
51void ParseArgs(int argc, char** argv, int* exec_time)
+
52{
+
53 if(argc > 1)
+
54 {
+
55 if(!memcmp(argv[1], "-t", 2))
+
56 {
+
57 char* pEnd = 0;
+
58 *exec_time = strtol(argv[2], &pEnd,0);
+
59 }
+
60 }
+
61}
+
62
+
63void receiveCallback(brawcap_handle_t* const pHandle, const brawcap_status_t status, brawcap_buffer_t* const pBuffer,
+
64 void* pUser)
+
65{
+
66 example_context_t* pContext = (example_context_t*) pUser;
+
67 if(status == BRAWCAP_STATUS_WARNING_DEMO_MODE)
+
68 {
+
69 if(!pContext->demoLogged)
+
70 {
+
71 printf("[WARNING] DEMO MODE: Receiving not available.\n");
+
72 pContext->demoLogged = 1;
+
73 }
+
74 }
+
75 else if(status == BRAWCAP_STATUS_SUCCESS)
+
76 {
+
77 if(pContext->demoLogged)
+
78 {
+
79 printf("[NOTICE] DEMO MODE: Limitation period elapsed, receiving is available again.\n");
+
80 pContext->demoLogged = 0;
+
81 }
+
82 brawcap_buffer_iterator_t* pIterator = 0;
+
83 brawcap_buffer_iterator_create(&pIterator, pBuffer, 0);
+
84
+
85 brawcap_packet_t* pPacket = 0;
+
86 brawcap_packet_size_t packetSize = 0;
+
87
+
88 do
+
89 {
+
90 pPacket = brawcap_buffer_iterator_eval(pIterator);
+
91 if(!pPacket)
+
92 break;
+
93
+
94 brawcap_packet_payload_size_get(pPacket, &packetSize);
+
95 pContext->counters.bytes += packetSize;
+
96 ++pContext->counters.packets;
+
97
+
98 brawcap_buffer_iterator_next(pIterator);
+
99 } while (1);
+
100
+
101 brawcap_buffer_iterator_free(pIterator);
+
102
+
103 printf("[NOTICE] Received new packets [Total Packets: %llu / Total Bytes: %llu].\n",
+
104 pContext->counters.packets, pContext->counters.bytes);
+
105 }
+
106}
+
107
+
108int main(int argc, char** argv)
+
109{
+
110 // Set console title
+
111 SetConsoleTitleA("bRAWcap Example - Buffered Receiver");
+
112
+
113 int exec_time = 300; // 5 minutes
+
114 int runtime_sec = 0;
+
115 ParseArgs(argc, argv, &exec_time);
+
116
+
117 // Some generic helper locals...
+
118 int retVal = 0;
+
119 example_context_t context = {0};
+
120
+
121 // Here we will store the status of any bRAWcap function
+
122 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
123
+
124 // Here we store the number of available bRAWcap adapters
+
125 brawcap_adapter_count_t numberAdapters = 0;
+
126 // This will contain our bRAWcap handle to the adapter we want to receive from
+
127 brawcap_handle_t* pHandle = 0;
+
128 // Our local packet buffers for storing received data
+
129 brawcap_buffer_t* pPacketBuffer1 = 0;
+
130 brawcap_buffer_t* pPacketBuffer2 = 0;
+
131
+
132 do
+
133 {
+
134 // First check if we have any bRAWcap adapters available.
+
135 // --> This function can only fail if we did something wrong.
+
136 // But we are sure that we did everything right...
+
137 // therefore we do not check it�s status.
+
138 brawcap_adapter_list_count(&numberAdapters);
+
139
+
140 // No adapters... nothing do receive from... lets exit ...
+
141 if (!numberAdapters)
+
142 {
+
143 printf("[WARNING] No bRAWcap adapter available... Will stop now.");
+
144 break;
+
145 }
+
146
+
147 // Get the name of the first adapter.
+
148 // To not overload the example with complex stuff,
+
149 // we always go for the first available adapter.
+
150 brawcap_adapter_name_t name = { '\0' };
+
151 if (!BRAWCAP_SUCCESS(brawcap_adapter_list_at(0, name)))
+
152 {
+
153 printf("[ERROR] Unexpected status while retrieving adapter name: %d", brawcap_last_status());
+
154 retVal = -1;
+
155 break;
+
156 }
+
157
+
158 // Open a handle to the adapter by using the retrieved name.
+
159 if (!BRAWCAP_SUCCESS(brawcap_open(name, &pHandle)))
+
160 {
+
161 printf("[ERROR] Unexpected status while opening handle: %d", brawcap_last_status());
+
162 retVal = -1;
+
163 break;
+
164 }
+
165
+
166 // Create the packet buffers
+
167 // For simplicity and to make sure that we get all packets,
+
168 // we set the packet payload size to the max supported value.
+
169 if(!BRAWCAP_SUCCESS(brawcap_buffer_create(&pPacketBuffer1, BRAWCAP_PACKET_SIZE_MAX, 512)))
+
170 {
+
171 printf("[ERROR] Unexpected status while creating packet buffer: %d", brawcap_last_status());
+
172 retVal = -1;
+
173 break;
+
174 }
+
175 if(!BRAWCAP_SUCCESS(brawcap_buffer_create(&pPacketBuffer2, BRAWCAP_PACKET_SIZE_MAX, 512)))
+
176 {
+
177 printf("[ERROR] Unexpected status while creating packet buffer: %d", brawcap_last_status());
+
178 retVal = -1;
+
179 break;
+
180 }
+
181
+
182 // Attach the created packet buffers to the handle for reception
+
183 brawcap_rx_buffer_attach(pHandle, pPacketBuffer1);
+
184 brawcap_rx_buffer_attach(pHandle, pPacketBuffer2);
+
185
+
186 // Now start the the bRAWcap reception on the handle
+
187 brawcap_rx_start(pHandle, receiveCallback, &context, 0);
+
188
+
189 // After starting the reception our main thread has finished it´s work.
+
190 // Everything else will be done from inside the receive callback until we should stop receiving.
+
191 do
+
192 {
+
193 Sleep(1000);
+
194 } while (++runtime_sec < exec_time);
+
195
+
196 brawcap_rx_stop(pHandle);
+
197 brawcap_rx_buffer_detach(pHandle, pPacketBuffer2);
+
198 brawcap_rx_buffer_detach(pHandle, pPacketBuffer1);
+
199 }while(0);
+
200
+
201 // We do not want to produce any memory leaks...
+
202 // ... so always cleanup what we have created
+
203 // --> The functions here can only fail if we did something wrong.
+
204 // But we are sure that we did everything right...
+
205 // therefore we do not check their status.
+
206 if (pPacketBuffer1)
+
207 brawcap_buffer_free(pPacketBuffer1);
+
208 if(pPacketBuffer2)
+
209 brawcap_buffer_free(pPacketBuffer2);
+
210 if (pHandle)
+
211 brawcap_close(pHandle);
+
212
+
213 return retVal;
+
214}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_WARNING_DEMO_MODE
@ BRAWCAP_STATUS_WARNING_DEMO_MODE
The operation was not executed due to demo mode limitations.
Definition: brawcap_types_shared.h:256
+
brawcap_packet_size_t
UINT16 brawcap_packet_size_t
Type for handling the number of payload bytes per packet.
Definition: brawcap_types_shared.h:670
+
brawcap_packet_payload_size_get
brawcap_status_t brawcap_packet_payload_size_get(brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLength)
Reads out the captured payload byte size of the specified packet. This indicates the total byte size ...
+
brawcap_packet_t
struct _brawcap_packet brawcap_packet_t
bRAWcap packet object.
Definition: brawcap_types_shared.h:679
+
BRAWCAP_PACKET_SIZE_MAX
#define BRAWCAP_PACKET_SIZE_MAX
The maximum supported (byte) size for a single packet payload.
Definition: brawcap_types_shared.h:649
+
brawcap_buffer_t
struct _brawcap_buffer brawcap_buffer_t
bRAWcap packet buffer object.
Definition: brawcap_types_shared.h:742
+
brawcap_buffer_free
brawcap_status_t brawcap_buffer_free(brawcap_buffer_t *pBuffer)
Frees the specified packet buffer. When this function is called the specified packet buffer becomes i...
+
brawcap_buffer_create
brawcap_status_t brawcap_buffer_create(brawcap_buffer_t **const pBuffer, const brawcap_packet_size_t maxPacketPayloadSize, const brawcap_buffer_packet_count_t numPackets)
Creates a new packet buffer.
+
brawcap_buffer_iterator_free
brawcap_status_t brawcap_buffer_iterator_free(brawcap_buffer_iterator_t *const pIterator)
Frees the specified iterator. When this function is called the specified iterator becomes invalid and...
+
brawcap_buffer_iterator_t
struct _brawcap_buffer_iterator brawcap_buffer_iterator_t
bRAWcap packet buffer iterator object.
Definition: brawcap_types_shared.h:770
+
brawcap_buffer_iterator_eval
brawcap_packet_t * brawcap_buffer_iterator_eval(brawcap_buffer_iterator_t *const pIterator)
Returns the buffered packet for the specified iterator.
+
brawcap_buffer_iterator_create
brawcap_status_t brawcap_buffer_iterator_create(brawcap_buffer_iterator_t **const pIterator, brawcap_buffer_t *const pBuffer, brawcap_buffer_packet_count_t startPosition)
Creates a new iterator for the specified buffer.
+
brawcap_buffer_iterator_next
brawcap_status_t brawcap_buffer_iterator_next(brawcap_buffer_iterator_t *const pIterator)
Increments the iterator to the next buffered packet.
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
brawcap_rx_buffer_detach
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_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)
Starts the internal receive loop.
+
brawcap_rx_stop
brawcap_status_t brawcap_rx_stop(brawcap_handle_t *const pHandle)
Stops the internal receive loop.
+
brawcap_rx_buffer_attach
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.
+
+ + + + + + diff --git a/sdk/c/doc/html/a00924.html b/sdk/c/doc/html/a00924.html new file mode 100644 index 0000000..e8ac1ca --- /dev/null +++ b/sdk/c/doc/html/a00924.html @@ -0,0 +1,458 @@ + + + + + + + + +bRAWcap: 08_receive_timestamp_inspector.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
08_receive_timestamp_inspector.c
+
+
+

This example shows how to configure the different timestamp modes and read timestamp information from single received packets. It opens a handle to the first available bRAWcap adapter, creates a bRAWcap packet to store received data to and applies the configured timestamp mode. For each received packet it will print it´s applied timestamp info.

+
1/**
+
2 * @file 08_receive_timestamp_inspector.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes.
+
5 *
+
6 * It shows how to:
+
7 * - Open a handle to the first available adapter
+
8 * - Configure the receive timestamp mode
+
9 * - Create a bRAWcap packet object
+
10 * - Receive single packets from the adapter
+
11 * - Access received packet timestamp.
+
12 *
+
13 * This example makes use of C only.
+
14 *
+
15 * @version 1.1
+
16 *
+
17 * @date 2023-03-30
+
18 *
+
19 * @copyright
+
20 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
21 *
+
22 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
23 *
+
24 * Redistribution in source or any other form, with or without modification, is not permitted.
+
25 *
+
26 * You may use this code under the according license terms of b-plus.
+
27 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
28 */
+
29// Include bRAWcap
+
30#include "libbrawcap.h"
+
31
+
32// C STD
+
33#include <stdio.h> // for printf
+
34#include <time.h> // for converting to readable time (gmtime)
+
35
+
36/* Check command line parameters if a custom timestamp mode or accuracy is specified
+
37 * The timestamp mode can be configured with the "-m" parameter.
+
38 * Possible values are:
+
39 * - No: Create no timestamp
+
40 * - DriverSysLow: Timestamp by driver from system time (low precision)
+
41 * - DriverSysHigh: Timestamp by driver from system time (high precision)
+
42 * - DriverSw: Timestamp by driver from software (QPC)
+
43 * - AdapterSys: Timestamp by adapter driver from system time
+
44 * - AdapterSw: Timestamp by adapter from software (QPC)
+
45 * - AdapterHw: Timestamp by adapter from hardware clock
+
46 *
+
47 * The timestamp accuracy can be configured with the "-r" parameter.
+
48 * Possible values are:
+
49 * - ns: Nanoseconds
+
50 * - us: Microseconds
+
51 * - ms: Miliseconds
+
52 */
+
53void ParseArgs(int argc, char** argv, brawcap_timestamp_mode_t* pMode, int* pAccuracy)
+
54{
+
55 for(int index = 0; index < argc; ++index)
+
56 {
+
57 if(!memcmp(argv[index], "-m", 2))
+
58 {
+
59 if(!strcmp(argv[index + 1], "No"))
+
60 *pMode = BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP;
+
61 else if(!strcmp(argv[index + 1], "DriverSysLow"))
+
62 *pMode = BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC;
+
63 else if(!strcmp(argv[index + 1], "DriverSysHigh"))
+
64 *pMode = BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC;
+
65 else if(!strcmp(argv[index + 1], "DriverSw"))
+
66 *pMode = BRAWCAP_TIMESTAMP_MODE_SOFTWARE;
+
67 else if(!strcmp(argv[index + 1], "AdapterSys"))
+
68 *pMode = BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM;
+
69 else if(!strcmp(argv[index + 1], "AdapterSw"))
+
70 *pMode = BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE;
+
71 else if(!strcmp(argv[index + 1], "AdapterHw"))
+
72 *pMode = BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE;
+
73 else
+
74 printf("[WARNING] Unknown timestamp mode - will use default mode.\n");
+
75 }
+
76 else if(!memcmp(argv[index], "-r", 2))
+
77 {
+
78 if(!strcmp(argv[index + 1], "ns"))
+
79 *pAccuracy = 1;
+
80 else if(!strcmp(argv[index + 1], "us"))
+
81 *pAccuracy = 2;
+
82 else if(!strcmp(argv[index + 1], "ms"))
+
83 *pAccuracy = 3;
+
84 else
+
85 printf("[WARNING] Unknown accuracy - will use default accuracy.\n");
+
86 }
+
87 }
+
88}
+
89
+
90int main(int argc, char** argv)
+
91{
+
92 // Set console title
+
93 SetConsoleTitleA("bRAWcap Example - Receive Timestamp Inspector");
+
94
+
95 // Some generic helper locals...
+
96 int retVal = 0;
+
97 unsigned char demoModeLogged = 0;
+
98 unsigned long long packetCounter = 0;
+
99 int accuracy = 1;
+
100
+
101 // Set the default timestamp mode to system low precision
+
102 brawcap_timestamp_mode_t timestampMode = BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC;
+
103
+
104 // Here we will store the status of any bRAWcap function
+
105 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
106
+
107 // Here we store the number of available bRAWcap adapters
+
108 brawcap_adapter_count_t numberAdapters = 0;
+
109 // This will contain our bRAWcap handle to the adapter we want to receive from
+
110 brawcap_handle_t* pHandle = 0;
+
111 // Our local packet for storing received data
+
112 brawcap_packet_t* pPacket = 0;
+
113
+
114 // Parse command line argument for selected timestamp mode
+
115 ParseArgs(argc, argv, &timestampMode, &accuracy);
+
116
+
117 do
+
118 {
+
119 // First check if we have any bRAWcap adapters available.
+
120 // --> This function can only fail if we did something wrong.
+
121 // But we are sure that we did everything right...
+
122 // therefore we do not check it�s status.
+
123 brawcap_adapter_list_count(&numberAdapters);
+
124
+
125 // No adapters... nothing do receive from... lets exit ...
+
126 if (!numberAdapters)
+
127 {
+
128 printf("[WARNING] No bRAWcap adapter available... Will stop now.\n");
+
129 break;
+
130 }
+
131
+
132 // Get the name of the first adapter.
+
133 // To not overload the example with complex stuff,
+
134 // we always go for the first available adapter.
+
135 brawcap_adapter_name_t name = { '\0' };
+
136 if (!BRAWCAP_SUCCESS(brawcap_adapter_list_at(0, name)))
+
137 {
+
138 printf("[ERROR] Unexpected status while retrieving adapter name: %d\n", brawcap_last_status());
+
139 retVal = -1;
+
140 break;
+
141 }
+
142
+
143 // Open a handle to the adapter by using the retrieved name.
+
144 if (!BRAWCAP_SUCCESS(brawcap_open(name, &pHandle)))
+
145 {
+
146 printf("[ERROR] Unexpected status while opening handle: %d\n", brawcap_last_status());
+
147 retVal = -1;
+
148 break;
+
149 }
+
150
+
151 // Lets see what timestamp modes we have on the specified adapter
+
152 brawcap_timestamp_capabilities_t timestampCapabilities;
+
153 if(!BRAWCAP_SUCCESS(brawcap_rx_timestamp_capabilities(pHandle, &timestampCapabilities)))
+
154 {
+
155 printf("[ERROR] Unexpected status while retrieving timestamp capabilities: %d\n", brawcap_last_status());
+
156 retVal = -1;
+
157 break;
+
158 }
+
159
+
160 // Print available adapter timestamp capabilities to console before we start reading packets
+
161 // We only check for adapter modes explicitly because all other modes are always available.
+
162 printf("ADAPTER TIMESTAMP CAPABILITIES: \n");
+
163 printf(" - System: %s\n", timestampCapabilities & BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM ? "yes" : "no");
+
164 printf(" - Software: %s\n", timestampCapabilities & BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE ? "yes" : "no");
+
165 printf(" - Hardware: %s\n", timestampCapabilities & BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE ? "yes" : "no");
+
166 printf("\n");
+
167
+
168 // Check if configured timestamp mode is available... if not exit now...
+
169 if(timestampMode && !(timestampMode & timestampCapabilities))
+
170 {
+
171 printf("[ERROR] Specified timestamp mode is not available on the adapter... will exit now.\n");
+
172 retVal = -1;
+
173 break;
+
174 }
+
175
+
176 // Apply the configured timestamp mode to the previously opened handle.
+
177 if(!BRAWCAP_SUCCESS(brawcap_rx_timestamp_mode_set(pHandle, timestampMode)))
+
178 {
+
179 printf("[ERROR] Unexpected status while applying configured timestamp mode: %d\n", brawcap_last_status());
+
180 retVal = -1;
+
181 break;
+
182 }
+
183
+
184 // Create a packet object
+
185 // For simplicity and to make sure that we get all packets,
+
186 // we set the payload size to the max supported value.
+
187 if(!BRAWCAP_SUCCESS(brawcap_packet_create(&pPacket, BRAWCAP_PACKET_SIZE_MAX)))
+
188 {
+
189 printf("[ERROR] Unexpected status while creating packet: %d\n", brawcap_last_status());
+
190 retVal = -1;
+
191 break;
+
192 }
+
193
+
194 // Some local variables to buffer the timestamp info, later on.
+
195 brawcap_timestamp_t* pTimestamp = 0;
+
196 brawcap_timestamp_mode_t source = BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP;
+
197 brawcap_timestamp_resolution_ns_t resolution = 0;
+
198 UINT64 sec = 0;
+
199 UINT32 ns = 0;
+
200
+
201 // Our receive loop, we stay in here until we should stop receiving.
+
202 while(1)
+
203 {
+
204 // Now lets see if we have received a packet...
+
205 status = brawcap_rx_packet(pHandle, pPacket);
+
206
+
207 // Seems like we had success and got some packet data to look at. :-)
+
208 if(BRAWCAP_SUCCESS(status))
+
209 {
+
210 // Check if we made it out of the demo limitation... :-D
+
211 // ... notify the user and go ahead with receiving.
+
212 if (demoModeLogged)
+
213 {
+
214 printf("[NOTICE] DEMO MODE: Limitation period elapsed, receiving is available again.\n");
+
215 demoModeLogged = 0;
+
216 }
+
217
+
218 // --> The bRAWcap functions below can only fail if we did something wrong.
+
219 // But we are sure that we did everything right...
+
220 // therefore we do not check their status.
+
221 brawcap_packet_timestamp_get(pPacket, &pTimestamp);
+
222 brawcap_timestamp_mode_get(pTimestamp, &source);
+
223 brawcap_timestamp_resolution_ns_get(pTimestamp, &resolution);
+
224 switch(accuracy)
+
225 {
+
226 case 1:
+
227 brawcap_timestamp_value_ns_get(pTimestamp, &sec, &ns);
+
228 break;
+
229 case 2:
+
230 brawcap_timestamp_value_us_get(pTimestamp, &sec, &ns);
+
231 ns *= BRAWCAP_TIMESTAMP_NS_PER_US;
+
232 break;
+
233 case 3:
+
234 brawcap_timestamp_value_ms_get(pTimestamp, &sec, &ns);
+
235 ns *= BRAWCAP_TIMESTAMP_NS_PER_MS;
+
236 break;
+
237 }
+
238 struct tm *tmp = gmtime((time_t*)&sec);
+
239
+
240 // Print the packet timestamp info to console
+
241 printf("%llu. Received Packet Timestamp:\n", ++packetCounter);
+
242 printf(" - Source/Mode: ");
+
243 switch(source)
+
244 {
+
245 case BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP: printf("No Timestamp\n"); break;
+
246 case BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC: printf("Driver System Low Precision\n"); break;
+
247 case BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC: printf("Driver System High Precision\n"); break;
+
248 case BRAWCAP_TIMESTAMP_MODE_SOFTWARE: printf("Driver Software (QPC)\n"); break;
+
249 case BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM: printf("Adapter System\n"); break;
+
250 case BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE: printf("Adapter Software (QPC)\n"); break;
+
251 case BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE: printf("Adapter Hardware\n"); break;
+
252 }
+
253 printf(" - Resolution: ");
+
254 resolution != BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN
+
255 ? printf("%09u ns\n", resolution)
+
256 : printf(" UNKNOWN\n");
+
257 printf(" - Timestamp: %llu %09u ns (<=> %02u.%02u.%04u %02u:%02u:%02u.%09u)\n\n", sec, ns,
+
258 tmp->tm_mday, tmp->tm_mon+1, tmp->tm_year+1900,
+
259 tmp->tm_hour, tmp->tm_min, tmp->tm_sec, ns);
+
260 }
+
261 // Hm... we got a very silent connection...
+
262 // ... lets try again...
+
263 else if (status == BRAWCAP_STATUS_INFO_NO_DATA)
+
264 continue;
+
265 // Sad but we do not have a bRAWcap license for this feature... yet. :-(
+
266 // Notify our user about this sad information and
+
267 // wait some time to check if we are allowed to receive again...
+
268 else if (status == BRAWCAP_STATUS_WARNING_DEMO_MODE)
+
269 {
+
270 if (!demoModeLogged)
+
271 {
+
272 demoModeLogged = 1;
+
273 printf("[WARNING] DEMO MODE: Receiving not available.\n");
+
274 }
+
275 Sleep(1000);
+
276 }
+
277 // Ok... Something strange happened here... :-O
+
278 // Better stop now if we do not know how to handle it.
+
279 else
+
280 {
+
281 printf("[ERROR] Unexpected status while receiving packet: %d\n", brawcap_last_status());
+
282 retVal = -1;
+
283 break;
+
284 }
+
285 }
+
286 }while(0);
+
287
+
288 // We do not want to produce any memory leaks...
+
289 // ... so always cleanup what we have created
+
290 // --> The functions here can only fail if we did something wrong.
+
291 // But we are sure that we did everything right...
+
292 // therefore we do not check their status.
+
293 if (pPacket)
+
294 brawcap_packet_free(pPacket);
+
295 if (pHandle)
+
296 brawcap_close(pHandle);
+
297
+
298 return retVal;
+
299}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
BRAWCAP_STATUS_INFO_NO_DATA
@ BRAWCAP_STATUS_INFO_NO_DATA
Indicates that a function returns without any data.
Definition: brawcap_types_shared.h:333
+
BRAWCAP_STATUS_WARNING_DEMO_MODE
@ BRAWCAP_STATUS_WARNING_DEMO_MODE
The operation was not executed due to demo mode limitations.
Definition: brawcap_types_shared.h:256
+
brawcap_timestamp_capabilities_t
UINT32 brawcap_timestamp_capabilities_t
Type used for indicating the supported timestamp modes.
Definition: brawcap_types_shared.h:524
+
BRAWCAP_TIMESTAMP_NS_PER_MS
#define BRAWCAP_TIMESTAMP_NS_PER_MS
Number of nanoseconds per millisecond.
Definition: brawcap_types_shared.h:516
+
brawcap_timestamp_value_us_get
brawcap_status_t brawcap_timestamp_value_us_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMicroseconds)
Reads out the timestamp value in seconds and microseconds.
+
brawcap_timestamp_value_ms_get
brawcap_status_t brawcap_timestamp_value_ms_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pMilliseconds)
Reads out the timestamp value in seconds and milliseconds.
+
brawcap_timestamp_resolution_ns_get
brawcap_status_t brawcap_timestamp_resolution_ns_get(brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_resolution_ns_t *const pResolution_ns)
Reads out the timestamp resolution of the specified timestamp.
+
brawcap_timestamp_t
struct _brawcap_timestamp brawcap_timestamp_t
bRAWcap timestamp object.
Definition: brawcap_types_shared.h:612
+
brawcap_timestamp_value_ns_get
brawcap_status_t brawcap_timestamp_value_ns_get(brawcap_timestamp_t *const pTimestamp, UINT64 *const pSeconds, UINT32 *const pNanoseconds)
Reads out the timestamp value in seconds and nanoseconds.
+
brawcap_timestamp_resolution_ns_t
UINT32 brawcap_timestamp_resolution_ns_t
Represents the timestamp resolution in nanoseconds.
Definition: brawcap_types_shared.h:533
+
BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN
#define BRAWCAP_TIMESTAMP_RESOLUTION_UNKNOWN
If a timestamp resolution is set to this value, it´s resolution is unknown - could not be resolved.
Definition: brawcap_types_shared.h:491
+
brawcap_timestamp_mode_t
brawcap_timestamp_mode_t
List of different timestamp modes.
Definition: brawcap_types_shared.h:574
+
brawcap_timestamp_mode_get
brawcap_status_t brawcap_timestamp_mode_get(brawcap_timestamp_t *const pTimestamp, brawcap_timestamp_mode_t *const pMode)
Reads out the mode of the specified timestamp.
+
BRAWCAP_TIMESTAMP_NS_PER_US
#define BRAWCAP_TIMESTAMP_NS_PER_US
Number of nanoseconds per microsecond.
Definition: brawcap_types_shared.h:511
+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC
@ BRAWCAP_TIMESTAMP_MODE_SYSTEM_HIGHPREC
A high precision system timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:586
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_HARDWARE
A hardware timestamp created by the network adapter hardware/firmware.
Definition: brawcap_types_shared.h:602
+
BRAWCAP_TIMESTAMP_MODE_SOFTWARE
@ BRAWCAP_TIMESTAMP_MODE_SOFTWARE
A software timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:590
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_SYSTEM
A system timestamp created by the network adapter driver.
Definition: brawcap_types_shared.h:594
+
BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE
@ BRAWCAP_TIMESTAMP_MODE_ADAPTER_SOFTWARE
A software timestamp created by the network adapter driver.
Definition: brawcap_types_shared.h:598
+
BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
@ BRAWCAP_TIMESTAMP_MODE_NO_TIMESTAMP
No timestamp.
Definition: brawcap_types_shared.h:578
+
BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
@ BRAWCAP_TIMESTAMP_MODE_SYSTEM_LOWPREC
A low precision system timestamp created by bRAWcap driver.
Definition: brawcap_types_shared.h:582
+
brawcap_packet_create
brawcap_status_t brawcap_packet_create(brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
Creates a new packet.
+
brawcap_packet_t
struct _brawcap_packet brawcap_packet_t
bRAWcap packet object.
Definition: brawcap_types_shared.h:679
+
BRAWCAP_PACKET_SIZE_MAX
#define BRAWCAP_PACKET_SIZE_MAX
The maximum supported (byte) size for a single packet payload.
Definition: brawcap_types_shared.h:649
+
brawcap_packet_timestamp_get
brawcap_status_t brawcap_packet_timestamp_get(brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
Reads out the timestamp object for the specified packet.
+
brawcap_packet_free
brawcap_status_t brawcap_packet_free(brawcap_packet_t *pPacket)
Frees the specified packet. When this function is called the specified packet becomes invalid and it´...
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
brawcap_rx_packet
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_rx_timestamp_capabilities
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_rx_timestamp_mode_set
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.
+
+ + + + + + diff --git a/sdk/c/doc/html/a00925.html b/sdk/c/doc/html/a00925.html new file mode 100644 index 0000000..b5f51d1 --- /dev/null +++ b/sdk/c/doc/html/a00925.html @@ -0,0 +1,374 @@ + + + + + + + + +bRAWcap: 06_filter_firewall.c + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
bRAWcap 1.0.1 +
+
b-plus Technologies - Ethernet Performance Transmitter Receiver
+
+
+ + + + + + + +
+ +
+
+ + +
+
+
+
+
+
Loading...
+
Searching...
+
No Matches
+
+
+
+
+ +
+
06_filter_firewall.c
+
+
+

This example shows how bRAWcap can be used to filter (discard) specific packets by using a byte filter.

+
1/**
+
2 * @file 06_filter_firewall.c
+
3 *
+
4 * @brief bRAWcap Example - Demonstrates how to throw away specific received packets.
+
5 *
+
6 * It shows how to:
+
7 * - Open a handle to the first available adapter
+
8 * - Create and apply a receive filter
+
9 * - Read the receive statistics
+
10 *
+
11 * This example makes use of C only.
+
12 *
+
13 * @version 1.0
+
14 *
+
15 * @date 2023-03-28
+
16 *
+
17 * @copyright
+
18 * <b> © 2021 - b-plus technologies GmbH. All rights reserved!</b>
+
19 *
+
20 * All rights exclusively reserved for b-plus GmbH, unless expressly otherwise agreed.
+
21 *
+
22 * Redistribution in source or any other form, with or without modification, is not permitted.
+
23 *
+
24 * You may use this code under the according license terms of b-plus.
+
25 * Please contact b-plus at services@b-plus.com to get the appropriate terms and conditions.
+
26 */
+
27// Include bRAWcap
+
28#include "libbrawcap.h"
+
29
+
30// C STD
+
31#include <stdlib.h> // for strtol
+
32#include <stdio.h> // for printf
+
33#include <time.h> // for printing time info
+
34
+
35// Check command line parameters if a custom execution time is specified
+
36// To configure a custom execution time use "-t numberOfSeconds"
+
37#if 1
+
38void ParseArgs(int argc, char** argv, int* exec_time)
+
39{
+
40 if(argc > 1)
+
41 {
+
42 if(!memcmp(argv[1], "-t", 2))
+
43 {
+
44 char* pEnd = 0;
+
45 *exec_time = strtol(argv[2], &pEnd,0);
+
46 }
+
47 }
+
48}
+
49#endif
+
50
+
51int main(int argc, char** argv)
+
52{
+
53 // Set console title
+
54 SetConsoleTitleA("bRAWcap Example - Firewall for SSDP Packets");
+
55
+
56 // Some generic helper locals...
+
57 int retVal = 0;
+
58 int exec_time = 300; // 5 minutes
+
59 int runtime_sec = 0;
+
60
+
61 // Parse command line argument, to check for user specified execution time
+
62 ParseArgs(argc, argv, &exec_time);
+
63
+
64 // Here we will store the status of any bRAWcap function
+
65 brawcap_status_t status = BRAWCAP_STATUS_SUCCESS;
+
66
+
67 // Here we store the number of available bRAWcap adapters
+
68 brawcap_adapter_count_t numberAdapters = 0;
+
69 // This will contain our bRAWcap handle to the adapter we want to receive from
+
70 brawcap_handle_t* pHandle = 0;
+
71 // Our local filter to configure which packets should be dropped
+
72 brawcap_filter_t* pFilter = 0;
+
73
+
74 do
+
75 {
+
76 // First check if we have any bRAWcap adapters available.
+
77 // --> This function can only fail if we did something wrong.
+
78 // But we are sure that we did everything right...
+
79 // therefore we do not check it´s status.
+
80 brawcap_adapter_list_count(&numberAdapters);
+
81
+
82 // No adapters... nothing do receive from... lets exit ...
+
83 if (!numberAdapters)
+
84 {
+
85 printf("[WARNING] No bRAWcap adapter available... Will stop now.");
+
86 break;
+
87 }
+
88
+
89 // Get the name of the first adapter.
+
90 // To not overload the example with complex stuff,
+
91 // we always go for the first available adapter.
+
92 brawcap_adapter_name_t name = { '\0' };
+
93 if (!BRAWCAP_SUCCESS(brawcap_adapter_list_at(0, name)))
+
94 {
+
95 printf("[ERROR] Unexpected status while retrieving adapter name: %d", brawcap_last_status());
+
96 retVal = -1;
+
97 break;
+
98 }
+
99
+
100 // Create a filter object where to store our filter settings
+
101 if(!BRAWCAP_SUCCESS(brawcap_filter_create(&pFilter, BRAWCAP_FILTER_TYPE_BYTE_MASK)))
+
102 {
+
103 printf("[ERROR] Unexpected status while creating the filter: %d", brawcap_last_status());
+
104 retVal = -1;
+
105 break;
+
106 }
+
107
+
108 // Local filter attributes
+
109 brawcap_filter_byte_length_t filterOffset = 0;
+
110 brawcap_filter_byte_length_t filterLength = 0;
+
111 brawcap_filter_mask_array_t filterMask = { 0 };
+
112 brawcap_filter_ignore_bits_array_t filterBitMask = { 0 };
+
113
+
114 /* Lets specify our (byte) filter.
+
115 *
+
116 * In this example we want to filter out all SSDP (Simple Service Discover Protocol) packets.
+
117 *
+
118 * -- If you need those packets, change the filter to another packet type. --
+
119 *
+
120 * SSDP packets can be identified by their 1900 port and
+
121 * typically they are transmitted via UDP - so we filter for UDP destination port 1900.
+
122 *
+
123 * To make the filter more precise we also check if the transport protocol is UDP.
+
124 * UDP is identified by the IP protocol type 17 (we always assume IPv4 for this example).
+
125 */
+
126
+
127 // Lets start our filter at the IP protocol type which is byte 23 (for IPv4):
+
128 filterOffset = 23;
+
129
+
130 // Because we also need to check for UDP destination port at byte 36-37 (also for IPv4)
+
131 // our filter length must be 37 - 23 = 14 bytes
+
132 filterLength = 14;
+
133
+
134 // Now specify the UDP protocol type and the UDP destination port in the filter mask
+
135 // IPv4 Protocol type = UDP (17 <=> 0x11)
+
136 filterMask[0] = 0x11;
+
137 // UDP destination port = SSDP (1900 <=> 0x076C)
+
138 filterMask[13] = 0x07;
+
139 filterMask[14] = 0x6C;
+
140
+
141 // Ignore all bits of the bytes between IPv4 protocol type and UDP destination port.
+
142 // Therefore we must set each bit in this range to 1.
+
143 memset(&filterBitMask[1], 0xFF, 12);
+
144
+
145 // Now set our filter attributes to the previous created filter.
+
146 brawcap_filter_mask_set(pFilter, filterOffset, filterLength, filterMask, filterBitMask);
+
147
+
148 // Because we want to discard matched packets - do not forward to network stack -
+
149 // we set the filter indication to false
+
150 brawcap_filter_indicate_set(pFilter, 0);
+
151
+
152 // Set the filter to active
+
153 brawcap_filter_activate(pFilter);
+
154
+
155 // Open a handle to the adapter by using the retrieved name.
+
156 if (!BRAWCAP_SUCCESS(brawcap_open(name, &pHandle)))
+
157 {
+
158 printf("[ERROR] Unexpected status while opening handle: %d", brawcap_last_status());
+
159 retVal = -1;
+
160 break;
+
161 }
+
162
+
163 // Now lets apply the filter to our opened handle
+
164 if(!BRAWCAP_SUCCESS(brawcap_rx_filter_set(pHandle, pFilter)))
+
165 {
+
166 printf("[ERROR] Unexpected status while applying the filter: %d", brawcap_last_status());
+
167 retVal = -1;
+
168 break;
+
169 }
+
170
+
171 // Because we do not want to process the packets somehow and just filter them.
+
172 // we can also reduce the drivers receive queue size for this handle to zero.
+
173 // With this setting the driver doesn´t even try to buffer those packets.
+
174 if(!BRAWCAP_SUCCESS(brawcap_rx_driver_queue_size_set(pHandle, 0)))
+
175 {
+
176 printf("[ERROR] Unexpected status while reducing driver queue size: %d", brawcap_last_status());
+
177 retVal = -1;
+
178 break;
+
179 }
+
180
+
181 // Local receive stats for some user feedback
+
182 brawcap_stats_rx_t rxStats;
+
183 rxStats.header.type = BRAWCAP_STATS_TYPE_RX;
+
184 rxStats.header.revision = BRAWCAP_STATS_RX_REVISION_1;
+
185 rxStats.header.size = BRAWCAP_STATS_RX_SIZEOF_REVISION_1;
+
186
+
187 // After applying the filter we would have finished here...
+
188 // Because we do not want to receive the filtered packets and only drop them.
+
189 // The bRAWcap driver does everything for us and we just need to keep the handle open.
+
190 do
+
191 {
+
192 // To give the user some feedback request the statistic counters from bRAWcap and
+
193 // print how many packets have been blocked by our "firewall" since applying it.
+
194 if (!BRAWCAP_SUCCESS(brawcap_stats_rx(pHandle, &rxStats)))
+
195 printf("[ERROR] Unexpected status while requesting receive stats: %d", brawcap_last_status());
+
196 else
+
197 {
+
198 time_t curTime = time(0);
+
199 char strTime[30];
+
200 strftime(strTime, 30, "<%F %X>", localtime(&curTime));
+
201 // We could also use the rxStats.handleDroppedPacketsQueue here.
+
202 // Both values should be equal as long as we do not process any of the matched packet
+
203 // by calling a bRAWcap receive function.
+
204 printf("%s Number of blocked packets: %llu\n", strTime, rxStats.handleReceivedPacketsMatched);
+
205 }
+
206
+
207 Sleep(1000);
+
208 } while (++runtime_sec < exec_time);
+
209 }while(0);
+
210
+
211 // We do not want to produce any memory leaks...
+
212 // ... so always cleanup what we have created
+
213 // --> The functions here can only fail if we did something wrong.
+
214 // But we are sure that we did everything right...
+
215 // therefore we do not check their status.
+
216 if (pHandle)
+
217 brawcap_close(pHandle);
+
218 if(pFilter)
+
219 brawcap_filter_free(pFilter);
+
220
+
221 return retVal;
+
222}
+
libbrawcap.h
bRAWcap main header.
+
brawcap_handle_t
struct _brawcap_handle brawcap_handle_t
A bRAWcap handle.
Definition: brawcap_types_um.h:173
+
brawcap_close
brawcap_status_t brawcap_close(brawcap_handle_t *pHandle)
Closes the specified bRAWcap handle.
+
brawcap_open
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_last_status
brawcap_status_t brawcap_last_status()
Reads the last status appeared in bRAWcap, for the calling thread.
+
brawcap_status_t
brawcap_status_t
bRAWcap status/return codes.
Definition: brawcap_types_shared.h:150
+
BRAWCAP_SUCCESS
#define BRAWCAP_SUCCESS(status)
Checks if the returned status indicates a success with no additional info.
Definition: brawcap_types_shared.h:122
+
BRAWCAP_STATUS_SUCCESS
@ BRAWCAP_STATUS_SUCCESS
Definition: brawcap_types_shared.h:152
+
brawcap_adapter_list_at
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_adapter_list_count
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_adapter_name_t
char brawcap_adapter_name_t[BRAWCAP_ADAPTER_NAME_LENGTH]
Fixed size array containing a adapter name.
Definition: brawcap_types_um.h:257
+
brawcap_adapter_count_t
UINT8 brawcap_adapter_count_t
Type used for counting the available/supported adapters on a machine.
Definition: brawcap_types_um.h:242
+
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)
Sets the driver queue size (in number of packets) for the specified handle.
+
brawcap_rx_filter_set
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_filter_mask_array_t
UINT8 brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a filter byte mask.
Definition: brawcap_types_shared.h:900
+
brawcap_filter_create
brawcap_status_t brawcap_filter_create(brawcap_filter_t **const pFilter, const brawcap_filter_type_t type)
Creates a new filter.
+
brawcap_filter_t
struct _brawcap_filter brawcap_filter_t
bRAWcap filter object.
Definition: brawcap_types_shared.h:973
+
brawcap_filter_ignore_bits_array_t
UINT8 brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
Fixed size array for storing a byte wise bitfield.
Definition: brawcap_types_shared.h:912
+
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)
Sets the filter parameters for the specified filter.
+
brawcap_filter_free
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 me...
+
brawcap_filter_byte_length_t
brawcap_packet_size_t brawcap_filter_byte_length_t
Type for specifying the byte filter length.
Definition: brawcap_types_shared.h:917
+
brawcap_filter_indicate_set
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_filter_activate
brawcap_status_t brawcap_filter_activate(brawcap_filter_t *const pFilter)
Sets the specified filter to active.
+
BRAWCAP_FILTER_TYPE_BYTE_MASK
@ BRAWCAP_FILTER_TYPE_BYTE_MASK
A bRAWcap byte filter.
Definition: brawcap_types_shared.h:931
+
brawcap_stats_rx_t
The bRAWcap receive statistics.
Definition: brawcap_types_shared.h:1303
+
brawcap_stats_rx_t::handleReceivedPacketsMatched
UINT64 handleReceivedPacketsMatched
The total number of packets which have matched the given bRAWcap handle filter.
Definition: brawcap_types_shared.h:1353
+
brawcap_stats_header_t::revision
BYTE revision
Indicates the revision of the stats.
Definition: brawcap_types_shared.h:1251
+
brawcap_stats_header_t::size
UINT16 size
Should be set to the size of the structure depending on it´s type and revision. You should use the BR...
Definition: brawcap_types_shared.h:1256
+
brawcap_stats_header_t::type
BYTE type
Indicates which type of stats it is.
Definition: brawcap_types_shared.h:1245
+
brawcap_stats_rx_t::header
brawcap_stats_header_t header
Header for receive statistics. This has to be always initialized by the user after creation before us...
Definition: brawcap_types_shared.h:1308
+
brawcap_stats_rx
brawcap_status_t brawcap_stats_rx(brawcap_handle_t *const pHandle, brawcap_stats_rx_t *const pStats)
Reads out the available receive statistic counters for the specified handle.
+
BRAWCAP_STATS_RX_SIZEOF_REVISION_1
#define BRAWCAP_STATS_RX_SIZEOF_REVISION_1
Returns the size of receive statistics revision 1.
Definition: brawcap_types_shared.h:1390
+
BRAWCAP_STATS_RX_REVISION_1
@ BRAWCAP_STATS_RX_REVISION_1
Revision 1 for receive stats.
Definition: brawcap_types_shared.h:1282
+
BRAWCAP_STATS_TYPE_RX
@ BRAWCAP_STATS_TYPE_RX
Type for receive stats.
Definition: brawcap_types_shared.h:1267
+
+ + + + + + diff --git a/sdk/c/doc/html/annotated.html b/sdk/c/doc/html/annotated.html index b51a34c..cad18cd 100644 --- a/sdk/c/doc/html/annotated.html +++ b/sdk/c/doc/html/annotated.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -110,15 +110,15 @@
Here are the data structures with brief descriptions:
- - - - - - - - - + + + + + + + + +
 Cbrawcap_adapter_ipv4_tIPv4 address
 Cbrawcap_adapter_ipv6_tIPv6 address
 Cbrawcap_bpf_insn_tA single BPF pseudo-instruction
 Cbrawcap_bpf_program_tA BPF pseudo-assembly program
 Cbrawcap_stats_header_tHeader describing given bRAWcap stats structure
 Cbrawcap_stats_rx_tThe bRAWcap receive statistics
 Cbrawcap_stats_tx_tThe bRAWcap transmit statistics
 Cbrawcap_version_fragments_tStruct containing the separated version parts
 Cbrawcap_version_tBRAWcap version
 Cbrawcap_adapter_ipv4_tIPv4 address
 Cbrawcap_adapter_ipv6_tIPv6 address
 Cbrawcap_bpf_insn_tA single BPF pseudo-instruction
 Cbrawcap_bpf_program_tA BPF pseudo-assembly program
 Cbrawcap_stats_header_tHeader describing given bRAWcap stats structure
 Cbrawcap_stats_rx_tThe bRAWcap receive statistics
 Cbrawcap_stats_tx_tThe bRAWcap transmit statistics
 Cbrawcap_version_fragments_tStruct containing the separated version parts
 Cbrawcap_version_tBRAWcap version
diff --git a/sdk/c/doc/html/classes.html b/sdk/c/doc/html/classes.html index 14e3902..5d724ed 100644 --- a/sdk/c/doc/html/classes.html +++ b/sdk/c/doc/html/classes.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -112,7 +112,7 @@
B
-
brawcap_adapter_ipv4_t
brawcap_adapter_ipv6_t
bpf_insn
bpf_program
brawcap_stats_header_t
brawcap_stats_rx_t
brawcap_stats_tx_t
brawcap_version_fragments_t
brawcap_version_t
+
brawcap_adapter_ipv4_t
brawcap_adapter_ipv6_t
bpf_insn
bpf_program
brawcap_stats_header_t
brawcap_stats_rx_t
brawcap_stats_tx_t
brawcap_version_fragments_t
brawcap_version_t
diff --git a/sdk/c/doc/html/dir_7b89567e327017dae4de490a86c928ab.html b/sdk/c/doc/html/dir_7b89567e327017dae4de490a86c928ab.html index 0357460..2b79ab3 100644 --- a/sdk/c/doc/html/dir_7b89567e327017dae4de490a86c928ab.html +++ b/sdk/c/doc/html/dir_7b89567e327017dae4de490a86c928ab.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -115,14 +115,14 @@ - - + + - - + + - - + +

Files

file  brawcap.h [code]
 bRAWcap API - Functions.
file  brawcap.h [code]
 bRAWcap API - Functions.
 
file  brawcap_types_shared.h [code]
 bRAWcap API - Shared types.
file  brawcap_types_shared.h [code]
 bRAWcap API - Shared types.
 
file  brawcap_types_um.h [code]
 bRAWcap API - User mode types.
file  brawcap_types_um.h [code]
 bRAWcap API - User mode types.
 
diff --git a/sdk/c/doc/html/dir_d28a4824dc47e487b107a5db32ef43c4.html b/sdk/c/doc/html/dir_d28a4824dc47e487b107a5db32ef43c4.html index f2b78c6..7504e5b 100644 --- a/sdk/c/doc/html/dir_d28a4824dc47e487b107a5db32ef43c4.html +++ b/sdk/c/doc/html/dir_d28a4824dc47e487b107a5db32ef43c4.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -115,35 +115,35 @@ - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + +

Files

file  01_adapter_property_reader.c
 bRAWcap Example - Demonstrates the usage of the adapter handling module.
file  01_adapter_property_reader.c
 bRAWcap Example - Demonstrates the usage of the adapter handling module.
 
file  02_adapter_change_notifier.c
 bRAWcap Example - Demonstrates the usage of the adapter handling module.
file  02_adapter_change_notifier.c
 bRAWcap Example - Demonstrates the usage of the adapter handling module.
 
file  03_generic_handle_opener.c
 bRAWcap Example - Demonstrates the usage of the generic bRAWcap functions.
file  03_generic_handle_opener.c
 bRAWcap Example - Demonstrates the usage of the generic bRAWcap functions.
 
file  04_version_comparator.c
 bRAWcap Example - Demonstrates how to use the bRAWcap version.
file  04_version_comparator.c
 bRAWcap Example - Demonstrates how to use the bRAWcap version.
 
file  05_receive_simple_packet_receiver.c
 bRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets.
file  05_receive_simple_packet_receiver.c
 bRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets.
 
file  06_filter_firewall.c
 bRAWcap Example - Demonstrates how to throw away specific received packets.
file  06_filter_firewall.c
 bRAWcap Example - Demonstrates how to throw away specific received packets.
 
file  07_receive_buffered_receiver.c
 bRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers.
file  07_receive_buffered_receiver.c
 bRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers.
 
file  08_receive_timestamp_inspector.c
 bRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes.
file  08_receive_timestamp_inspector.c
 bRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes.
 
file  09_transmit_simple_packet_transmitter.c
 bRAWcap Example - TODO:
file  09_transmit_simple_packet_transmitter.c
 bRAWcap Example - TODO:
 
file  10_transmit_buffered_transmitter.c
 bRAWcap Example - TODO:
file  10_transmit_buffered_transmitter.c
 bRAWcap Example - TODO:
 
diff --git a/sdk/c/doc/html/examples.html b/sdk/c/doc/html/examples.html index 8020d21..4802ed7 100644 --- a/sdk/c/doc/html/examples.html +++ b/sdk/c/doc/html/examples.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -109,14 +109,14 @@
Here is a list of all examples:
diff --git a/sdk/c/doc/html/files.html b/sdk/c/doc/html/files.html index 7af4b44..763c93e 100644 --- a/sdk/c/doc/html/files.html +++ b/sdk/c/doc/html/files.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -111,21 +111,21 @@
Here is a list of all documented files with brief descriptions:
[detail level 12]
- - - + + + - - - - - - - - - - - + + + + + + + + + + +
 ▼ brawcap
 brawcap.hBRAWcap API - Functions
 brawcap_types_shared.hBRAWcap API - Shared types
 brawcap_types_um.hBRAWcap API - User mode types
 brawcap.hBRAWcap API - Functions
 brawcap_types_shared.hBRAWcap API - Shared types
 brawcap_types_um.hBRAWcap API - User mode types
 ▼ examples
 01_adapter_property_reader.cBRAWcap Example - Demonstrates the usage of the adapter handling module
 02_adapter_change_notifier.cBRAWcap Example - Demonstrates the usage of the adapter handling module
 03_generic_handle_opener.cBRAWcap Example - Demonstrates the usage of the generic bRAWcap functions
 04_version_comparator.cBRAWcap Example - Demonstrates how to use the bRAWcap version
 05_receive_simple_packet_receiver.cBRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets
 06_filter_firewall.cBRAWcap Example - Demonstrates how to throw away specific received packets
 07_receive_buffered_receiver.cBRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers
 08_receive_timestamp_inspector.cBRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes
 09_transmit_simple_packet_transmitter.cBRAWcap Example - TODO:
 10_transmit_buffered_transmitter.cBRAWcap Example - TODO:
 libbrawcap.hBRAWcap main header
 01_adapter_property_reader.cBRAWcap Example - Demonstrates the usage of the adapter handling module
 02_adapter_change_notifier.cBRAWcap Example - Demonstrates the usage of the adapter handling module
 03_generic_handle_opener.cBRAWcap Example - Demonstrates the usage of the generic bRAWcap functions
 04_version_comparator.cBRAWcap Example - Demonstrates how to use the bRAWcap version
 05_receive_simple_packet_receiver.cBRAWcap Example - Demonstrates how to use bRAWcap to receive separated packets
 06_filter_firewall.cBRAWcap Example - Demonstrates how to throw away specific received packets
 07_receive_buffered_receiver.cBRAWcap Example - Demonstrates how to use bRAWcap to receive packets with packet buffers
 08_receive_timestamp_inspector.cBRAWcap Example - Demonstrates how to use bRAWcap to use different receive timestamp modes
 09_transmit_simple_packet_transmitter.cBRAWcap Example - TODO:
 10_transmit_buffered_transmitter.cBRAWcap Example - TODO:
 libbrawcap.hBRAWcap main header
diff --git a/sdk/c/doc/html/functions.html b/sdk/c/doc/html/functions.html index 989b27a..a0a6499 100644 --- a/sdk/c/doc/html/functions.html +++ b/sdk/c/doc/html/functions.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,111 +108,111 @@
Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- a -

- b -

- c -

- d -

- f -

- h -

- j -

- k -

- m -

- p -

- q -

- r -

- s -

- t -

- w -

diff --git a/sdk/c/doc/html/functions_vars.html b/sdk/c/doc/html/functions_vars.html index 8b729c7..3902613 100644 --- a/sdk/c/doc/html/functions_vars.html +++ b/sdk/c/doc/html/functions_vars.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,111 +108,111 @@  

- a -

- b -

- c -

- d -

- f -

- h -

- j -

- k -

- m -

- p -

- q -

- r -

- s -

- t -

- w -

diff --git a/sdk/c/doc/html/globals.html b/sdk/c/doc/html/globals.html index 436f256..37ba0ef 100644 --- a/sdk/c/doc/html/globals.html +++ b/sdk/c/doc/html/globals.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,7 +108,7 @@
Here is a list of all documented functions, variables, defines, enums, and typedefs with links to the documentation:

- _ -

diff --git a/sdk/c/doc/html/globals_b.html b/sdk/c/doc/html/globals_b.html index 50d1e53..c8c2b33 100644 --- a/sdk/c/doc/html/globals_b.html +++ b/sdk/c/doc/html/globals_b.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,286 +108,287 @@
Here is a list of all documented functions, variables, defines, enums, and typedefs with links to the documentation:

- b -

diff --git a/sdk/c/doc/html/globals_defs.html b/sdk/c/doc/html/globals_defs.html index 4a4d4be..fe3ca35 100644 --- a/sdk/c/doc/html/globals_defs.html +++ b/sdk/c/doc/html/globals_defs.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,56 +108,56 @@  

- _ -

- b -

diff --git a/sdk/c/doc/html/globals_enum.html b/sdk/c/doc/html/globals_enum.html index 7665ce6..e083b32 100644 --- a/sdk/c/doc/html/globals_enum.html +++ b/sdk/c/doc/html/globals_enum.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -106,21 +106,21 @@
 
diff --git a/sdk/c/doc/html/globals_eval.html b/sdk/c/doc/html/globals_eval.html index 4275a88..ab2e6bc 100644 --- a/sdk/c/doc/html/globals_eval.html +++ b/sdk/c/doc/html/globals_eval.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,89 +108,89 @@  

- b -

diff --git a/sdk/c/doc/html/globals_func.html b/sdk/c/doc/html/globals_func.html index 426ca24..952de1d 100644 --- a/sdk/c/doc/html/globals_func.html +++ b/sdk/c/doc/html/globals_func.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,119 +108,120 @@  

- b -

diff --git a/sdk/c/doc/html/globals_type.html b/sdk/c/doc/html/globals_type.html index ac44451..3c80569 100644 --- a/sdk/c/doc/html/globals_type.html +++ b/sdk/c/doc/html/globals_type.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -106,30 +106,30 @@
 
diff --git a/sdk/c/doc/html/index.html b/sdk/c/doc/html/index.html index ca59afe..bd793f5 100644 --- a/sdk/c/doc/html/index.html +++ b/sdk/c/doc/html/index.html @@ -56,7 +56,7 @@ Logo -
bRAWcap 1.0.0 +
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
@@ -108,12 +108,12 @@
Main Page
-

+

bRAWcap
Manual
-Version 1.0.0
-Date 2024-2-2
+Version 1.0.1
+Date 2024-11-12

b-plus technologies GmbH
 Ulrichsberger Str. 17
@@ -126,7 +126,7 @@ Legal Notice

Copyright © 2024 b-plus technologies GmbH All contents in this document, in particular texts and graphics, are protected by copyright (all rights reserved). Duplication (copy, print or any other form) as well as electronic distribution of this document is only permitted within statutory provisions or the written permission of b-plus technologies GmbH. b-plus technologies GmbH reserves the right to change technical data without prior notice. Names of products, companies, brands and so forth which are mentioned in this document are trademarks or registered trademarks of their respective owners. The general terms and conditions as well as the provisions of the license agreements apply. See general terms and conditions for more information. This document has been created with due care. b-plus technologies GmbH is not liable for damages which results directly or indirectly from errors, omissions or discrepancies between the product and the document.


Software Copyright
-

bRAWcap © 2024 b-plus technologies GmbH. All rights reserved! This software, including all code, text, and graphics, is the property of b-plus technologies GmbH or its licensors and is protected by international copyright laws. Unauthorized use, reproduction, or distribution of this software or any portion of it may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under the law. For general terms and Conditions for Software please go to General Terms & Conditions on our Website b-plus.com and download it there: general terms and conditions
bRAWcap ▪ 1.0.0 ▪ 2024-2-2

+

bRAWcap © 2024 b-plus technologies GmbH. All rights reserved! This software, including all code, text, and graphics, is the property of b-plus technologies GmbH or its licensors and is protected by international copyright laws. Unauthorized use, reproduction, or distribution of this software or any portion of it may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under the law. For general terms and Conditions for Software please go to General Terms & Conditions on our Website b-plus.com and download it there: general terms and conditions
bRAWcap ▪ 1.0.1 ▪ 2024-11-12

Contents

@@ -319,15 +321,15 @@

-CAUTION (yellow):
Instructions that, if ignored, could result in a crash by incorrect operation of the software.
+CAUTION (yellow):
Instructions that, if ignored, could result in a injury, failure or crash.
-ATTENTION (blue):
Instructions that, if ignored, could result in malfunction of the software or parts thereof..
+ATTENTION (blue):
Instructions that, if ignored, could result in malfunction.
-NOTE (grey):
This symbol refers to a note which can clarify a detail or expand on something mentioned. It provides context and more detail..
+NOTE (grey):
This symbol refers to a note which can clarify a detail or expand on something mentioned. It provides additional context and more details.
@@ -667,12 +669,12 @@

The API documentation is grouped into different modules. Each module is describing a specific part of the API.

5.3.2. Including

-

bRAWcap API is written in C and fully compatible to C99. All header files describing the API can be found in sdk\c\include. bRAWcap has in general four header files. It is recommended to always include the base header sdk\c\include\libbrawcap.h, which will than include all other headers for you.

+

bRAWcap API is written in C and fully compatible to C99. All header files describing the API can be found in sdk\c\include. bRAWcap has in general four header files. It is recommended to always include the base header sdk\c\include\libbrawcap.h, which will than include all other headers for you.

Here is a list of the other headers and a short description of their content:

5.3.3. Linking

@@ -693,12 +695,13 @@

7. Third-Party Legal Notice

    -
  • Driver [none]
    • -
  • Library [none]
    • -

  • Demo

    - -cxxopts - MIT License -

    +
  • Driver
    + [none]
    • +
  • Library
    + [none]
    • +

  • Demo +

    cxxopts +

    Copyright (c) 2014 Jarryd Beck
    Permission is hereby granted, free of charge, to any person obtaining a copy
    @@ -718,11 +721,12 @@

    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
    -

    -
    -
    - -PDCursesMod - Public Domain License +

+ +

+

+

PDCursesMod +

The core package is in the public domain, but small portions of PDCursesMod are subject to copyright under various
licenses. Each directory contains a README file, with a section titled "Distribution Status" which describes the
status of the files in that directory.
@@ -732,13 +736,13 @@

for the benefit of other users.
This software is provided AS IS with NO WARRANTY whatsoever.
-

-
+

+ +

-
  • Setup
    - -NSIS - zlib/libpng License -

    +

  • Setup +

    NSIS +

    Copyright
    Copyright (C) 1999-2023 Contributors
    @@ -962,13 +966,13 @@

    NSIS without subjecting your linked code to the terms of the Common Public license version 1.0. Any modifications
    or additions to files from the LZMA compression module for NSIS, however, are subject to the terms of the
    Common Public License version 1.0.
    -

    -
    +

    • + +

    -
  • Doc
    - -doxygen-awesome-css - MIT License -

    +

  • Doc +

    doxygen-awesome-css +

    MIT License
    Copyright (c) 2021 - 2023 jothepro
    @@ -990,8 +994,9 @@

    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    -

    -
    +

    • + +

    @@ -1051,7 +1056,7 @@

    8.1.3. High CPU Load

    First of all bRAWcap is handle based, which means that there can be several handles attached to the same adapter. This makes it possible that several processes (applications) can use bRAWcap independent from each other. If several applications use bRAWcap with the same receive filter for example, the CPU load will increase. Especially if the handles use no filtering (all packets are processed) the resulting CPU load have to be multiplied by the number of handles (for example if one handle produces 3% CPU load, than three handles will result in 9% CPU load).

    In general it is recommended to set the receive filter very precisely, that only packets which are really required are processed by bRAWcap. Overlapping filters on the same adapter should be avoided, if possible.

    -

    bRAWcap also allows to only process a subpart of each packet and not always the hole packet (see brawcap_filter_bytes_to_capture_set API function documentation). So if you are not interested in headers for example, configure bRAWcap to only supply the payload without headers.

    +

    bRAWcap also allows to only process a subpart of each packet and not always the hole packet (see brawcap_filter_bytes_to_capture_set API function documentation). So if you are not interested in headers for example, configure bRAWcap to only supply the payload without headers.

    NOTE Filtering vs Supplying
    If you set bRAWcap to only process a subpart of the packet, it is still possible to set the filter for the hole packet. For example if you do not want the header bytes to be part of the packet, you can still set a filter on those header bytes.
    @@ -1060,10 +1065,14 @@

    8.2. Version History

    Update history of bRAWcap and all of it´s components.

    8.2.1. Version 0.1.0

    @@ -1376,7 +1385,7 @@

  • Setup
      -
    • Added required VC redistributable to installer, will be automatically installed if no supported version is already available.
      • +
    • Added required VC re-distributable to installer, will be automatically installed if no supported version is already available.
    • @@ -1389,6 +1398,77 @@

  • Setup
    • +

    +8.2.5. Version 1.0.1

    +

    Release Date: 2024-11-05

    +
    +

    ‍Highlights

    +
      +
    • Updated driver signature method to Microsoft Attestation signature. Driver can no be installed and executed on Windows 10 & 11 with Secure Boot activated.
      • +
    +
    +
    +

    ‍Changes

    +
      +
    • Driver & Library
        +
      • Generic
          +
        • Added new API function for activating several log types and log levels at once (brawcap_log_levels_set)
          • +
        +
        • +
      +
      • +
    • Demo App
        +
      • Generic
          +
        • Command line parameter to adjust demo log levels.
          • +
        +
        • +
      +
      • +
    • CPP Wrapper
        +
      • Added new API function for activating several log types and log levels at once (BRAWcap::LogLevelsSet)
        • +
      +
      • +
    • Setup
        +
      • Improved driver installation-file to isolate driver in Windows driver store depending on Windows version
        • +
      • All b-plus and third party licenses will be available in installation directory ./licenses subpath
        • +
      +
      • +
    +
    +
    +

    ‍Bugfixes

    +
      +
    • Driver & Library
        +
      • [none]
        • +
      +
      • +
    • Demo App
        +
      • [none]
        • +
      +
      • +
    • Setup
        +
      • [none]
        • +
      +
      • +
    +
    +
    +

    ‍Open Issues

    +
      +
    • Driver & Library
        +
      • [none]
        • +
      +
      • +
    • Demo App
        +
      • [none]
        • +
      +
      • +
    • Setup
        +
      • [none]
        • +
      +
      • +
    +