file.h

Go to the documentation of this file.

/*
 * file.h
 *
 * Operating System file I/O channel class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: file.h,v $
 * Revision 1.43  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.42  2003/09/26 09:58:50  rogerhardiman
 * Move #include <sys/stat.h> from the unix file.h to the main file.h
 * FreeBSD's sys/stat.h includes extern "C" for some prototypes and you
 * cannot have an extern "C" in the middle of a C++ class
 *
 * Revision 1.41  2003/09/17 05:41:58  csoutheren
 * Removed recursive includes
 *
 * Revision 1.40  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.39  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.38  2002/07/02 08:00:55  craigs
 * Also made GetPosition, SetPosition and SetLength virtual as well
 *
 * Revision 1.37  2002/07/02 07:59:42  craigs
 * Added virtual to GetLength call
 *
 * Revision 1.36  2002/01/13 20:54:55  rogerh
 * Make the other Open() virtual so it can be overridden (eg in PWAVFile)
 *
 * Revision 1.35  2001/05/22 12:49:32  robertj
 * Did some seriously wierd rewrite of platform headers to eliminate the
 *   stupid GNU compiler warning about braces not matching.
 *
 * Revision 1.34  2000/09/27 05:58:07  craigs
 * Added virtual to PFile::Open to allow overriding in descandant classes
 *
 * Revision 1.33  2000/07/09 14:05:46  robertj
 * Added file share options.
 *
 * Revision 1.32  1999/06/13 13:54:07  robertj
 * Added PConsoleChannel class for access to stdin/stdout/stderr.
 *
 * Revision 1.31  1999/06/09 02:05:20  robertj
 * Added ability to open file as standard input, output and error streams.
 *
 * Revision 1.30  1999/03/09 02:59:49  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.29  1999/02/16 08:07:11  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.28  1998/09/23 06:20:35  robertj
 * Added open source copyright license.
 *
 * Revision 1.27  1995/07/31 12:15:43  robertj
 * Removed PContainer from PChannel ancestor.
 *
 * Revision 1.26  1995/06/17 11:12:33  robertj
 * Documentation update.
 *
 * Revision 1.25  1995/04/22 00:43:57  robertj
 * Added Move() function and changed semantics of Rename().
 * Changed all file name strings to PFilePath objects.
 *
 * Revision 1.24  1995/03/14 12:41:23  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.23  1995/03/12  04:37:13  robertj
 * Moved GetHandle() function from PFile to PChannel.
 *
 * Revision 1.22  1995/01/14  06:22:11  robertj
 * Documentation
 *
 * Revision 1.21  1994/12/21  11:52:54  robertj
 * Documentation and variable normalisation.
 *
 * Revision 1.20  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.19  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.18  1994/08/21  23:43:02  robertj
 * Added "remove on close" feature for temporary files.
 * Added "force" option to Remove/Rename etc to override write protection.
 * Added function to set file permissions.
 *
 * Revision 1.17  1994/07/17  10:46:06  robertj
 * Moved data to platform dependent files.
 *
 * Revision 1.16  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.15  1994/04/20  12:17:44  robertj
 * Split name into PFilePath
 *
 * Revision 1.14  1994/04/01  14:11:03  robertj
 * Added const to functions.
 * Added SetName function.
 *
 * Revision 1.13  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.12  1994/01/13  03:40:22  robertj
 * Added hidden flag to file info.
 *
 * Revision 1.12  1994/01/13  03:36:48  robertj
 * Created intermediate class PInteractorLayout for dialog-ish windows.
 *
 * Revision 1.11  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.10  1993/12/31  06:45:38  robertj
 * Made inlines optional for debugging purposes.
 *
 * Revision 1.9  1993/09/27  16:35:25  robertj
 * Changed GetName() to GetTitle(), better naming convention.
 * Moved internal functions to private section.
 *
 * Revision 1.8  1993/08/31  03:38:02  robertj
 * Changed PFile::Status to PFile::Info due to X-Windows compatibility.
 *
 * Revision 1.7  1993/08/27  18:17:47  robertj
 * Moved code from MS-DOS platform to common files.
 *
 * Revision 1.6  1993/08/21  04:40:19  robertj
 * Added Copy() function.
 *
 * Revision 1.5  1993/08/21  01:50:33  robertj
 * Made Clone() function optional, default will assert if called.
 *
 * Revision 1.4  1993/08/01  14:05:27  robertj
 * Added GetFileName() function required for proper portability.
 * Improved some comments.
 *
 * Revision 1.3  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */


#ifndef _PFILE
#define _PFILE

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#ifndef _WIN32
#include <sys/stat.h>
#endif



// Binary Files

class PFile : public PChannel
{
  PCLASSINFO(PFile, PChannel);

  public:
    PFile();

    enum OpenMode {
      ReadOnly,
      WriteOnly,
      ReadWrite
    };

    enum OpenOptions {
      ModeDefault = -1, 
      MustExist = 0,    
      Create = 1,       
      Truncate = 2,     
      Exclusive = 4,    
      Temporary = 8,
      DenySharedRead = 16,
      DenySharedWrite = 32
    };

    PFile(
      OpenMode mode,          
      int opts = ModeDefault  
    );

    PFile(
      const PFilePath & name,    
      OpenMode mode = ReadWrite, 
      int opts = ModeDefault     
    );

    ~PFile();


    Comparison Compare(
      const PObject & obj   
    ) const;


    virtual PString GetName() const;

    virtual BOOL Read(
      void * buf,   
      PINDEX len    
    );

    virtual BOOL Write(
      const void * buf, 
      PINDEX len        
    );

    virtual BOOL Close();


    static BOOL Exists(
      const PFilePath & name  
    );

    BOOL Exists() const;

    static BOOL Access(
      const PFilePath & name, 
      OpenMode mode         
    );

    BOOL Access(
      OpenMode mode         
    );

    static BOOL Remove(
      const PFilePath & name,   // Name of file to delete.
      BOOL force = FALSE      // Force deletion even if file is protected.
    );

    BOOL Remove(
      BOOL force = FALSE      // Force deletion even if file is protected.
    );

    static BOOL Rename(
      const PFilePath & oldname,  
      const PString & newname,    
      BOOL force = FALSE
    );

    BOOL Rename(
      const PString & newname,  
      BOOL force = FALSE
    );

    static BOOL Copy(
      const PFilePath & oldname,  
      const PFilePath & newname,  
      BOOL force = FALSE
    );

    BOOL Copy(
      const PFilePath & newname,  
      BOOL force = FALSE
    );

    static BOOL Move(
      const PFilePath & oldname,  
      const PFilePath & newname,  
      BOOL force = FALSE
    );

    BOOL Move(
      const PFilePath & newname,  
      BOOL force = FALSE
    );

    const PFilePath & GetFilePath() const;

    void SetFilePath(
      const PString & path    
    );


    virtual BOOL Open(
      OpenMode mode = ReadWrite,  // Mode in which to open the file.
      int opts = ModeDefault      // Options for open operation.
    );

    virtual BOOL Open(
      const PFilePath & name,    // Name of file to open.
      OpenMode mode = ReadWrite, // Mode in which to open the file.
      int opts = ModeDefault     // #OpenOptions enum# for open operation.
    );
      
    virtual off_t GetLength() const;
      
    virtual BOOL SetLength(
      off_t len   // New length of file.
    );

    enum FilePositionOrigin {
      Start = SEEK_SET,   
      Current = SEEK_CUR, 
      End = SEEK_END      
    };

    virtual BOOL SetPosition(
      off_t pos,                         
      FilePositionOrigin origin = Start  
    );

    virtual off_t GetPosition() const;

    BOOL IsEndOfFile() const;
      
    static BOOL GetInfo(
      const PFilePath & name,  // Name of file to get the information on.
      PFileInfo & info
      // #PFileInfo# structure to receive the information.
    );

    BOOL GetInfo(
      PFileInfo & info
      // #PFileInfo# structure to receive the information.
    );

    static BOOL SetPermissions(
      const PFilePath & name,   // Name of file to change the permission of.
      int permissions           // New permissions mask for the file.
    );
    BOOL SetPermissions(
      int permissions           // New permissions mask for the file.
    );

  protected:
    // Member variables
    PFilePath path;

    BOOL removeOnClose;


// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/file.h"
#else
#include "unix/ptlib/file.h"
#endif
};

#endif

// End Of File ///////////////////////////////////////////////////////////////

---