PLogger API functions


Detailed Description

Logging API.

Must call pmemInit() before using this module.

The logging API is composed of a Logger. A Logger is an object who implements an API to actually write log messages. The logging API uses the logger when logging is to be performed but does not depend on an actual implementation of this API.

When a request for logging is performed, the current level of the logging API is compared with the current stack-trace level. If the logger's log level is greater than or equal to the stack-trace level, then the message is being logged through the use of the Logger. Otherwise, the message is not logged. Setting the log level of the API to UINT_MAX is equivalent to unconditionally log all messages from all modules. Conversely, setting the log level of the API to 0 is equivalent to disabling logging globally.


Data Structures

struct  PLogger

Defines

#define LOG_OUTPUT_FORMAT_NONE   0x0000
#define LOG_OUTPUT_FORMAT_DATE_TIME   0x0001
#define LOG_OUTPUT_FORMAT_THREAD_ID   0x0002
#define LOG_OUTPUT_FORMAT_MODULE_NAME   0x0004
#define CHKLOG(rc, function)   do { rc = (function); if (rc != ESR_SUCCESS) { PLogError("%s in %s:%d", ESR_rc2str(rc), __FILE__, __LINE__); goto CLEANUP; } } while (0)
#define PLOG_CHKRC_ARGS(rc, function, args)   do { if((rc = (function args)) != ESR_SUCCESS) { PLogError(ESR_rc2str(rc)); return rc; } } while (0)
#define PLOG_CHKRC(rc, function)   do { rc = (function); if (rc != ESR_SUCCESS) { PLogError(rc); return rc; } } while (0)

Typedefs

typedef asr_uint16_t LOG_OUTPUT_FORMAT

Functions

PORTABLE_API
ESR_ReturnCode 
PLogInit (PLogger *logger, unsigned int logLevel)
PORTABLE_API
ESR_ReturnCode 
PLogIsInitialized (ESR_BOOL *isInit)
PORTABLE_API
ESR_ReturnCode 
PLogIsLocked (ESR_BOOL *isLocked)
PORTABLE_API
ESR_ReturnCode 
PLogShutdown (void)
PORTABLE_API
ESR_ReturnCode 
PLogSetFormat (LOG_OUTPUT_FORMAT format)
PORTABLE_API
ESR_ReturnCode 
PLogGetLevel (unsigned int *logLevel)
PORTABLE_API
ESR_ReturnCode 
PLogSetLevel (unsigned int logLevel)
PORTABLE_API
ESR_ReturnCode 
PLogMessage (const LCHAR *msg,...)
PORTABLE_API
ESR_ReturnCode 
PLogError (const LCHAR *msg,...)
PORTABLE_API
ESR_ReturnCode 
PLogCreateFileLogger (PFile *file, PLogger **logger)
PORTABLE_API
ESR_ReturnCode 
PLogCreateCircularFileLogger (const LCHAR *filename, unsigned int maxsize, PLogger **logger)


Define Documentation

#define CHKLOG ( rc,
function   )     do { rc = (function); if (rc != ESR_SUCCESS) { PLogError("%s in %s:%d", ESR_rc2str(rc), __FILE__, __LINE__); goto CLEANUP; } } while (0)

Runs a function, checks its return-code. In case of an error, logs it and jumps to the CLEANUP label.

#define LOG_OUTPUT_FORMAT_DATE_TIME   0x0001

Specifies that the date and time is to be output.

#define LOG_OUTPUT_FORMAT_MODULE_NAME   0x0004

Specifies that the module name of the module generating the message is to be output.

#define LOG_OUTPUT_FORMAT_NONE   0x0000

Specifies that no extra information is to be output.

#define LOG_OUTPUT_FORMAT_THREAD_ID   0x0002

Specifies that thread id of thread generating the message is to be output.

#define PLOG_CHKRC ( rc,
function   )     do { rc = (function); if (rc != ESR_SUCCESS) { PLogError(rc); return rc; } } while (0)

Checks the function return-code and if it is not ESR_SUCCESS, logs and returns it.

#define PLOG_CHKRC_ARGS ( rc,
function,
args   )     do { if((rc = (function args)) != ESR_SUCCESS) { PLogError(ESR_rc2str(rc)); return rc; } } while (0)

Invokes the function with args and if it is not ESR_SUCCESS, logs and returns it.

Parameters:
rc Used to store the function return value
function Function name
args Function arguments


Typedef Documentation

typedef asr_uint16_t LOG_OUTPUT_FORMAT

Type used to control output format.


Function Documentation

PORTABLE_API ESR_ReturnCode PLogCreateCircularFileLogger ( const LCHAR filename,
unsigned int  maxsize,
PLogger **  logger 
)

Creates a logger that logs to a circular file.

Parameters:
filename The name of the file to be created.
maxsize The maximum number of bytes that the file may have.
logger logger handle receiving the created logger.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error.

PORTABLE_API ESR_ReturnCode PLogCreateFileLogger ( PFile file,
PLogger **  logger 
)

Creates a logger that logs to a file.

Parameters:
file The file to log to.
logger logger handle receiving the created logger.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error.

PORTABLE_API ESR_ReturnCode PLogError ( const LCHAR msg,
  ... 
)

Unconditionally logs an error message.

Parameters:
msg The message format specification (ala printf).
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if the API is not initialized.

PORTABLE_API ESR_ReturnCode PLogGetLevel ( unsigned int *  logLevel  ) 

Gets the current log level of the LOG API.

Parameters:
logLevel A pointer to where the log level is to be stored. If NULL, the function returns ESR_INVALID_ARGUMENT.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if the API is not initialized.

PORTABLE_API ESR_ReturnCode PLogInit ( PLogger logger,
unsigned int  logLevel 
)

Initializes the LOG library. This function must be called before any logging can take place. PtrdInit() must be called before this function on platforms that support threads.

Parameters:
logger The logger to be used to output the messages. If NULL, then logging goes to PSTDERR.
logLevel The level of logging requested.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if already initialized.

PORTABLE_API ESR_ReturnCode PLogIsInitialized ( ESR_BOOL *  isInit  ) 

Indicates if PLog module is initialized.

Parameters:
isInit True if module is initialized
Returns:
ESR_INVALID_ARGUMENT if isLocked is null

PORTABLE_API ESR_ReturnCode PLogIsLocked ( ESR_BOOL *  isLocked  ) 

Indicates if PLog module is locked inside a critical section. This is for internal use only.

Parameters:
isLocked True if module is locked
Returns:
ESR_INVALID_ARGUMENT if isLocked is null

PORTABLE_API ESR_ReturnCode PLogMessage ( const LCHAR msg,
  ... 
)

Conditionally Logs a message. The message is logged only if module is enabled.

Parameters:
msg The message format specification (ala printf).
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if the API is not initialized.

PORTABLE_API ESR_ReturnCode PLogSetFormat ( LOG_OUTPUT_FORMAT  format  ) 

Sets the format of the logging messages. If this function is never called, the default format is

LOG_OUTPUT_FORMAT_MODULE_NAME | LOG_OUTPUT_FORMAT_DATE_TIME.

Parameters:
format the format specification for new messages.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error.

PORTABLE_API ESR_ReturnCode PLogSetLevel ( unsigned int  logLevel  ) 

Sets the current log level of the LOG API.

Parameters:
logLevel The new log level.
Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if the API is not initialized.

PORTABLE_API ESR_ReturnCode PLogShutdown ( void   ) 

Shutdowns the LOG library. Once this function is called, no logging activity can be performed.

Returns:
ESR_SUCCESS if success, otherwise a status code indicating the nature of the error. In particular, it returns ESR_INVALID_STATE if not initialized or already shutted down.


Generated on Thu May 1 15:37:26 2008 for SREC by  doxygen 1.5.3