Pantheios - 'The C++ Logging Sweetspot': include/pantheios/pantheios.h Source File

00001 /* /////////////////////////////////////////////////////////////////////////
00002  * File:        pantheios/pantheios.h
00003  *
00004  * Purpose:     Pantheios Core API.
00005  *
00006  * Created:     21st June 2005
00007  * Updated:     2nd September 2006
00008  *
00009  * Author:      Matthew Wilson
00010  *
00011  * Home:        http://www.pantheios.org/
00012  *
00013  * Copyright:   Matthew Wilson and Synesis Software Pty Ltd, 1999-2005.
00014  *              Matthew Wilson, 2005-2006.
00015  *
00016  * Redistribution and use in source and binary forms, with or without
00017  * modification, are permitted provided that the following conditions are met:
00018  *
00019  * - Redistributions of source code must retain the above copyright notice, this
00020  *   list of conditions and the following disclaimer.
00021  * - Redistributions in binary form must reproduce the above copyright notice,
00022  *   this list of conditions and the following disclaimer in the documentation
00023  *   and/or other materials provided with the distribution.
00024  * - Neither the names of Matthew Wilson and Synesis Software nor the names of
00025  *   any contributors may be used to endorse or promote products derived from
00026  *   this software without specific prior written permission.
00027  *
00028  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00029  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00030  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00031  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00032  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00033  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00034  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00035  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00036  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00037  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00038  * POSSIBILITY OF SUCH DAMAGE.
00039  *
00040  * ////////////////////////////////////////////////////////////////////// */
00041 
00042 
00048 #ifndef PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS
00049 #define PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS
00050 
00051 /* /////////////////////////////////////////////////////////////////////////
00052  * Version information
00053  */
00054 
00055 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00056 # define PANTHEIOS_VER_PANTHEIOS_H_PANTHEIOS_MAJOR      3
00057 # define PANTHEIOS_VER_PANTHEIOS_H_PANTHEIOS_MINOR      0
00058 # define PANTHEIOS_VER_PANTHEIOS_H_PANTHEIOS_REVISION   5
00059 # define PANTHEIOS_VER_PANTHEIOS_H_PANTHEIOS_EDIT       128
00060 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00061 
00078 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00079 # define PANTHEIOS_VER_1_0_1_B2                 0x01000102
00080 # define PANTHEIOS_VER_1_0_1                    0x010001ff
00081 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00082 
00083 #define PANTHEIOS_VER_MAJOR                     1
00084 #define PANTHEIOS_VER_MINOR                     0
00085 #define PANTHEIOS_VER_REVISION                  1
00086 
00087 #define PANTHEIOS_VER                           PANTHEIOS_VER_1_0_1_B2
00088 
00089 /* /////////////////////////////////////////////////////////////////////////
00090  * Includes
00091  */
00092 
00093 /* Pantheios core API relies on STLSoft for compiler/library discrimination,
00094  * and various fundamental types.
00095  */
00096 #include <stlsoft/stlsoft.h>
00097 
00098 #include <stdarg.h>     /* for va_list */
00099 #include <stddef.h>     /* for size_t */
00100 
00101 /* /////////////////////////////////////////////////////////////////////////
00102  * Namespace
00103  */
00104 
00105 #if !defined(__cplusplus) && \
00106     !defined(PANTHEIOS_DOCUMENTATION_SKIP_SECTION) && \
00107     !defined(PANTHEIOS_NO_NAMESPACE)
00108 # define PANTHEIOS_NO_NAMESPACE
00109 #endif /* __cplusplus, etc. */
00110 
00111 #if !defined(PANTHEIOS_NO_NAMESPACE)
00112 
00117 namespace pantheios
00118 {
00119 #endif /* !PANTHEIOS_NO_NAMESPACE */
00120 
00121 /* /////////////////////////////////////////////////////////////////////////
00122  * Macros and definitions
00123  */
00124 
00125 #if !defined(PANTHEIOS_DECLSPEC)
00126 # define PANTHEIOS_DECLSPEC
00127 #endif /* !PANTHEIOS_DECLSPEC */
00128 
00129 #if defined(__cplusplus) || \
00130     defined(PANTHEIOS_DOCUMENTATION_SKIP_SECTION)
00131 # define PANTHEIOS_EXTERN_C            extern "C"
00132 #else /* ? __cplusplus */
00133 # define PANTHEIOS_EXTERN_C            extern
00134 #endif /* !__cplusplus */
00135 
00136 #if !defined(PANTHEIOS_CALLCONV)
00137 # define PANTHEIOS_CALLCONV
00138 #endif /* !PANTHEIOS_CALLCONV */
00139 
00140 #define PANTHEIOS_CALL(rt)             PANTHEIOS_DECLSPEC PANTHEIOS_EXTERN_C rt PANTHEIOS_CALLCONV
00141 
00142 /* /////////////////////////////////////////////////////////////////////////
00143  * Types
00144  */
00145 
00146 /* Basic types */
00147 
00149 typedef stlsoft_ns_qual(ss_uint8_t)     pan_uint8_t;
00151 typedef stlsoft_ns_qual(ss_uint16_t)    pan_uint16_t;
00153 typedef stlsoft_ns_qual(ss_uint32_t)    pan_uint32_t;
00155 typedef stlsoft_ns_qual(ss_uint64_t)    pan_uint64_t;
00156 
00157 
00169 struct pan_slice_t
00170 {
00171     size_t      len;    
00172     char const  *ptr;   
00174 #ifdef __cplusplus
00175 
00176     pan_slice_t();
00178     pan_slice_t(char const *p, size_t l);
00180     pan_slice_t(pan_slice_t const &rhs);
00182     pan_slice_t &operator =(pan_slice_t const &rhs);
00183 
00184 # ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00185 
00186     pan_slice_t(int len, char const *p);
00187 # endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00188 
00189     static size_t   get_lazy_length(size_t fromLen, size_t toLen);
00190 
00191 #endif /* __cplusplus */
00192 };
00193 #if !defined(__cplusplus)
00194 typedef struct pan_slice_t pan_slice_t;
00195 #endif /* !__cplusplus */
00196 
00197 
00213 enum pan_severity_t
00214 {
00215 #ifdef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00216         PANTHEIOS_SEV_EMERGENCY         =   0   
00217     ,   PANTHEIOS_SEV_ALERT             =   1   
00218     ,   PANTHEIOS_SEV_CRITICAL          =   2   
00219     ,   PANTHEIOS_SEV_ERROR             =   3   
00220     ,   PANTHEIOS_SEV_WARNING           =   4   
00221     ,   PANTHEIOS_SEV_NOTICE            =   5   
00222     ,   PANTHEIOS_SEV_INFORMATIONAL     =   6   
00223     ,   PANTHEIOS_SEV_DEBUG             =   7   
00224 #else /* ? PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00225         PANTHEIOS_SEV_EMERGENCY_        =   0   
00226     ,   PANTHEIOS_SEV_ALERT_            =   1   
00227     ,   PANTHEIOS_SEV_CRITICAL_         =   2   
00228     ,   PANTHEIOS_SEV_ERROR_            =   3   
00229     ,   PANTHEIOS_SEV_WARNING_          =   4   
00230     ,   PANTHEIOS_SEV_NOTICE_           =   5   
00231     ,   PANTHEIOS_SEV_INFORMATIONAL_    =   6   
00232     ,   PANTHEIOS_SEV_DEBUG_            =   7   
00233 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00234 
00235 };
00236 #if !defined(__cplusplus)
00237 typedef enum pan_severity_t pan_severity_t;
00238 #endif /* !__cplusplus */
00239 
00246 typedef stlsoft_ns_qual(ss_sint32_t)    pan_sev_t;
00247 
00248 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00249 # ifdef __cplusplus
00250 const pan_sev_t PANTHEIOS_SEV_EMERGENCY       =   static_cast<pan_sev_t>(PANTHEIOS_SEV_EMERGENCY_);
00251 const pan_sev_t PANTHEIOS_SEV_ALERT           =   static_cast<pan_sev_t>(PANTHEIOS_SEV_ALERT_);
00252 const pan_sev_t PANTHEIOS_SEV_CRITICAL        =   static_cast<pan_sev_t>(PANTHEIOS_SEV_CRITICAL_);
00253 const pan_sev_t PANTHEIOS_SEV_ERROR           =   static_cast<pan_sev_t>(PANTHEIOS_SEV_ERROR_);
00254 const pan_sev_t PANTHEIOS_SEV_WARNING         =   static_cast<pan_sev_t>(PANTHEIOS_SEV_WARNING_);
00255 const pan_sev_t PANTHEIOS_SEV_NOTICE          =   static_cast<pan_sev_t>(PANTHEIOS_SEV_NOTICE_);
00256 const pan_sev_t PANTHEIOS_SEV_INFORMATIONAL   =   static_cast<pan_sev_t>(PANTHEIOS_SEV_INFORMATIONAL_);
00257 const pan_sev_t PANTHEIOS_SEV_DEBUG           =   static_cast<pan_sev_t>(PANTHEIOS_SEV_DEBUG_);
00258 # else /* ?__cplusplus */
00259 # define PANTHEIOS_SEV_EMERGENCY        ((pan_sev_t)PANTHEIOS_SEV_EMERGENCY_)
00260 # define PANTHEIOS_SEV_ALERT            ((pan_sev_t)PANTHEIOS_SEV_ALERT_)
00261 # define PANTHEIOS_SEV_CRITICAL         ((pan_sev_t)PANTHEIOS_SEV_CRITICAL_)
00262 # define PANTHEIOS_SEV_ERROR            ((pan_sev_t)PANTHEIOS_SEV_ERROR_)
00263 # define PANTHEIOS_SEV_WARNING          ((pan_sev_t)PANTHEIOS_SEV_WARNING_)
00264 # define PANTHEIOS_SEV_NOTICE           ((pan_sev_t)PANTHEIOS_SEV_NOTICE_)
00265 # define PANTHEIOS_SEV_INFORMATIONAL    ((pan_sev_t)PANTHEIOS_SEV_INFORMATIONAL_)
00266 # define PANTHEIOS_SEV_DEBUG            ((pan_sev_t)PANTHEIOS_SEV_DEBUG_)
00267 # endif /* __cplusplus */
00268 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00269 
00270 #ifdef __cplusplus
00271 # if 0
00272 const pan_sev_t emergency       =   PANTHEIOS_SEV_EMERGENCY;
00273 const pan_sev_t alert           =   PANTHEIOS_SEV_ALERT;
00274 const pan_sev_t critical        =   PANTHEIOS_SEV_CRITICAL;
00275 const pan_sev_t error           =   PANTHEIOS_SEV_ERROR;
00276 const pan_sev_t warning         =   PANTHEIOS_SEV_WARNING;
00277 const pan_sev_t notice          =   PANTHEIOS_SEV_NOTICE;
00278 const pan_sev_t informational   =   PANTHEIOS_SEV_INFORMATIONAL;
00279 const pan_sev_t debug           =   PANTHEIOS_SEV_DEBUG;
00280 # else /* ? 0 */
00281 # define PANTHEIOS_INCLUDING_LEVELS
00282 # include "./cpp/levels.hpp"    /* Stock/custom level type */
00283 # undef PANTHEIOS_INCLUDING_LEVELS
00284 # endif /* 0 */
00285 #endif /* __cplusplus */
00286 
00287 /* /////////////////////////////////////////////////////////////////////////
00288  * API
00289  */
00290 
00310 PANTHEIOS_CALL(int) pantheios_init(void);
00311 
00329 PANTHEIOS_CALL(void) pantheios_uninit(void);
00330 
00347 PANTHEIOS_CALL(int) pantheios_isSeverityLogged(pan_sev_t severity);
00348 
00361 PANTHEIOS_CALL(char const*) pantheios_getSeverityString(pan_sev_t severity);
00362 
00376 PANTHEIOS_CALL(int) pantheios_log_n(    pan_sev_t                       severity
00377                                     ,   size_t                          numSlices
00378 #ifdef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00379                                     ,   pantheios::pan_slice_t const   *slices);
00380 #else /* ? PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00381                                     ,   pan_slice_t const               *slices);
00382 #endif /* PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00383 
00384 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00385 # define PANTHEIOS_INCLUDING_C_API_FUNCTIONS
00386 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00387 #include "./c/log_functions.h"    /* pantheios_log_1() (pantheios::log_1()), etc.  */
00388 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00389 # undef PANTHEIOS_INCLUDING_C_API_FUNCTIONS
00390 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00391 
00404 PANTHEIOS_CALL(int) pantheios_printf(   pan_sev_t           severity
00405                                     ,   char const          *format
00406                                     ,   ...);
00407 
00424 PANTHEIOS_CALL(int) pantheios_vprintf(  pan_sev_t           severity
00425                                     ,   char const          *format
00426                                     ,   va_list             args);
00427 
00428 #if 0
00429 PANTHEIOS_CALL(int) pantheios_snprintf( pan_sev_t           severity
00430                                     ,   char                *dest
00431                                     ,   size_t              cchDest
00432                                     ,   char const          *format
00433                                     ,   ...);
00434 PANTHEIOS_CALL(int) pantheios_snvprintf(pan_sev_t           severity
00435                                     ,   char                *dest
00436                                     ,   size_t              cchDest
00437                                     ,   char const          *format
00438                                     ,   va_list             args);
00439 #endif /* 0 */
00440 
00441 /* /////////////////////////////////////////////////////////////////////////
00442  * Utility functions
00443  */
00444 
00445 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00446 PANTHEIOS_CALL(int)     pantheios_isInitialising(void);
00447 PANTHEIOS_CALL(int)     pantheios_isInitialised(void);
00448 PANTHEIOS_CALL(void)    pantheios_exit_process(int code);
00449 PANTHEIOS_CALL(size_t)  pantheios_strnlen(char const *s, size_t len);
00450 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00451 
00466 PANTHEIOS_CALL(int)     pantheios_getNextBackEndId(void);
00467 
00481 PANTHEIOS_CALL(void) pantheios_puts(pan_sev_t severity, char const *message);
00482 
00483 /* /////////////////////////////////////////////////////////////////////////
00484  * API functions for C++
00485  */
00486 
00488 typedef pan_uint8_t     uint8_t;
00490 typedef pan_uint16_t    uint16_t;
00492 typedef pan_uint32_t    uint32_t;
00494 typedef pan_uint64_t    uint64_t;
00495 
00496 #if !defined(PANTHEIOS_NO_NAMESPACE)
00497 
00498 # ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00499 inline int isInitialising()
00500 {
00501     return pantheios_isInitialising();
00502 }
00503 
00504 inline int isInitialised()
00505 {
00506     return pantheios_isInitialised();
00507 }
00508 
00509 inline void exit_process(int code)
00510 {
00511     pantheios_exit_process(code);
00512 }
00513 
00514 inline size_t strnlen(char const *s, size_t len)
00515 {
00516     return pantheios_strnlen(s, len);
00517 }
00518 # endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00519 
00524 inline int isSeverityLogged(pan_sev_t severity)
00525 {
00526     return pantheios_isSeverityLogged(severity);
00527 }
00528 
00533 inline char const *getSeverityString(pan_sev_t severity)
00534 {
00535     return pantheios_getSeverityString(severity);
00536 }
00537 
00540 inline int getNextBackEndId()
00541 {
00542     return pantheios_getNextBackEndId();
00543 }
00544 
00549 inline void puts(pan_sev_t severity, char const *message)
00550 {
00551     pantheios_puts(severity, message);
00552 }
00553 
00554 #endif /* !PANTHEIOS_NO_NAMESPACE */
00555 
00556 /* /////////////////////////////////////////////////////////////////////////
00557  * String access shims
00558  */
00559 
00560 #ifdef __cplusplus
00561 
00563 inline char const *c_str_ptr_a(pan_slice_t const &s)
00564 {
00565     return s.ptr;
00566 }
00568 inline char const *c_str_ptr(pan_slice_t const &s)
00569 {
00570     return s.ptr;
00571 }
00572 
00574 inline char const *c_str_ptr_null_a(pan_slice_t const &s)
00575 {
00576     return (0 != s.len) ? s.ptr : NULL;
00577 }
00579 inline char const *c_str_ptr_null(pan_slice_t const &s)
00580 {
00581     return (0 != s.len) ? s.ptr : NULL;
00582 }
00583 
00585 inline char const *c_str_data_a(pan_slice_t const &s)
00586 {
00587     return c_str_ptr(s);
00588 }
00590 inline char const *c_str_data(pan_slice_t const &s)
00591 {
00592     return c_str_ptr(s);
00593 }
00594 
00596 inline size_t c_str_len_a(pan_slice_t const &s)
00597 {
00598     return s.len;
00599 }
00601 inline size_t c_str_len(pan_slice_t const &s)
00602 {
00603     return s.len;
00604 }
00605 
00606 
00607 
00608 
00610 inline char const *c_str_ptr_a(pan_slice_t const *s)
00611 {
00612     return (NULL != s) ? s->ptr : "";
00613 }
00615 inline char const *c_str_ptr(pan_slice_t const *s)
00616 {
00617     return (NULL != s) ? s->ptr : "";
00618 }
00619 
00621 inline char const *c_str_ptr_null_a(pan_slice_t const *s)
00622 {
00623     return (NULL != s && (0 != s->len)) ? s->ptr : NULL;
00624 }
00626 inline char const *c_str_ptr_null(pan_slice_t const *s)
00627 {
00628     return (NULL != s && (0 != s->len)) ? s->ptr : NULL;
00629 }
00630 
00632 inline char const *c_str_data_a(pan_slice_t const *s)
00633 {
00634     return c_str_ptr(s);
00635 }
00637 inline char const *c_str_data(pan_slice_t const *s)
00638 {
00639     return c_str_ptr(s);
00640 }
00641 
00643 inline size_t c_str_len_a(pan_slice_t const *s)
00644 {
00645     return (NULL != s) ? s->len : 0;
00646 }
00648 inline size_t c_str_len(pan_slice_t const *s)
00649 {
00650     return (NULL != s) ? s->len : 0;
00651 }
00652 
00653 #endif /* __cplusplus */
00654 
00655 /* /////////////////////////////////////////////////////////////////////////
00656  * Namespace
00657  */
00658 
00659 #ifdef __cplusplus
00660 # ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00661 inline pan_slice_t::pan_slice_t()
00662     : len(0)
00663     , ptr(NULL)
00664 {}
00665 inline pan_slice_t::pan_slice_t(char const *p, size_t l)
00666     : len(l)
00667     , ptr(p)
00668 {
00669     const size_t topBit =   size_t(0x01) << (sizeof(size_t) * 8 - 1);
00670 
00671     if(topBit & len)
00672     {
00673         this->len = pantheios_strnlen(p, len);
00674     }
00675 }
00676 inline pan_slice_t::pan_slice_t(pan_slice_t const &rhs)
00677     : len(rhs.len)
00678     , ptr(rhs.ptr)
00679 {}
00680 inline pan_slice_t &pan_slice_t::operator =(pan_slice_t const &rhs)
00681 {
00682     len = rhs.len;
00683     ptr = rhs.ptr;
00684 
00685     return *this;
00686 }
00687 
00688 inline pan_slice_t::pan_slice_t(int len, char const *p)
00689     : len(pantheios_strnlen(p, static_cast<size_t>(len)))
00690     , ptr(p)
00691 {}
00692 # endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00693 #endif /* __cplusplus */
00694 
00695 /* /////////////////////////////////////////////////////////////////////////
00696  * Namespace
00697  */
00698 
00699 #if !defined(PANTHEIOS_NO_NAMESPACE)
00700 } /* namespace pantheios */
00701 
00702 #ifdef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00703 
00715 #endif /* PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00716 namespace stlsoft
00717 {
00718     using ::pantheios::c_str_data_a;
00719     using ::pantheios::c_str_data;
00720 
00721     using ::pantheios::c_str_len;
00722     using ::pantheios::c_str_len_a;
00723 
00724     using ::pantheios::c_str_ptr_a;
00725     using ::pantheios::c_str_ptr;
00726 
00727     using ::pantheios::c_str_ptr_null_a;
00728     using ::pantheios::c_str_ptr_null;
00729 }
00730 
00731 #endif /* !PANTHEIOS_NO_NAMESPACE */
00732 
00733 /* /////////////////////////////////////////////////////////////////////////
00734  * Inclusion
00735  */
00736 
00737 #ifdef STLSOFT_CF_PRAGMA_ONCE_SUPPORT
00738 # pragma once
00739 #endif /* STLSOFT_CF_PRAGMA_ONCE_SUPPORT */
00740 
00741 /* ////////////////////////////////////////////////////////////////////// */
00742 
00743 #endif /* !PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS */
00744 
00745 /* ////////////////////////////////////////////////////////////////////// */