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]	type	Log type for which to configure the log level.
[in]	level	The log level to be applied.
[in]	pKey	Key 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]	type	Log 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]	level	The log levels to be applied. Value has to be interpreted as bitfield. This allows to (de)activate several levels with only one call.
[in]	pKey	Key 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]	type	Log 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]	pLevel	Will 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.