libbdilog.h File Reference

#include <declspec_bdiutil.h>

Go to the source code of this file.

Macros
#define	CPLUSPLUS_ONLY
#define	CHECK_PRINTF_FORMAT   /* No support for non-GCC compilers */
#define	BDI_LOG_MAX_CALLBACKS   (8)
#define	BDI_LOG_BAD_CALLBACK_HANDLE   (-1)
#define	BDI_LOG_NOTHING   (-1)
	Log notify levels. More...
#define	BDI_LOG_ALWAYS   (0)
#define	BDI_LOG_FATAL   (1)
#define	BDI_LOG_ERROR   (2)
#define	BDI_LOG_WARN   (3)
#define	BDI_LOG_INFO   (4)
#define	BDI_LOG_DEBUG   (5)
#define	BDI_LOG_DEBUG_LV1   (6)
#define	BDI_LOG_DEBUG_LV2   (7)
#define	BDI_LOG_DEBUG_LV3   (8)
#define	BDI_LOG_DEBUG_LV4   (9)
#define	BDI_LOG_DEBUG_LV5   (10)
#define	BDI_LOG_DEBUG_LV6   (11)
#define	BDI_LOG_DEBUG_LV7   (12)
#define	BDI_LOG_DEBUG_LV8   (13)
#define	BDI_LOG_DEBUG_LV9   (14)
#define	BDI_LOG_EVERYTHING   (15)
#define	bdi_log_assert(assertion)   if (!(assertion)) {bdi_log_printf(BDI_LOG_ERROR, "ERROR: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define	bdi_log_assert_fatal(assertion)   if (!(assertion)) {bdi_log_printf(BDI_LOG_FATAL, "FATAL: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__); exit(EXIT_FAILURE);}
#define	bdi_log_assert_warn(assertion)   if (!(assertion)) {bdi_log_printf(BDI_LOG_WARN, "WARNING: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define	bdi_log_assert_info(assertion)   if (!(assertion)) {bdi_log_printf(BDI_LOG_INFO, "INFO: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define	bdi_log_assert_debug(assertion)   if (!(assertion)) {bdi_log_printf(BDI_LOG_DEBUG, "DEBUG: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}
#define	bdi_log_debug(string)   bdi_log_print(BDI_LOG_DEBUG, string)
#define	bdi_log_debug_arg0(string)   bdi_log_print(BDI_LOG_DEBUG, string)
#define	bdi_log_debug_arg1(string, arg1)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1)
#define	bdi_log_debug_arg2(string, arg1, arg2)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2)
#define	bdi_log_debug_arg3(string, arg1, arg2, arg3)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3)
#define	bdi_log_debug_arg4(string, arg1, arg2, arg3, arg4)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4)
#define	bdi_log_debug_arg5(string, arg1, arg2, arg3, arg4, arg5)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5)
#define	bdi_log_debug_arg6(string, arg1, arg2, arg3, arg4, arg5, arg6)   bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5, arg6)
#define	bdi_log_debug_lvn(level, string)   bdi_log_print(BDI_LOG_DEBUG_LV##level, string)
#define	bdi_log_debug_lvn_arg0(level, string)   bdi_log_print(BDI_LOG_DEBUG_LV##level, string)
#define	bdi_log_debug_lvn_arg1(level, string, arg1)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1)
#define	bdi_log_debug_lvn_arg2(level, string, arg1, arg2)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2)
#define	bdi_log_debug_lvn_arg3(level, string, arg1, arg2, arg3)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3)
#define	bdi_log_debug_lvn_arg4(level, string, arg1, arg2, arg3, arg4)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4)
#define	bdi_log_debug_lvn_arg5(level, string, arg1, arg2, arg3, arg4, arg5)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5)
#define	bdi_log_debug_lvn_arg6(level, string, arg1, arg2, arg3, arg4, arg5, arg6)   bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5, arg6)

Typedefs
typedef int	bdiCallbackHandle
typedef int	bdiLogCallbackFunction(int notify_level, const char *string, void *user_data)
typedef int	bdiLogFatalExitFunction(void)
typedef const char *	bdiLogPrefixFunction(void *user_data)

Functions
int	bdi_log_stderr_enable (int notify_level)
	This function will route a copy of appropriate log messages to stdio's stderr. More...
int	bdi_log_stderr_disable (void)
	This function shuts down the log opened by bdi_log_stderr_enable(). More...
int	bdi_log_stdout_enable (int notify_level)
	This function will route a copy of appropriate log messages to stdio's stdout. More...
int	bdi_log_stdout_disable (void)
	This function shuts down the log opened by bdi_log_stdout_enable(). More...
int	bdi_log_file_enable (int notify_level, const char *filename, int clear_file)
	This function will route a copy of appropriate log messages to the named file. More...
int	bdi_log_file_disable (void)
	This function shuts down the log opened by bdi_log_file_enable(). More...
int	bdi_log_print (int notify_level, const char *string)
	This function sends the specified string to all open logs. More...
int	bdi_log_printf (int notify_level, const char *format,...) CHECK_PRINTF_FORMAT
	printf-like version of bdi_log_print(). More...
int	bdi_log_set_global_notify_level (int notify_level)
	This function sets the global notify level. More...
int	bdi_log_get_global_notify_level (void)
	Returns the most recent setting of bdi_log_set_global_notify_level(). More...
bdiCallbackHandle	bdi_log_register_callback (int notify_level, bdiLogCallbackFunction *callback, void *user_data)
	This function registers a callback for the specified notify_level. More...
int	bdi_log_unregister_callback (bdiCallbackHandle handle)
	This function unregisters a previously registered callback. More...
int	bdi_log_get_num_logs_open ()
	This function returns the number of logs currently open. More...
int	bdi_log_set_notify_level (bdiCallbackHandle handle, int notify_level)
	This function changes the notify level of a registered callback. More...
int	bdi_log_get_notify_level (bdiCallbackHandle handle)
	This function returns the notify level of a registered callback. More...
void	bdi_log_get_string_from_notify_level (int notify_level, char *result, int result_buf_size)
	Derives a string from the notify level and returns it in the passed result buffer. More...
void	bdi_log_register_fatal_exit_function (bdiLogFatalExitFunction *fatal_exit_func)
	This function registers a function that will be called if a log message is sent with level BDI_LOG_FATAL. More...
int	bdi_log_print_to_output_window (const char *format,...)
	This function prints using OutputDebugString on Windows, which will show up in the Output window in Microsoft Developer Studio. More...
void	bdi_log_lock ()
	This function grabs the lock of the logging system. More...
void	bdi_log_unlock ()
	This function releases the lock of the logging system. More...

Variables
comment line count2comment line count2comment line count2comment line count2comment line	count2

Macro Definition Documentation

#define CPLUSPLUS_ONLY

#define CHECK_PRINTF_FORMAT   /* No support for non-GCC compilers */

#define BDI_LOG_MAX_CALLBACKS   (8)

#define BDI_LOG_BAD_CALLBACK_HANDLE   (-1)

#define BDI_LOG_NOTHING   (-1)

Log notify levels.

A lower number indicates higher importance.

#define BDI_LOG_ALWAYS   (0)

#define BDI_LOG_FATAL   (1)

#define BDI_LOG_ERROR   (2)

#define BDI_LOG_WARN   (3)

#define BDI_LOG_INFO   (4)

#define BDI_LOG_DEBUG   (5)

#define BDI_LOG_DEBUG_LV1   (6)

#define BDI_LOG_DEBUG_LV2   (7)

#define BDI_LOG_DEBUG_LV3   (8)

#define BDI_LOG_DEBUG_LV4   (9)

#define BDI_LOG_DEBUG_LV5   (10)

#define BDI_LOG_DEBUG_LV6   (11)

#define BDI_LOG_DEBUG_LV7   (12)

#define BDI_LOG_DEBUG_LV8   (13)

#define BDI_LOG_DEBUG_LV9   (14)

#define BDI_LOG_EVERYTHING   (15)

#define bdi_log_assert

(

assertion

)

if (!(assertion)) {bdi_log_printf(BDI_LOG_ERROR, "ERROR: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}

#define bdi_log_assert_fatal

(

assertion

)

if (!(assertion)) {bdi_log_printf(BDI_LOG_FATAL, "FATAL: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__); exit(EXIT_FAILURE);}

#define bdi_log_assert_warn

(

assertion

)

if (!(assertion)) {bdi_log_printf(BDI_LOG_WARN, "WARNING: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}

#define bdi_log_assert_info

(

assertion

)

if (!(assertion)) {bdi_log_printf(BDI_LOG_INFO, "INFO: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}

#define bdi_log_assert_debug

(

assertion

)

if (!(assertion)) {bdi_log_printf(BDI_LOG_DEBUG, "DEBUG: Assertion '%s' failed in file %s line %d\n", #assertion, __FILE__, __LINE__);}

#define bdi_log_debug

(

string

)

bdi_log_print(BDI_LOG_DEBUG, string)

#define bdi_log_debug_arg0

(

string

)

bdi_log_print(BDI_LOG_DEBUG, string)

#define bdi_log_debug_arg1	(		string,
			arg1
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1)

#define bdi_log_debug_arg2	(		string,
			arg1,
			arg2
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2)

#define bdi_log_debug_arg3	(		string,
			arg1,
			arg2,
			arg3
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3)

#define bdi_log_debug_arg4	(		string,
			arg1,
			arg2,
			arg3,
			arg4
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4)

#define bdi_log_debug_arg5	(		string,
			arg1,
			arg2,
			arg3,
			arg4,
			arg5
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5)

#define bdi_log_debug_arg6	(		string,
			arg1,
			arg2,
			arg3,
			arg4,
			arg5,
			arg6
	)		bdi_log_printf(BDI_LOG_DEBUG, string, arg1, arg2, arg3, arg4, arg5, arg6)

#define bdi_log_debug_lvn	(		level,
			string
	)		bdi_log_print(BDI_LOG_DEBUG_LV##level, string)

#define bdi_log_debug_lvn_arg0	(		level,
			string
	)		bdi_log_print(BDI_LOG_DEBUG_LV##level, string)

#define bdi_log_debug_lvn_arg1	(		level,
			string,
			arg1
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1)

#define bdi_log_debug_lvn_arg2	(		level,
			string,
			arg1,
			arg2
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2)

#define bdi_log_debug_lvn_arg3	(		level,
			string,
			arg1,
			arg2,
			arg3
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3)

#define bdi_log_debug_lvn_arg4	(		level,
			string,
			arg1,
			arg2,
			arg3,
			arg4
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4)

#define bdi_log_debug_lvn_arg5	(		level,
			string,
			arg1,
			arg2,
			arg3,
			arg4,
			arg5
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5)

#define bdi_log_debug_lvn_arg6	(		level,
			string,
			arg1,
			arg2,
			arg3,
			arg4,
			arg5,
			arg6
	)		bdi_log_printf(BDI_LOG_DEBUG_LV##level, string, arg1, arg2, arg3, arg4, arg5, arg6)

Typedef Documentation

typedef int bdiCallbackHandle

typedef int bdiLogCallbackFunction(int notify_level, const char *string, void *user_data)

typedef int bdiLogFatalExitFunction(void)

typedef const char* bdiLogPrefixFunction(void *user_data)

Function Documentation

int bdi_log_stderr_enable

(

int

notify_level

)

This function will route a copy of appropriate log messages to stdio's stderr.

Parameters

return	value 0 on success, -1 on failure
notify_level	only messages whose notify level is at least as important as this will appear in this log

int bdi_log_stderr_disable

(

void

)

This function shuts down the log opened by bdi_log_stderr_enable().

int bdi_log_stdout_enable

(

int

notify_level

)

This function will route a copy of appropriate log messages to stdio's stdout.

Parameters

return	value 0 on success, -1 on failure
notify_level	only messages whose notify level is at least as important as this will appear in this log

int bdi_log_stdout_disable

(

void

)

This function shuts down the log opened by bdi_log_stdout_enable().

Parameters

return

value 0 on success, -1 on failure

int bdi_log_file_enable	(	int	notify_level,
		const char *	filename,
		int	clear_file
	)

This function will route a copy of appropriate log messages to the named file.

Parameters

return	value 0 on success, -1 on failure
notify_level	only messages whose notify level is at least as important as this will appear in this log
filename	name of the file in which messages will appear
clear_file	0 or 1; 1 means clear out prior contents of file, 0 means append to the file

int bdi_log_file_disable

(

void

)

This function shuts down the log opened by bdi_log_file_enable().

Parameters

return

value 0 on success, -1 on failure

int bdi_log_print	(	int	notify_level,
		const char *	string
	)

This function sends the specified string to all open logs.

Whether or not the string is actually printed depends the specified notify_level in this call and the notify_level with which each log was opened.

Parameters

return	value 0 on success, -1 on failure
string	message to be (potentially) printed
notify_level	"importance" of message; lower is more important

int bdi_log_printf	(	int	notify_level,
		const char *	format,
			...
	)

printf-like version of bdi_log_print().

Use just like printf, but add the notify_level as the first argument.

Parameters

return

value 0 on success, -1 on failure

int bdi_log_set_global_notify_level

(

int

notify_level

)

This function sets the global notify level.

Messages whose notify_level argument is less important than this will not be printed, regardless of the notify_level used to open logs.

The starting global notify level is BDI_LOG_EVERYTHING.

Parameters

return	value 0 on success, -1 on failure
notify_level	global level of importance

Example:

// open a file log with notify level BDI_LOG_WARN
bdi_log_file_enable(BDI_LOG_WARN, "errors.txt", 1);

// this message WILL appear in the log
bdi_log_print(BDI_LOG_WARN, "Message 1.\n");

// set the global notify level to be more strict
bdi_log_set_global_notify_level(BDI_LOG_ERROR);

// this message WILL NOT appear in the log
// (log messages of importance less than BDI_LOG_ERROR are ignored.)
bdi_log_print(BDI_LOG_WARN, "Message 2.\n");

int bdi_log_get_global_notify_level

(

void

)

Returns the most recent setting of bdi_log_set_global_notify_level().

Parameters

return

value most recent setting

bdiCallbackHandle bdi_log_register_callback	(	int	notify_level,
		bdiLogCallbackFunction *	callback,
		void *	user_data
	)

This function registers a callback for the specified notify_level.

Parameters

return	value a handle
callback	pointer to the callback function
notify_level	level of "importance" the callback will be called for
user_data	pointer that will be supplied to the callback each time it is called.

int bdi_log_unregister_callback

(

bdiCallbackHandle

handle

)

This function unregisters a previously registered callback.

Parameters

return	value 0 on success, -1 on failure
handle	the handle returned by bdi_log_register_callback()

int bdi_log_get_num_logs_open

(

)

This function returns the number of logs currently open.

Parameters

return

value number of logs open

int bdi_log_set_notify_level	(	bdiCallbackHandle	handle,
		int	notify_level
	)

This function changes the notify level of a registered callback.

Parameters

return	value 0 on success, -1 on failure
handle	the handle returned by bdi_log_register_callback()
notify_level	the new notify level

int bdi_log_get_notify_level

(

bdiCallbackHandle

handle

)

This function returns the notify level of a registered callback.

Parameters

return	value most recent setting or BDI_LOG_NOTHING if handle is invalid
handle	the handle returned by bdi_log_register_callback()

void bdi_log_get_string_from_notify_level	(	int	notify_level,
		char *	result,
		int	result_buf_size
	)

Derives a string from the notify level and returns it in the passed result buffer.

a

Parameters

notify_level	notify level to parse
result	character buffer for result
result_max_len	result buffer size

void bdi_log_register_fatal_exit_function

(

bdiLogFatalExitFunction *

fatal_exit_func

)

This function registers a function that will be called if a log message is sent with level BDI_LOG_FATAL.

The function should whatever it takes to shut down gracefully.

If no fatal exit function is registered, exit(EXIT_FAILURE) will be called by default.

int bdi_log_print_to_output_window	(	const char *	format,
			...
	)

This function prints using OutputDebugString on Windows, which will show up in the Output window in Microsoft Developer Studio.

void bdi_log_lock

(

)

This function grabs the lock of the logging system.

This is pretty hacky. If you do not release this lock, you're in trouble. This can be useful for certain specialized interactions with log callback objects that rely on the libbdilog lock for their synchronization.

void bdi_log_unlock

(

)

This function releases the lock of the logging system.

This is pretty hacky. If you do not release this lock, you're in trouble. This can be useful for certain specialized interactions with log callback objects that rely on the libbdilog lock for their synchronization.

Variable Documentation

comment line count2comment line count2comment line count2comment line count2comment line count2