Pantheios Back-end API

Detailed Description

The Pantheios back-end API describes the required functionality of a back-end library. The back-end is responsible solely for translating the log entry - severity indicator + length-specified, nul-terminated string - into output, as appropriate to its implementation.

There are several stock back-ends supplied with the Pantheios distribution (http://pantheios.org/), providing logging to stderr (using fprintf()), SysLog (using UNIX syslog(), or KiwiSysLog's KLOG on Win32), Win32 Debugger, ACE output. You may also supply your own back-end by implementing the three simple functions of the API: pantheios_be_init(), pantheios_be_uninit(), and pantheios_be_logEntry().


Modules

 Pantheios Stock Back-ends
 Pre-built back-ends supplied with the Pantheios library.
 Pantheios Stock Back-end Ids
 Stock back-end identifiers used by the Pantheios back-end libraries.

Functions

int pantheios_be_init (char const *processIdentity, void *reserved, void **ptoken)
 Initialises the back-end API.
void pantheios_be_uninit (void *token)
 Uninitialises the back-end API.
int pantheios_be_logEntry (void *feToken, void *beToken, int severity, char const *entry, size_t cchEntry)
 Passes a log-entry to the back-end API.

Function Documentation

int pantheios_be_init (  char const *  processIdentity,
void *  reserved,
void **  ptoken
) 
 

Initialises the back-end API.

This function is called once by the Pantheios core library to initialise the back-end library. It passes the process identity (in the form of a nul-terminated C-style string) and a second parameter (reserved for future use; currently always has value 0), which the back-end may use in its initialisation. The third parameter is a pointer to a void*, with which the back-end may store state, to be passed back to it in the pantheios_be_logEntry() and pantheios_be_uninit() functions.

Parameters:
processIdentity The identity of the process within which Pantheios is being used. Should be a meaningful human-readable string. Must not be NULL. Maximum length is limited solely by what the back-end library can accomodate. The string pointed to by this parameter may not persist after the call is complete, so the back-end should take a copy if required.
reserved Currently reserved. Will contain 0 in the current version of the Pantheios library
ptoken Pointer to a variable to receive the back-end token, which will be stored in the Pantheios library and passed to the pantheios_be_logEntry() and pantheios_be_uninit() functions
Note:
This function must be defined by each back-end implementation

This function is called at most once per process.

Returns:
A status indicating whether the back-end is initialised, and therefore whether the Pantheios library as a whole is initialised.
Return values:
<0 Initialisation failed.
>=0 Initialisation succeeded
Examples:
cpp/example_cpp_custom_severity_levels/example_cpp_custom_severity_levels.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

int pantheios_be_logEntry (  void *  feToken,
void *  beToken,
int  severity,
char const *  entry,
size_t  cchEntry
) 
 

Passes a log-entry to the back-end API.

This function is called by the Panthieos core library to emit a log entry. It is passed five parameters. The severity, entry and cchEntry parameters describe the severity level, and the nul-terminated contents of the log entry. The feToken and beToken parameters hold the library-specific state of the front-end and back-end librarys, respectively.

Note:
This function must be defined by each back-end implementation

This may be called from any thread in a multi-threaded process.

Parameters:
feToken The front-end token, created by the pantheios_fe_init() function. This value does not hold any meaning to the back-end library, and may be used only to passed back to the front-end in calls to pantheios_fe_isSeverityLogged().
beToken The back-end token, created by the pantheios_be_init() function
severity The severity level.
entry The nul-terminated string containing the entry information
cchEntry The number of bytes in the string, not including the nul-terminating character
Examples:
cpp/example_cpp_custom_severity_levels/example_cpp_custom_severity_levels.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

void pantheios_be_uninit (  void *  token  ) 
 

Uninitialises the back-end API.

This function is called to uninitialise the back-end library during the uninitialisation of the Pantheios core library. It is passed the value of the token stored on its behalf by the Pantheios core library.

Note:
This function must be defined by each back-end implementation

This function is called at most once per process.

Parameters:
token The back-end token, created by the pantheios_be_init() function
Examples:
cpp/example_cpp_custom_severity_levels/example_cpp_custom_severity_levels.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.
pantheios Library documentation © Matthew Wilson, 2006 SourceForge.net Logo