Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members

FXBinaryLogReader.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                  Binary log file reader                                       *
00004 *                                                                               *
00005 *********************************************************************************
00006 * Copyright (C) 2003 by Mathew Robertson.   All Rights Reserved.                *
00007 *********************************************************************************
00008 * This library is free software; you can redistribute it and/or                 *
00009 * modify it under the terms of the GNU Lesser General Public                    *
00010 * License as published by the Free Software Foundation; either                  *
00011 * version 2.1 of the License, or (at your option) any later version.            *
00012 *                                                                               *
00013 * This library is distributed in the hope that it will be useful,               *
00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of                *
00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU             *
00016 * Lesser General Public License for more details.                               *
00017 *                                                                               *
00018 * You should have received a copy of the GNU Lesser General Public              *
00019 * License along with this library; if not, write to the Free Software           *
00020 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.    *
00021 *********************************************************************************/
00022 #ifndef FXBINARYLOGREADER_H
00023 #define FXBINARYLOGREADER_H
00024 
00025 namespace FXEX {
00026 
00027 /// Container data structure for a log entry
00028 struct FXBinaryLogData {
00029   FXbool  subsecond;      // does the log contain valid subsecond resolution
00030   FXTime  seconds;        // current time, seconds resolution
00031   FXint   microseconds;   // current time, microseconds resolution
00032   FXshort code;           // status code of log entry
00033   FXshort value;          // status value of log entry
00034   };
00035 
00036 /// Binary Log Reader options
00037 enum {
00038   BINARYLOGREADER_TRUNCATE=0x02   // Truncate the file on opening ? FIXME...
00039   };
00040 
00041 /**
00042  * A binary log file allows applications to log entries to a file, faster and more compact
00043  * than a normal log file.
00044  *
00045  * How this differs from a normal log file is that, up to 1000% of the speed of a log file
00046  * is consumed in the printf style parsing of the input string.  By using numbers only,
00047  * no parsing is necessary.  As an added bonus, you dont log many bytes per log entry so
00048  * the disk I/O time is reduced.
00049  *
00050  * The upshot is that a binary logger can run many times quicker than a text file logger,
00051  * and that the storage of that information is more compact.  The downside is that you need
00052  * a custom program to read the file (see FXBinaryLogReader).
00053  *
00054  * File format:
00055  * - file header (2 bytes)
00056  *   - 1 byte version code
00057  *   - 1 byte options value
00058  * - written per log entry (8-12 bytes)
00059  *   - 32bit date stamp
00060  *     - 1 second resolution
00061  *   - 32bit subsecond date stamp
00062  *     - microsecond resolution
00063  *     - optional
00064  *   - 32bit log entry
00065  *     - upper 16bits are used for indicating error severity
00066  *     - lower 16bits are used for indicating enumerated value
00067  *
00068  * Notes:
00069  * 1. The log file stores the endian-ness of the CPU architecture so that the log file
00070  *    can later be read back on any type of CPU.
00071  * 2. Log entries are automatically written on file open/close (as debug entries)
00072  *
00073  * It is envisaged that you could use this logger in an embedded application.  You would
00074  * log the values you need, when you identify a condition that needs to be logged.  You 
00075  * should create a specific enumerated value, for all possible log cases.
00076  */
00077 class FXAPI FXBinaryLogReader {
00078 private:
00079   FXFileIO              *fileio;    // file IO object
00080   FXBinaryLogData        logentry;  // holding variable for a log entry
00081   FXuchar                options;
00082 
00083 protected:
00084   /// opens the log file for writing
00085   FXbool open();
00086 
00087   /// closes the log file
00088   void close();
00089 
00090 public:
00091   /// Give me a log file
00092   FXBinaryLogReader(const FXString& file="",FXuint opts=0);
00093 
00094   /// Change the location of the log file - change is immediate
00095   FXbool name(const FXString& file);
00096 
00097   /// get the current filename
00098   FXString name();
00099 
00100   /// indicates whether the log file can/will be read from
00101   FXbool opened();
00102 
00103   /// read log entries from the file
00104   FXBinaryLogData* read();
00105 
00106   /// Save to stream
00107   friend FXAPI FXStream& operator<<(FXStream& store,const FXBinaryLogReader& b);
00108 
00109   /// load from stream
00110   friend FXAPI FXStream& operator>>(FXStream& store,FXBinaryLogReader& b);
00111 
00112   /// done
00113   virtual ~FXBinaryLogReader();
00114   };
00115 
00116 } // namespace FXEX
00117 #endif // FXBINARYLOGREADER_H