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:

• Status indicates success
• Status indicates error
• Status indicates warning
• Status indicates info

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.