Pantheios Front-end API

Detailed Description

The Pantheios front-end API describes the required functionality of a front-end library. The front-end is responsible solely for providing process identity information and arbitrating logging requests, based on severity level (and local/remote destination).

Process identity is defined by the front-end according to the return-value of pantheios_fe_getProcessIdentity(), which should return a nul-terminated C-style string representing the host process, e.g. "MyDaemon"

Filtering is carried out by pantheios_fe_isSeverityLogged(), which receives three parameters: the front-end state, the log entry severity level, and a back-end identifier. The back-end identifier value represents one of three 'questions' that are to be asked of the front-end. If backEndId is 0, then the question is whether any logging should occur for the given severity level. If backEndId is 1, then the question is whether logging should occur for the local back-end. If backEndId is 2, then the question is whether logging should occur for the remote back-end.


Functions

int pantheios_fe_init (void *reserved, void **ptoken)
 Initialises the front-end API.
void pantheios_fe_uninit (void *token)
 Uninitialises the front-end API.
char const * pantheios_fe_getProcessIdentity (void *token)
 Defines the process identity.
int pantheios_fe_isSeverityLogged (void *token, int severity, int backEndId)
 Determines whether a given severity is being logged.

Function Documentation

char const* pantheios_fe_getProcessIdentity (  void *  token  ) 
 

Defines the process identity.

This function must be defined by each front-end implementation. It defines the name of the process, that may be used in the emission of log statements by back-ends.

Parameters:
token The front-end token, created by the pantheios_fe_init() function.There is no strict maximum length as far as Pantheios is concerned, but it should not exceed the limitation provided by the implementing back-end library.
Returns:
A pointer to a nul-terminated C-style string containing the process identity. May not be NULL.
Note:
This function is called at most once per process.
Examples:
cpp/example_cpp_custom_fe/example_cpp_custom_fe.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

int pantheios_fe_init (  void *  reserved,
void **  ptoken
) 
 

Initialises the front-end API.

Parameters:
reserved Currently reserved. Will be NULL in the current version of the Pantheios library
ptoken Pointer to a variable to receive the front-end token, which will be stored in the Pantheios library and passed to the pantheios_fe_getProcessIdentity(), pantheios_fe_isSeverityLogged() and pantheios_fe_uninit() functions.
This function must be defined by each front-end implementation. It initialises the front-end. If the implementation requires any context, e.g. a front-end class instance, this can be allocated and placed into *ptoken, and it will be passed back to the other functions.

Note:
This function is called at most once per process.
Returns:
A status indicating whether the front-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_fe/example_cpp_custom_fe.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

int pantheios_fe_isSeverityLogged (  void *  token,
int  severity,
int  backEndId
) 
 

Determines whether a given severity is being logged.

This function must be defined by each front-end implementation. It is called by the Pantheios core library and, optionally, a back-end library, to determine whether, for the given severity, any/all logging is enabled (backEndId == 0), or whether local (backEndId == 1) or remote (backEndId == 2) logging is enabled. It is passed the token returned in pantheios_fe_init(), which the front-end implementation may use to access its state

Parameters:
token The front-end token, created by the pantheios_fe_init() function.
severity The severity level
backEndId A front-end+back-end specific parameter. This is used to enable a back-end, such as the be.lrsplit library, to simultaneously provide multiple actual back-ends and query the front-end for their respective. The value 0 is used within the Pantheios library and stands for every back-end. All other values indicate specific back-end splits, although by convention 1 indicates local logging and 2 indicates remote logging.
Returns:
A status indicating whether the given severity level is being logged.
Return values:
non-0 Severity is being logged.
0 Severity is not being logged.
Note:
This may be called from any thread in a multi-threaded process, and so it must be safely callable by multiple threads concurrently.
Examples:
cpp/example_cpp_custom_fe/example_cpp_custom_fe.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

void pantheios_fe_uninit (  void *  token  ) 
 

Uninitialises the front-end API.

This function must be defined by each front-end implementation. It uninitialises the front-end.

Parameters:
token The front-end token, created by the pantheios_fe_init() function.
Note:
This function is called at most once per process.
Examples:
cpp/example_cpp_custom_fe/example_cpp_custom_fe.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