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.
169 lines
6.6 KiB
169 lines
6.6 KiB
/* /////////////////////////////////////////////////////////////////////////
|
|
* File: pantheios/frontends/stock.h
|
|
*
|
|
* Purpose: Declaration of the Pantheios Stock Front-end API Common
|
|
* Elements.
|
|
*
|
|
* Created: 23rd November 2007
|
|
* Updated: 6th August 2012
|
|
*
|
|
* Home: http://www.pantheios.org/
|
|
*
|
|
* Copyright (c) 2007-2012, Matthew Wilson and Synesis Software
|
|
* 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/frontends/stock.h
|
|
*
|
|
* [C, C++] Declaration of the Pantheios Stock Front-end API Common
|
|
* Elements.
|
|
*/
|
|
|
|
#ifndef PANTHEIOS_INCL_PANTHEIOS_FRONTENDS_H_STOCK
|
|
#define PANTHEIOS_INCL_PANTHEIOS_FRONTENDS_H_STOCK
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Version information
|
|
*/
|
|
|
|
#ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
|
|
# define PANTHEIOS_VER_PANTHEIOS_FRONTENDS_H_STOCK_MAJOR 1
|
|
# define PANTHEIOS_VER_PANTHEIOS_FRONTENDS_H_STOCK_MINOR 2
|
|
# define PANTHEIOS_VER_PANTHEIOS_FRONTENDS_H_STOCK_REVISION 2
|
|
# define PANTHEIOS_VER_PANTHEIOS_FRONTENDS_H_STOCK_EDIT 13
|
|
#endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Includes
|
|
*/
|
|
|
|
#ifndef PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS
|
|
# include <pantheios/pantheios.h>
|
|
#endif /* !PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS */
|
|
#ifndef PANTHEIOS_INCL_PANTHEIOS_H_FRONTEND
|
|
# include <pantheios/frontend.h>
|
|
#endif /* !PANTHEIOS_INCL_PANTHEIOS_H_FRONTEND */
|
|
|
|
/** \defgroup group__frontend__stock_frontends Pantheios Stock Front-ends
|
|
* \ingroup group__frontend Pantheios
|
|
* Pre-built front-ends supplied with the Pantheios library
|
|
*
|
|
* Pantheios comes with several pre-written stock front-end libraries, which
|
|
* cover most common needs for diagnostic logging. They also serve as good
|
|
* examples of how to write a custom front-end.
|
|
*/
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Compiler compatibility
|
|
*/
|
|
|
|
#if defined(__DMC__) && \
|
|
__DMC__ < 0x0850
|
|
/* Previous versions of Digital Mars compiler/linker did not operate
|
|
* correctly with declaration of extern const char [].
|
|
*/
|
|
# error Not compatible with Digital Mars C/C++ prior to version 8.50. Download the latest free version at www.digitalmars.com
|
|
#endif /* compiler */
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* External Declarations
|
|
*/
|
|
|
|
/** The application must define this variable, to contain the
|
|
* application name/identity.
|
|
*
|
|
* \ingroup group__frontend__stock_frontends
|
|
*
|
|
* The variable is an immutable array of <code>PAN_CHAR_T</code> (i.e.
|
|
* <code>char</code> in multibyte string builds, <code>wchar_t</code> in
|
|
* wide string builds) whose name is non-mangled and has external linkage.
|
|
*
|
|
* Therefore, when defining within a C++ compilation unit it must be
|
|
* declared <code>extern "C"</code>; when defined within a C compilation
|
|
* unit it must be extern (optionally declared <code>extern</code>; it
|
|
* must not be declared <code>static</code>).
|
|
*
|
|
* Examples:
|
|
\htmlonly
|
|
<pre>
|
|
// C: multibyte string build
|
|
char const PANTHEIOS_FE_PROCESS_IDENTITY[] = "my.app";
|
|
|
|
// C++: wide string build
|
|
extern "C" wchar_t const PANTHEIOS_FE_PROCESS_IDENTITY[] = L"my.app";
|
|
</pre>
|
|
\endhtmlonly
|
|
*
|
|
* For convenience, the constructs PANTHEIOS_EXTERN_C, PAN_CHAR_T, and
|
|
* PANTHEIOS_LITERAL_STRING() may be employed to write the variable
|
|
* definition in a manner independent of language and/or character encoding,
|
|
* as in:
|
|
\htmlonly
|
|
<pre>
|
|
/\* C or C++; multibyte or wide string build \*\/
|
|
PANTHEIOS_EXTERN_C PAN_CHAR_T const PANTHEIOS_FE_PROCESS_IDENTITY[] = PANTHEIOS_LITERAL_STRING("my.app");
|
|
|
|
</pre>
|
|
\endhtmlonly
|
|
*
|
|
* \note The process identity must not contain any whitespace characters,
|
|
* otherwise Pantheios library initialisation will fail.
|
|
*
|
|
* \warn If you define the variable as a pointer
|
|
* (<code>PAN_CHAR_T const*</code>) the behaviour of the link unit is
|
|
* undefined.
|
|
*/
|
|
PANTHEIOS_EXTERN_C PAN_CHAR_T const PANTHEIOS_FE_PROCESS_IDENTITY[];
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Application-defined functions
|
|
*/
|
|
|
|
/** \ref page__frontend__callbacks "Callback" function defined by the
|
|
* application, invoked during API initialisation.
|
|
*
|
|
* \ingroup group__frontend__stock_frontends
|
|
*
|
|
* \note This function is only required when the
|
|
* \ref page__frontend__callbacks "callback" version of the front-end
|
|
* library is used.
|
|
*
|
|
* \note This function *MUST NOT* throw an exception, and *MUST NOT* return
|
|
* <code>NULL</code>. If the implementation fails to acquire/produce the
|
|
* identity, it must call <code>pantheios_exitProcess(1)</code>. It may
|
|
* optionally call <code>pantheios_util_onBailOut4()</code> first.
|
|
*/
|
|
PANTHEIOS_CALL(PAN_CHAR_T const*) pantheios_fe_getAppProcessIdentity(void) /* throw() */;
|
|
|
|
/* ////////////////////////////////////////////////////////////////////// */
|
|
|
|
#endif /* PANTHEIOS_INCL_PANTHEIOS_FRONTENDS_H_STOCK */
|
|
|
|
/* ///////////////////////////// end of file //////////////////////////// */
|