You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
215 lines
9.1 KiB
215 lines
9.1 KiB
/* /////////////////////////////////////////////////////////////////////////
|
|
* 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 //////////////////////////// */
|