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.


Modules
	Pantheios Stock Front-ends
	Pre-built front-ends supplied with the Pantheios library.
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.
PAN_CHAR_T 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

PAN_CHAR_T 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, except in the case where initialisation fails, in which case it may be called by the bail out handler (pantheios_onBailOut4()). It will also be called if the application, or the front-end or back-end(s) invoke pantheios_onBailOut4() at any other time.

Examples:: cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.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/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.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/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.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/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.cpp.

Pantheios Front-end API

Detailed Description

Modules

Functions

Function Documentation


pantheios Library documentation � Matthew Wilson & Synesis Software, 2006-2011