|
|
/* /////////////////////////////////////////////////////////////////////////
* File: pantheios/frontend.h * * Purpose: Pantheios front end API * * Created: 21st June 2005 * Updated: 7th August 2012 * * Home: http://www.pantheios.org/
* * Copyright (c) 2005-2012, Matthew Wilson and Synesis Software * Copyright (c) 1999-2005, Synesis Software and Matthew Wilson * All rights reserved. * * Redistribution and use 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(s) of Matthew Wilson and Synesis Software nor the * names of any contributors may be used to endorse or promote products * derived from this software without specific prior written permission. * * 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. * * ////////////////////////////////////////////////////////////////////// */
/** \file pantheios/frontend.h
* * [C, C++] Definition of the \ref group__frontend. */
#ifndef PANTHEIOS_INCL_PANTHEIOS_H_FRONTEND
#define PANTHEIOS_INCL_PANTHEIOS_H_FRONTEND
/* /////////////////////////////////////////////////////////////////////////
* Version information */
#ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
# define PANTHEIOS_VER_PANTHEIOS_H_FRONTEND_MAJOR 3
# define PANTHEIOS_VER_PANTHEIOS_H_FRONTEND_MINOR 2
# define PANTHEIOS_VER_PANTHEIOS_H_FRONTEND_REVISION 1
# define PANTHEIOS_VER_PANTHEIOS_H_FRONTEND_EDIT 20
#endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
/* /////////////////////////////////////////////////////////////////////////
* Includes */
#ifndef PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS
# include <pantheios/pantheios.h>
#endif /* !PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS */
/* /////////////////////////////////////////////////////////////////////////
* Front-end API */
/** \defgroup group__frontend Pantheios Front-end API
* * 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. \c "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 \c backEndId is 0, then the question is whether any logging * should occur for the given severity level. If \c backEndId is 1, then the * question is whether logging should occur for the local back-end. If * \c backEndId is 2, then the question is whether logging should occur for * the remote back-end. * * @{ */
/** Initialises the front-end API.
* * \param reserved Currently reserved. Will be NULL in the current version * of the Pantheios library * \param 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 * <code>*ptoken</code>, and it will be passed back to the other functions. * * \note This function is called at most once per process. * * \return A status indicating whether the front-end is initialised, and * therefore whether the Pantheios library as a whole is initialised. * \retval <0 Initialisation failed. * \retval >=0 Initialisation succeeded */PANTHEIOS_CALL(int) pantheios_fe_init( void* reserved, void** ptoken);
/** Uninitialises the front-end API.
* * This function must be defined by each front-end implementation. It * uninitialises the front-end. * * \param token The front-end token, created by the pantheios_fe_init() * function. * * \note This function is called at most once per process. */PANTHEIOS_CALL(void) pantheios_fe_uninit(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. * * \param 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. * * \return A pointer to a nul-terminated C-style string containing the * process identity. May not be \c NULL, except on the first invocation, * which is an indication to the Pantheios core library (and congnisant * custom back-ends; no stock back-ends use his behaviour) that the * front-end may provide changing process identity at different times and * that multiple calls are supported (and, presumably, desired). The * maximum length of the returned string is 1000 characters. * * \note When the first invocation returns \c NULL, to denote that a dynamic * process identity, the second invocation (which must * <strong>not</strong> return \c NULL) will be called on the same thread, * and at a time when no other (Pantheios-related) threads will call it, * enabling implementations to use simple static flag variables to handle * their switching logic (should they so wish). * * \note When the first invocation returns non-<code>NULL</code>, to denote * a "classic" non-dynamic process identity, then the function is called * at most once during successful * initialisation, but in the case where initialisation fails it may be * called additional times by the bail out handler * (\link pantheios::util::pantheios_onBailOut4 pantheios_onBailOut4()\endlink). * It may also be called if the application, or the front-end or * back-end(s) invoke the bail out handler at any other time. */PANTHEIOS_CALL(PAN_CHAR_T const*) pantheios_fe_getProcessIdentity(void* token);
/** 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 \c severity, * any/all logging is enabled (\c backEndId == 0), or whether local * (\c backEndId == 1) or remote (\c 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 * * \param token The front-end token, created by the pantheios_fe_init() * function. * \param severity The severity level * \param 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. * * \return A status indicating whether the given severity level is being * logged. * \retval non-0 Severity is being logged. * \retval 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. */PANTHEIOS_CALL(int) pantheios_fe_isSeverityLogged( void* token, int severity, int backEndId);
/** @} // group__frontend */
/* ////////////////////////////////////////////////////////////////////// */
#endif /* !PANTHEIOS_INCL_PANTHEIOS_H_FRONTEND */
/* ///////////////////////////// end of file //////////////////////////// */
|
