00001 /* /////////////////////////////////////////////////////////////////////////
00002  * File:        pantheios/backends/bec.file.h
00003  *
00004  * Purpose:     Declaration of the Pantheios file Stock Back-end API.
00005  *
00006  * Created:     10th July 2006
00007  * Updated:     27th December 2010
00008  *
00009  * Home:        http://www.pantheios.org/
00010  *
00011  * Copyright (c) 2006-2010, Matthew Wilson and Synesis Software
00012  * All rights reserved.
00013  *
00014  * Redistribution and use in source and binary forms, with or without
00015  * modification, are permitted provided that the following conditions are
00016  * met:
00017  *
00018  * - Redistributions of source code must retain the above copyright notice,
00019  *   this list of conditions and the following disclaimer.
00020  * - Redistributions in binary form must reproduce the above copyright
00021  *   notice, this list of conditions and the following disclaimer in the
00022  *   documentation and/or other materials provided with the distribution.
00023  * - Neither the name(s) of Matthew Wilson and Synesis Software nor the
00024  *   names of any contributors may be used to endorse or promote products
00025  *   derived from this software without specific prior written permission.
00026  *
00027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
00028  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00029  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00030  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00031  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00032  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00033  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00034  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00035  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00036  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00037  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00038  *
00039  * ////////////////////////////////////////////////////////////////////// */
00040 
00041 
00047 #ifndef PANTHEIOS_INCL_PANTHEIOS_BACKENDS_H_BEC_FILE
00048 #define PANTHEIOS_INCL_PANTHEIOS_BACKENDS_H_BEC_FILE
00049 
00050 /* /////////////////////////////////////////////////////////////////////////
00051  * Version information
00052  */
00053 
00054 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00055 # define PANTHEIOS_VER_PANTHEIOS_BACKENDS_H_BEC_FILE_MAJOR      4
00056 # define PANTHEIOS_VER_PANTHEIOS_BACKENDS_H_BEC_FILE_MINOR      3
00057 # define PANTHEIOS_VER_PANTHEIOS_BACKENDS_H_BEC_FILE_REVISION   1
00058 # define PANTHEIOS_VER_PANTHEIOS_BACKENDS_H_BEC_FILE_EDIT       33
00059 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00060 
00061 /* /////////////////////////////////////////////////////////////////////////
00062  * Includes
00063  */
00064 
00065 #ifndef PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS
00066 # include <pantheios/pantheios.h>
00067 #endif /* !PANTHEIOS_INCL_PANTHEIOS_H_PANTHEIOS */
00068 #ifndef PANTHEIOS_INCL_PANTHEIOS_H_BACKEND
00069 # include <pantheios/backend.h>
00070 #endif /* !PANTHEIOS_INCL_PANTHEIOS_H_BACKEND */
00071 
00072 /* /////////////////////////////////////////////////////////////////////////
00073  * Documentation
00074  */
00075 
00081 /* /////////////////////////////////////////////////////////////////////////
00082  * Constants
00083  */
00084 
00159 #define PANTHEIOS_BE_FILE_F_TRUNCATE                    (0x00100000)
00160 #define PANTHEIOS_BE_FILE_F_DISCARD_CACHED_CONTENTS     (0x00200000)
00161 #define PANTHEIOS_BE_FILE_F_SHARE_ON_WINDOWS            (0x00400000)
00162 #define PANTHEIOS_BE_FILE_F_WRITE_WIDE_CONTENTS         (0x00800000)
00163 #define PANTHEIOS_BE_FILE_F_WRITE_MULTIBYTE_CONTENTS    (0x00080000)
00164 #define PANTHEIOS_BE_FILE_F_DELETE_IF_EMPTY             (0x00040000)
00165 
00166 #if 0 /* None of the following are yet supported: */
00167 #define PANTHEIOS_BE_FILE_F_ROLL_ON_SIZE                (0x01000000)
00168 #define PANTHEIOS_BE_FILE_F_ROLL_ON_ENTRY_COUNT         (0x02000000)
00169 #define PANTHEIOS_BE_FILE_F_ROLL_ON_DATETIME            (0x04000000)
00170 
00171 #define PANTHEIOS_BE_FILE_F_ROLL_ON_1MB                 (0x10000000 | PANTHEIOS_BE_FILE_F_ROLL_ON_SIZE)
00172 #define PANTHEIOS_BE_FILE_F_ROLL_ON_8K_ENTRIES          (0x10000000 | PANTHEIOS_BE_FILE_F_ROLL_ON_ENTRY_COUNT)
00173 #define PANTHEIOS_BE_FILE_F_ROLL_ON_DAY                 (0x10000000 | PANTHEIOS_BE_FILE_F_ROLL_ON_DATETIME)
00174 
00175 #define PANTHEIOS_BE_FILE_F_ROLL_TO_SELF                (0x20000000)
00176 #endif /* 0 */
00177 
00178 /* /////////////////////////////////////////////////////////////////////////
00179  * External Declarations
00180  */
00181 
00182 #ifndef PANTHEIOS_DOCUMENTATION_SKIP_SECTION
00183 struct Pantheios_be_file_no_longer_defines_the_function_pantheios_be_file_setFileName_and_Use_pantheios_be_file_setFilePath_instead_;
00184 # define Pantheios_be_file_setFileName (_pantheios_be_file_no_longer_defines_the_function_pantheios_be_file_setFileName_and_Use_pantheios_be_file_setFilePath_instead_)
00185 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION */
00186 
00187 /* /////////////////////////////////////////////////////////////////////////
00188  * Typedefs
00189  */
00190 
00199 #define PANTHEIOS_BE_FILE_MAX_FILE_LEN              (1000)
00200 
00205 struct pan_be_file_init_t
00206 {
00207 #if !defined(PANTHEIOS_DOCUMENTATION_SKIP_SECTION) && \
00208     !defined(PANTHEIOS_NO_NAMESPACE)
00209     typedef pantheios::pan_uint16_t pan_uint16_t;
00210     typedef pantheios::pan_uint32_t pan_uint32_t;
00211     typedef pantheios::pan_uint64_t pan_uint64_t;
00212 #endif /* !PANTHEIOS_DOCUMENTATION_SKIP_SECTION && !PANTHEIOS_NO_NAMESPACE */
00213 
00214     pan_uint32_t        version;    
00215     pan_uint32_t        flags;      
00216     PAN_CHAR_T          buff[1 + (PANTHEIOS_BE_FILE_MAX_FILE_LEN)]; 
00217     PAN_CHAR_T const*   fileName;  
00219 #if 0 /* These features are part of a stream of development for log-file rolling that is incomplete. */
00220     union
00221     {
00222         pan_uint64_t    fileSizeKB; 
00223         pan_uint64_t    entryCount; 
00224         pan_uint64_t    interval;   
00226     }                   roll;       
00227 #endif /* 0 */
00228 
00229 
00230 #ifdef __cplusplus
00231 public: /* Construction */
00232 # ifndef PANTHEIOS_BE_INIT_NO_CPP_STRUCT_INIT
00233     pan_be_file_init_t();
00234 # endif /* !PANTHEIOS_BE_INIT_NO_CPP_STRUCT_INIT */
00235 #endif /* __cplusplus */
00236 };
00237 #ifndef __cplusplus
00238 typedef struct pan_be_file_init_t   pan_be_file_init_t;
00239 #endif /* !__cplusplus */
00240 
00241 /* /////////////////////////////////////////////////////////////////////////
00242  * Application-defined functions
00243  */
00244 
00273 PANTHEIOS_CALL(void) pantheios_be_file_getAppInit(
00274     int                     backEndId
00275 ,   pan_be_file_init_t*     init
00276 ) /* throw() */;
00277 
00278 /* /////////////////////////////////////////////////////////////////////////
00279  * API
00280  */
00281 
00287 PANTHEIOS_CALL(void) pantheios_be_file_getDefaultAppInit(
00288     pan_be_file_init_t* init
00289 ) /* throw() */;
00290 
00295 PANTHEIOS_CALL(int) pantheios_be_file_init(
00296     PAN_CHAR_T const*           processIdentity
00297 ,   int                         id
00298 ,   pan_be_file_init_t const*   init
00299 ,   void*                       reserved
00300 ,   void**                      ptoken
00301 );
00302 
00307 PANTHEIOS_CALL(void) pantheios_be_file_uninit(void* token);
00308 
00313 PANTHEIOS_CALL(int) pantheios_be_file_logEntry(
00314     void*               feToken
00315 ,   void*               beToken
00316 ,   int                 severity
00317 ,   PAN_CHAR_T const*   entry
00318 ,   size_t              cchEntry
00319 );
00320 
00347 PANTHEIOS_CALL(int) pantheios_be_file_setFilePath(
00348     PAN_CHAR_T const*                   fileName
00349 #ifndef PANTHEIOS_NO_NAMESPACE
00350 ,   pan_be_file_init_t::pan_uint32_t    fileMask
00351 ,   pan_be_file_init_t::pan_uint32_t    fileFlags
00352 #else /* ? !PANTHEIOS_NO_NAMESPACE */
00353 ,   pan_uint32_t                        fileMask
00354 ,   pan_uint32_t                        fileFlags
00355 #endif /* !PANTHEIOS_NO_NAMESPACE */
00356 ,   int                                 backEndId
00357 );
00358 
00359 #ifdef __cplusplus
00360 
00369 inline int pantheios_be_file_setFilePath(PAN_CHAR_T const* fileName)
00370 {
00371     return pantheios_be_file_setFilePath(fileName, 0, 0, PANTHEIOS_BEID_ALL);
00372 }
00373 
00386 inline int pantheios_be_file_setFilePath(PAN_CHAR_T const* fileName, int backEndId)
00387 {
00388     return pantheios_be_file_setFilePath(fileName, 0, 0, backEndId);
00389 }
00390 #endif /* __cplusplus */
00391 
00400 PANTHEIOS_CALL(int) pantheios_be_file_flush(int backEndId);
00401 
00430 PANTHEIOS_CALL(int) pantheios_be_file_parseArgs(
00431     size_t                          numArgs
00432 #ifdef PANTHEIOS_NO_NAMESPACE
00433 ,   struct pan_slice_t* const       args
00434 #else /* ? PANTHEIOS_NO_NAMESPACE */
00435 ,   pantheios::pan_slice_t* const   args
00436 #endif /* PANTHEIOS_NO_NAMESPACE */
00437 ,   pan_be_file_init_t*             init
00438 );
00439 
00440 /* ////////////////////////////////////////////////////////////////////// */
00441 
00442 #ifdef __cplusplus
00443 # ifndef PANTHEIOS_BE_INIT_NO_CPP_STRUCT_INIT
00444 inline pan_be_file_init_t::pan_be_file_init_t()
00445 {
00446     pantheios_be_file_getDefaultAppInit(this);
00447 }
00448 # endif /* !PANTHEIOS_BE_INIT_NO_CPP_STRUCT_INIT */
00449 #endif /* __cplusplus */
00450 
00451 /* ////////////////////////////////////////////////////////////////////// */
00452 
00453 #endif /* PANTHEIOS_INCL_PANTHEIOS_BACKENDS_H_BEC_FILE */
00454 
00455 /* ///////////////////////////// end of file //////////////////////////// */

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