/*********************************************************************************************************
* Software License Agreement (BSD License)                                                               *
* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
*													 *
* Copyright (c) 2008, WIDE Project and NICT								 *
* All rights reserved.											 *
* 													 *
* Redistribution and use of this software in source and binary forms, with or without modification, are  *
* permitted provided that the following conditions are met:						 *
* 													 *
* * Redistributions of source code must retain the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer.										 *
*    													 *
* * Redistributions in binary form must reproduce the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer in the documentation and/or other						 *
*   materials provided with the distribution.								 *
* 													 *
* * Neither the name of the WIDE Project or NICT nor the 						 *
*   names of its contributors may be used to endorse or 						 *
*   promote products derived from this software without 						 *
*   specific prior written permission of WIDE Project and 						 *
*   NICT.												 *
* 													 *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
*********************************************************************************************************/

/* This file contains the definitions of types and functions related to the log facility
 and that can be called by extensions. */
 
#ifndef _LOG_API_H
#define _LOG_API_H

#include <pthread.h>
#include <stddef.h>

/*
 ***************************************************************************
 *
 * Log API functions 
 *
 * These functions are used to report information to the user 
 * (debug, errors, ...)
 *
 ***************************************************************************
 */

#ifndef IN_EXTENSION

/*
 * FUNCTION:	log_error
 *
 * PARAMETERS:
 *  format 	: Same format string as in the printf function
 *  ...		: Same list as printf
 *
 * DESCRIPTION: 
 *  Log an error message to the user. Error conditions must be reported with this function.
 *
 * RETURN VALUE:
 *  None.
 */
void log_error ( char * format, ... );

/*
 * FUNCTION:	log_normal
 *
 * PARAMETERS:
 *  format 	: Same format string as in the printf function
 *  ...		: Same list as printf
 *
 * DESCRIPTION: 
 *  Log a message to the user. Warnings and informations are reported with this function
 *
 * RETURN VALUE:
 *  None.
 */
void log_normal ( char * format, ... );

/*
 * FUNCTION:	log_debug
 *
 * PARAMETERS:
 *  format 	: Same format string as in the printf function
 *  ...		: Same list as printf
 *
 * DESCRIPTION: 
 *  Log internal information for use of developpers only. 
 *
 * RETURN VALUE:
 *  None.
 */
void log_debug ( char * format, ... );

/*
 * FUNCTION:	log_time
 *
 * PARAMETERS:
 *  format 	: Same format string as in the printf function
 *  ...		: Same list as printf
 *
 * DESCRIPTION: 
 *  Log internal information for use of developpers only. 
 *
 * RETURN VALUE:
 *  None.
 */
char * log_time ( char * buf, size_t len );

/*
 * FUNCTION:	log_set_thread_name
 *
 * PARAMETERS:
 *  name 	: A name identifying the calling thread
 *  cat		: Optional categorization. Should for example contain the extension name.
 *
 * DESCRIPTION: 
 *  Get a string describing current time
 *
 * RETURN VALUE:
 *  None.
 */
void log_set_thread_name ( char * name, char * cat );

/* The name of the current thread */
extern pthread_key_t thread_name;


#endif /* ! IN_EXTENSION */

/* The version of this API, to check binary compatibility -- increment each time a change is made in api_log_t */
#define WAAAD_API_LOG_VER	2

/* Now define the type of the structure that contains the callback to pass to extensions */
typedef struct {
	/* The header is common to all sub-API pieces */
	size_t	length;		/* The size of this structure, may be useful for extensions not using the log facility */
	int	version;	/* The version of this API/ABI, must be WAAAD_API_LOG_VER */
	
	/* the remaining is log-specific */
	void  (*log_error)  ( char * format, ... );
	void  (*log_normal) ( char * format, ... );
	void  (*log_debug)  ( char * format, ... );
	char *(*log_time)   ( char * buf, size_t len );
	void  (*log_set_thread_name) (char * name, char * cat);
	pthread_key_t (*thread_name);
} api_log_t;

#ifdef IN_EXTENSION

/* From within the extensions, we register callbacks in the following global structure */
#ifdef DECLARE_API_POINTERS
api_log_t * g_api_log=NULL;
#else /* DECLARE_API_POINTERS */
extern api_log_t * g_api_log;
#endif /* DECLARE_API_POINTERS */

/* These defines allow to call functions from extension in the same way as in waaad */
#define log_error	g_api_log->log_error
#define log_normal	g_api_log->log_normal
#define log_debug	g_api_log->log_debug
#define log_time	g_api_log->log_time
#define log_set_thread_name	g_api_log->log_set_thread_name
#define thread_name	*g_api_log->thread_name


#else /* IN_EXTENSION */

/* From the daemon, we must initialize the API object, in extension.c */
# define MY_WAAAD_API_LOG_VER 2
# if MY_WAAAD_API_LOG_VER != WAAAD_API_LOG_VER
#  error "You must update API_INIT_LOG also"
# endif

#define API_INIT_LOG( api_log ) 				\
{								\
	(api_log).length      = sizeof(api_log_t);		\
	(api_log).version     = WAAAD_API_LOG_VER;		\
	(api_log).log_error   = log_error;			\
	(api_log).log_normal  = log_normal;			\
	(api_log).log_debug   = log_debug;			\
	(api_log).log_time    = log_time;			\
	(api_log).log_set_thread_name  = log_set_thread_name;	\
	(api_log).thread_name = &thread_name;			\
}							

#endif /* IN_EXTENSION */

/************************/
/* Some macro for debug */
/************************/
#ifdef DEFINE_DEBUG_MACRO

/* helpers */
#define __str( arg )  #arg
#define _stringize( arg ) __str( arg )
#define __agr( arg1, arg2 ) arg1 ## arg2
#define _aggregate( arg1, arg2 ) __agr( arg1, arg2 )

/* Macro to set the current thread name, useful for multi-threaded environments */
#define THREAD_NAME( name )		\
	log_set_thread_name( (name), _stringize(DEFINE_DEBUG_MACRO) );

/* Boolean for tracing at a certain level, for custom dump functions for example */
#define TRACE_BOOL(level) ( level <= local_debug_level + _aggregate(DEFINE_DEBUG_MACRO, _verbosity) )

/* The general debug macro, each call results in two lines of debug messages */
#define TRACE_DEBUG(level,format,args... ) {										\
	if ( TRACE_BOOL(level) ) {											\
		char __buf[25];												\
		char * __thn = ((char *)pthread_getspecific(thread_name) ?: "unnamed");					\
		log_debug("\t |%-30s\t%s\tin %s@%s:%d\n"								\
				"\t%s|%*s" format "\n",  								\
						__thn, log_time(__buf, sizeof(__buf)), __FUNCTION__, __FILE__, __LINE__,\
						(level < FULL)?"@":" ",level, "", ## args); 				\
	}														\
}

/* Helper for function entry */
#define TRACE_ENTRY(_format,_args... ) \
	TRACE_DEBUG(FCTS, "->%s (" #_args ") = (" _format ") >", __FUNCTION__, ##_args );

/* Helper for debugging by adding traces */
#define TRACE_HERE()	\
	TRACE_DEBUG(INFO, " -- debug checkpoint -- ");

/* levels definitions */
#define NONE 0	/* Display no debug message */
#define INFO 1	/* Display errors only */
#define FULL 2  /* Display additional information to follow code execution */
#define ANNOYING 4 /* Very verbose, for example in loops */
#define FCTS 6  /* Display entry parameters of most functions */
#define CALL 9  /* Display calls to most functions (with CHECK macros) */

/* Default level is INFO */
#ifndef TRACE_LEVEL 
#define TRACE_LEVEL INFO
#endif /* TRACE_LEVEL */

/* The level of the file being compiled */
static int local_debug_level = TRACE_LEVEL;
/* We use an run-time variable to be able to change the level on-the-fly with a debugger */

#endif /* DEFINE_DEBUG_MACRO */


#endif /* ! _LOG_API_H */