/*
************************************************************************
**
**	Copyright (c) 2009..2010 by
**		Core|Vision B.V.
**		Cereslaan 10b
**		5384 VT  Heesch
**		The Netherlands
**
**	All Rights Reserved
**
************************************************************************
*/
/*
************************************************************************
**
**	Project name:   Dual Inventive: Utility Library
**	Filename:       zkldebug.h
**	Author:			Jack Weeland
**	Date:			August 7, 2009
**	File version:	1.00	of August 7, 2009
**
************************************************************************
*/
/*
************************************************************************
**
**	Debug functions - definitions
**
************************************************************************
*/

#ifndef __DI_DEBUG_H
#define	__DI_DEBUG_H

#include <stdarg.h>

/*
**	Definitions
*/

// is debugging enabled? (or rather, 'debug_init()' was called)
extern int __debug;

// internal buffer size; the client _must_ adhere this since to
//	prevent a crash
#define	DBG_BUFSZ				(16 * 1024)

// flags for 'set_debug_output()' and 'dbgxprintf()'
#define	DBGOUT_NONE				0x00000000	// 'dbgprintf()' doesn't do anything;
											//	'dbgxprinft()' can only output to
											//	syslog and stderr
#define	DBGOUT_FILE				0x00000001	// file or stdout
// syslog(3)
#define	DBGOUT_SYSLOG			0x00000010
// windows event viewer (complementary to syslog on Unix; not yet implemented)
#define	DBGOUT_EVENTLOG			0x00000010
// windows debugger (output window in Visual C++, external debugger,
//	remote debugger... output is sent to 'OutputDebugString()')
// on non-Windows platform, stderr is used.
#define	DBGOUT_OUTPUTWIN		0x00000020
#define	DBGOUT_WIN_DEBUGGER		(DBGOUT_OUTPUTWIN)
// application callback
#define	DBGOUT_APP				0x00000040	// application, see 'debug_set_app()'

// the following flags and modifiers can only be used with'dbgxprinf()'
#define	DBGOUT_OVERRIDE			0x40000000	// replace existing flags (instead of adding the new flags)
#define	DBGOUT_SPECIAL_SET		0x80000000	// special flags for dbgxprintf
#define	DBGOUT_SPECIAL_MASK		0x3FFF0000	// event identifier
#define	DBGOUT_SPECIAL(n)		(DBGOUT_SPECIAL_SET | (n << 16))
#define	DBGOUT_SPECIAL_ID(n)	((n & DBGOUT_SPECIAL_MASK) >> 16)

// syslog(3) severity flags; DBGOUT_SYSLOG_INFO is the default
#define	DBGOUT_SYSLOG_ERROR		(DBGOUT_SPECIAL(3) | DBGOUT_SYSLOG)
#define	DBGOUT_SYSLOG_WARN		(DBGOUT_SPECIAL(2) | DBGOUT_SYSLOG)
#define	DBGOUT_SYSLOG_WARNING	(DBGOUT_SYSLOG_WARN)
#define	DBGOUT_SYSLOG_NOTICE	(DBGOUT_SPECIAL(1) | DBGOUT_SYSLOG)
#define	DBGOUT_SYSLOG_INFO		(DBGOUT_SPECIAL(0) | DBGOUT_SYSLOG)

// application callback severity flags; DBGOUT_APP_INFO is the default
#define	DBGOUT_APP_ERROR		(DBGOUT_SPECIAL(3) | DBGOUT_APP)
#define	DBGOUT_APP_WARN			(DBGOUT_SPECIAL(2) | DBGOUT_APP)
#define	DBGOUT_APP_WARNING		(DBGOUT_APP_WARN)
#define	DBGOUT_APP_NOTICE		(DBGOUT_SPECIAL(1) | DBGOUT_APP)
#define	DBGOUT_APP_INFO			(DBGOUT_SPECIAL(0) | DBGOUT_APP)

// force stdout or stderr, not the file set with 'debug_set_output()'
#define	DBGOUT_STDOUT			(DBGOUT_SPECIAL(1) | DBGOUT_FILE)
#define	DBGOUT_STDERR			(DBGOUT_SPECIAL(2) | DBGOUT_FILE)

// special: strictly for debugging, as an argument for 'dbgxprintf()'
#define	DBGOUT_DEBUG			(DBGOUT_OUTPUTWIN | DBGOUT_OVERRIDE)

//
//	Debug categories
//

// socket communications
#define	DBGCAT_SOCKETIO			1
// the 'level' parameter for 'debug_set_level()' is a bitmask of one
//	or more of the following
#define	DBGSOCKETIO_IO		0x00000001
#define	DBGSOCKETIO_SECURE	0x00000002	

/*
**	Exported functions
*/

// Initialize and enable debugging
// Note that 'syslog(3)' is always initialized, so it is is always
//	available for 'dbgxprintf()'; logging of debug data, with 'dbgprintf()',
//	must be enabled by setting the flag DBGOUT_SYSLOG for 'debug_set_output()'.
// The parameter 'program_identifier' is used for the 'ident' argument for
//	'openlog(3)'.
int debug_init(const char *program_identifier);
void debug_deinit();

// Set or change debug output (default 'stderr')
// Parameter:
//	fname: file to use, or NULL when DBGOUT_FILE is not set in 'flags'
//		_or_ output is to go to 'stderr'
//	flags: combination of the DBGOUT flags
// Returns:
//	-1 on error, 0 when successful
int debug_set_output(const char *fname, unsigned int flags);

// Set application callback (or clear it, if the parameter is NULL)
// Returns the previous callback
// NB: the flag DBGOUT_APP must be set globally using 'debug_set_output()'
//	or it must be specified for 'dbgxprintf()'; the application callback
//	is NOT enabled automatically
typedef void (*debug_app_t)(int severity, const char *client_id, const char *msg);
debug_app_t debug_set_app(debug_app_t);

// debugging enabled?
int debug_enabled();

// Set client identifier (optional); pass NULL to clear
//	the string 'client_id' may optionally contain the format specifier
//	"%s", which will be replace with the current time (with microseconds)
//	in the format "yyyymmddhhmmss.uuuuuu" (using 'sprintf()', so do not
//	include any other format specifiers).
// the additional client identifier is concatenated to the existing
//	identifier; it must _not_ contain the format specifier "%s"
int debug_set_client_id(const char *client_id);
int debug_add_client_id(const char *additional_id);

// Debug logger, like printf
#ifdef _DEBUG
int dbgprintf(const char *fmt, ...);
#else
static int dbgprintf(const char *fmt, ...)
{
	return -1;
}
#endif

// 'dbgxprintf()' can be used to augment or override the default flags set
//	by 'debug_set_output()'
int dbgxprintf(unsigned int flags, const char *fmt, ...);
int dbgvxprintf(unsigned int flags, const char *fmt, va_list);

// dump bytes
int dbgdump(const char *data, int len);

// Configurable debug flags; see DBGCAT definitions above
int debug_set_level(int category, unsigned int level);
unsigned int debug_get_level(int category);

#endif	/* __DI_DEBUG_H */