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

FXFileIO.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                  File I/O object                                              *
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 FXFILEIO_H
00023 #define FXFILEIO_H
00024 
00025 #ifndef FXIOHANDLE_H
00026 #include "FXIOHandle.h"
00027 #endif
00028 namespace FXEX {
00029 class FXFileMonitor;
00030 
00031 /**
00032  * The FXFileIO implements file read/write access, including ability to seek
00033  * around the file, and support for read and write locking all or parts of a file.
00034  * Detects when new data is available from the file (if the file pointer is at the end
00035  * of the file), then reads in the new data.
00036  *
00037  * You can also memory-map a section of the file, from the current seek point, then
00038  * treat the pointer returned, as a section of raw memory.
00039  *
00040  * Note, file permissions are set to 'secure IO' mode, by default, for all new objects.
00041  */
00042 
00043 enum {
00044   FILEIO_EXCLUSIVE       = 0x00000001,  // exclusive access to file
00045   FILEIO_TRUNCATE        = 0x00000002,  // truncate file on opening
00046   FILEIO_SYNC            = 0x00000004,  // make writes sychronous if possible
00047   FILEIO_REMOVE_ON_CLOSE = 0x00000008   // remove the file when closed
00048   };
00049 
00050 
00051 class FXAPI FXFileIO : public FXIOHandle {
00052   FXDECLARE(FXFileIO)
00053 
00054   public:
00055     enum{
00056       LockUnknown=-1,   // couldn't determine lock status
00057       Unlocked=0,       // not locked
00058       LockRead=1,       // this process is currently holding an read lock
00059       LockWrite=2,      // this process is currently holding an write lock
00060       LockedRead=3,     // read locked by another process
00061       LockedWrite=4,    // write locked by another process
00062       };
00063 
00064   private:
00065     static FXuint filemodeDefault; // value used for all new FileIO objects
00066 
00067   protected:
00068     FXString       filename;        // file name
00069     FXbool         temp;            // indicates if file is a temp file
00070     FXuint         filemode;        // file permissions (mode flags)
00071     FXuint         retryInterval;   // retry interval for 'lock' polling
00072     FXint          locked;          // locked status
00073     void          *region;          // mapped region
00074     FXuint         mappedLength;    // length of mapped region
00075     FXFileMonitor *monitor;         // monitors file activity - used to simulate 'data ready'
00076 
00077   protected:
00078     FXFileIO(){}
00079 
00080     /// instantiates this class
00081     virtual FXFileIO* newInstance(FXInputHandle h);
00082 
00083   public:
00084     enum {
00085       ID_FILEIO=FXIOHandle::ID_LAST,
00086       ID_LAST
00087       };
00088 
00089   public:
00090     long onConnect(FXObject*,FXSelector,void*);
00091     long onFileCreated(FXObject*,FXSelector,void*);
00092     long onFileChanged(FXObject*,FXSelector,void*);
00093     long onFileClosed(FXObject*,FXSelector,void*);
00094 
00095   public:
00096     /// get access to a file
00097     FXFileIO(FXApp *a,const FXString& file="",FXObject *tgt=NULL,FXSelector sel=0,FXuint opts=0);
00098 
00099     /// use an already open file :-)
00100     FXFileIO(FXInputHandle f,FXApp *a,FXObject *tgt=NULL,FXSelector sel=0);
00101 
00102     /// create a temporary file, deletes on close
00103     FXFileIO(FXApp *a,FXObject *tgt=NULL,FXSelector=0);
00104 
00105     /// create resource
00106     virtual void create();
00107 
00108     /// get the filename
00109     FXString name() const;
00110 
00111     /// set to new file, but only if the file is not open (fails silently)
00112     void name(const FXString& file);
00113 
00114     /**
00115      * Set file permissions (mode flags).
00116      * The permissions that can be set, are taken from the 'unix way' - I have looked at the
00117      * Win32 security permissions/ACL's for files; get this, there is a permission to stop
00118      * you deleting a file, but you can happily truncate to file to zero bytes - what the?
00119      * If you have write access, then you might as well have delete access.
00120      * In any case, if a better idea comes along we can always change it...
00121      *
00122      * If the file exists, the permission is applied to a file immediately.  If the file is
00123      * yet to be opened, it is applied to the file on opening time.
00124      */
00125     void mode(FXuint m);
00126 
00127     /**
00128      * Returns the permission (mode flags) on the file; if the file exists, the permission
00129      * is the value from the file; if the file doesn't exist, the value returned is the
00130      * 'default' value if no previous call to modeDefault() has been called, otherwise it
00131      * is the value passed in the modeDefault() call
00132      */
00133     FXuint mode();
00134 
00135     /// open the file
00136     virtual FXbool open();
00137 
00138     /// close the file
00139     virtual void close();
00140 
00141     /// get the current size
00142     FXlong size();
00143 
00144     /// is the file a temp file
00145     FXbool isTemp() const { return temp; }
00146 
00147     /// mark the file, as a temp file - temp files are removed on close
00148     void setTemp(FXbool t=TRUE);
00149 
00150     /**
00151      * Enable FXFileIO to detect when new data is available from the file.
00152      * This moves the file pointer to the end of the file, reading in the file as it moves.
00153      * It then tries to maintain the file pointer at the end of the file.  The idea is that
00154      * you can treat a file, like a socket, ie continually incoming data.
00155      *
00156      * It is also used to enable 'auto-open' feature of FXFileIO which will detect when
00157      * the filename exists, and if enabled will open the file for you.
00158      *
00159      * If you want to have the 'auto-open' but not the 'new-data-available' functionality,
00160      * handle SEL_IO_CONNECT in your app, then disable the FXFileIO object, finally return 0.
00161      * eg
00162      *
00163      * FXMAPFUNC(SEL_IO_CONNECT,App::ID_FILE,App::onAutoOpen),
00164      *
00165      * long App::onAutoOpen(FXObject *sender,FXSelector,void*){
00166      *   sender->handle(this,FXSEL(SEL_COMMAND,ID_DISABLE),NULL);
00167      *   return 0;
00168      *   }
00169      */
00170     virtual void enable();
00171 
00172     /// Disable the ability to detect when mroe data is available from the file
00173     virtual void disable();
00174 
00175     /**
00176      * Flush/sync data to disk - returns when sync is complete.
00177      * Used to sunchronise memory mapped files, or when FILEIO_SYNC is not specified.
00178      */
00179     void sync();
00180 
00181     /// what is current file pointer position
00182     FXlong current();
00183 
00184     /// move to the start of file plus some number of pos bytes
00185     FXbool seekbegin(FXlong pos=0);
00186 
00187     /// move to some point in the file, from where it is currently
00188     FXbool seek(FXlong pos);
00189 
00190     /// move to the end of the file minus pos
00191     /// Note: zero is the first byte beyond the end of the file,
00192     ///       -1 is one past the end of the file (differs from lseek)
00193     FXbool seekend(FXlong pos=0);
00194 
00195     /// truncate the file to some length
00196     /// Note: you should really check the size of the file, after you call truncate
00197     FXbool truncate(FXlong len);
00198 
00199     /// nice and simple lock interface
00200     FXbool lock() { return writeLock(); }
00201 
00202     /// nice and simple unlock interface
00203     FXbool unlock(FXlong len);
00204 
00205     /// is the file already locked
00206     /// - a length of zero implies the whole file
00207     /// - for the simple interface, a non-zero return code implies some form of lock
00208     /// - otherwise, returns 'Unlocked' (0) if not locked, or the type of lock
00209     FXint isLocked(FXlong len=0);
00210 
00211     /// lock a file - read lock
00212     /// - multiple read locks can be in-force (by multiple processes) at any given time
00213     /// - never unlocks any other lock
00214     /// - locking with a length of zero means lock the whole file
00215     /// - otherwise lock the number of bytes, begining from the current position
00216     /// - timeout is in milliseconds
00217     FXbool readLock(FXlong len=0,FXint timeout=0);
00218 
00219     /// lock a file - write lock
00220     /// - only one lock can be in force at any given time, ie the write lock
00221     /// - cannot unlock any other lock
00222     /// - a write lock still allows you to read the file (ie it is a more powerful read lock)
00223     /// - locking with a length of zero means lock the whole file
00224     /// - otherwise lock the number of bytes, begining from the current position
00225     /// - timeout is in milliseconds
00226     FXbool writeLock(FXlong len=0,FXint timeout=0);
00227     
00228     /// this allows us to adjust or retry interval when trying to set a lock
00229     /// - retry in nanoseconds
00230     void setLockRetry(FXuint retry) { retryInterval=retry; }
00231 
00232     /// this class supports memory mapping of the file, but only one region at a time...
00233     /// load part of the file into memory, from the current seek position
00234     FXbool map(FXlong len,FXbool writeable=TRUE);
00235 
00236     /// unload part of a file from memory
00237     void unmap();
00238 
00239     /// is the file mapped into memory
00240     FXbool isMapped() { return region?TRUE:FALSE; }
00241 
00242     /// return pointer to mapped memory
00243     void* getMapping() { return region; }
00244 
00245     /// duplicate this file handle
00246     FXFileIO* duplicate(FXInputHandle newHandle=INVALID_HANDLE);
00247 
00248     /// set the default mode for all new FileIO objects
00249     static void modeDefault(FXuint mode) { filemodeDefault=mode; }
00250 
00251     /// get the default mode of all new FileIO objects
00252     static FXuint modeDefault() { return filemodeDefault; }
00253 
00254     /// save object to stream
00255     virtual void save(FXStream& store) const;
00256 
00257     /// load object from stream
00258     virtual void load(FXStream& store);
00259 
00260     /**
00261      * Destructor
00262      * If the object contains a mapped region, the region is unmapped before destruction.
00263      */
00264     virtual ~FXFileIO();
00265   };
00266 
00267 } // namespace FXEX
00268 #endif // FXFileIO