CeylanFile.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the Ceylan library.
 *
 * The Ceylan library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The Ceylan library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and the GNU General Public License along with the Ceylan library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#ifndef CEYLAN_FILE_H_
#define CEYLAN_FILE_H_


#include "CeylanFileSystemCommon.h"    // for FileException and al
#include "CeylanSystem.h"              // for Size, SignedSize, etc.
#include "CeylanTypes.h"               // for Ceylan::Byte
#include "CeylanInputOutputStream.h"   // for inheritance

#include <string>




namespace Ceylan
{


    namespace System
    {

        
        /*
         * Each File child class is linked to a corresponding filesystem
         * manager child class.
         *
         */
        class FileSystemManager ;
        
        
        
        typedef Ceylan::Uint16 OpeningFlag ;



        typedef Ceylan::Uint16 PermissionFlag ;


        /*
         * As explained in CeylanFileSystemCommon.h, some file exceptions have
         * to be declared in that file and have to have a name starting with
         * 'File'. For the sake of homogeneity, other file exception declared
         * here also have a name like 'FileX', instead of being
         * declared as inner classes (ex: File::X').
         *
         * Note that exceptions associated to inherited methods
         * (InputOutputStream) cannot follow this rule.
         *
         */
         
         

        class CEYLAN_DLL FileReadLockingFailed: public FileException
        { 
            public: 
            
                explicit FileReadLockingFailed( const std::string & reason ) ; 
        } ;



        class CEYLAN_DLL FileReadUnlockingFailed: public FileException
        { 
            public: 
            
                explicit FileReadUnlockingFailed( const std::string & reason ) ;
        } ;



        class CEYLAN_DLL FileWriteLockingFailed: public FileException
        { 
            public: 
            
                explicit FileWriteLockingFailed( const std::string & reason ) ; 
        } ;



        class CEYLAN_DLL FileWriteUnlockingFailed: public FileException
        { 
            public: 
            
                explicit FileWriteUnlockingFailed( 
                    const std::string & reason ) ; 
        } ;



        class CEYLAN_DLL FileDelegatingException: public FileException
        { 
        
            public: 
            
                explicit FileDelegatingException( const std::string & reason ) ;
                    
        } ;
        



        class CEYLAN_DLL File: public InputOutputStream
        {
    

            public:



                // Allows read operations on the opened file. 
                static const OpeningFlag Read ;
                
                
                // Allows write operations on the opened file.
                static const OpeningFlag Write ;
                
                
                
                static const OpeningFlag CreateFile ;
                
                
                // Truncates file to length zero when opening.
                static const OpeningFlag TruncateFile ;
                
                
                // Seeks to the end of the file before each write operation.
                static const OpeningFlag AppendFile ;
                
                
                                
                // Opens the file in binary rather than in text mode.
                static const OpeningFlag Binary ;
                
                
                // Does not open the underlying file object.
                static const OpeningFlag DoNotOpen ;
                
                
                
                /*
                 * Creates the file for writing, it is a convenience 
                 * shortcut equal to the very common combination:
                 * 'Read | Write | CreateFile | TruncateFile | Binary'.
                 *
                 */
                static const OpeningFlag CreateToWriteBinary ;
                
                
                /*
                 * Opens the file for reading, it is a convenience 
                 * shortcut equal to the very common combination:
                 * 'Read | Binary'.
                 *
                 */
                static const OpeningFlag OpenToReadBinary ;
                
                                
                
                static const OpeningFlag NonBlocking ;
                
                
                
                static const OpeningFlag Synchronous ;
                
                


                /*
                 * Open flags for 'Owner'.
                 *
                 */


                static const PermissionFlag OwnerRead ;
                
                
                
                static const PermissionFlag OwnerWrite ;



                static const PermissionFlag OwnerExec ;
                
                
                
                static const PermissionFlag OwnerReadWrite ;
                
                

                static const PermissionFlag OwnerReadWriteExec ;
                



                /*
                 * Open flags for 'Group'.
                 *
                 * @note They are only taken into account if the advanced 
                 * file attribute feature is enabled.
                 *
                 */


                static const PermissionFlag GroupRead ;
                
                
                
                static const PermissionFlag GroupWrite ;


                static const PermissionFlag GroupExec ;
                
                
                
                static const PermissionFlag GroupReadWrite ;
                
                
                
                static const PermissionFlag GroupReadWriteExec ;
                


                /*
                 * Open flags for 'Others'.
                 *
                 * @note They are only taken into account if the advanced 
                 * file attribute feature is enabled.
                 *
                 */



                static const PermissionFlag OthersRead ;
                
                
                
                static const PermissionFlag OthersWrite ;



                static const PermissionFlag OthersExec ;
                
                
                
                static const PermissionFlag OthersReadWrite ;
                
                
                
                static const PermissionFlag OthersReadWriteExec ;
                
                            
                /*
                 * Static section.
                 *
                 * These methods encapsulate calls to the actual filesystem
                 * manager, so that the developer does not need to mess with
                 * platform-specific details and/or with the management of
                 * specialized filesystem managers. 
                 *
                 * Should a delegated operation fail, a FileException is
                 * thrown, including if the filesystem manager backend could 
                 * not be retrieved. In that case a more specialized exception
                 * is thrown, a FileDelegatingException.
                 *
                 */


                static bool ExistsAsFileOrSymbolicLink( 
                    const std::string & filename ) ;



                static bool Exists( const std::string & filename ) ;



                static void Remove( const std::string & filename ) ;
                
                
                
                static void Move( const std::string & sourceFilename,
                        const std::string & targetFilename ) ;



                static void Copy( const std::string & sourceFilename,
                        const std::string & targetFilename ) ;



                static Size GetSize( const std::string & filename ) ;



                static time_t GetLastChangeTime( 
                    const std::string & filename ) ;



                static std::string TransformIntoValidFilename( 
                    const std::string & rawFilename ) ;



                static void Touch( const std::string & filename ) ;



                static bool Diff( const std::string & firstFilename,
                        const std::string & secondFilename ) ;


                
                
                
                // Factory section.
                
        
                static File & Create( const std::string & filename, 
                    OpeningFlag createFlag = CreateToWriteBinary,
                    PermissionFlag permissionFlag = OwnerReadWrite ) ;

                
                
                static File & Open( const std::string & filename, 
                    OpeningFlag openFlag = OpenToReadBinary ) ;


                
                virtual ~File() throw() ;




                // Instance methods.


                const std::string & getName() const ;

                
                
                virtual bool isOpen() const = 0 ;
                
                
                
                virtual bool close() = 0 ;



                virtual void saveAs( const std::string & newName ) = 0 ;





                // Locking section.
                
                 
                 
                virtual void lockForReading() const ;



                virtual void unlockForReading() const ;



                virtual void lockForWriting() const ;



                virtual void unlockForWriting() const ;




                virtual bool isLocked() const ;




                virtual Size size() const ;



                virtual time_t getLastChangeTime() const = 0 ;



                virtual Size read( Ceylan::Byte * buffer, Size maxLength ) = 0 ;



                virtual void readExactLength( Ceylan::Byte * buffer, 
                        Size exactLength ) ;



                virtual bool hasAvailableData() const ;
                
                
                
                virtual Size write( const std::string & message ) = 0 ;



                virtual Size write( const Ceylan::Byte * buffer, 
                    Size maxLength ) = 0 ;



                virtual Position tell() = 0 ;



                virtual void seek( Position targetPosition ) = 0 ;



                virtual void open( OpeningFlag openFlag = CreateToWriteBinary, 
                    PermissionFlag permissionFlag = OwnerReadWrite ) ;



                virtual void remove() ;





                // Interface implementation.


                virtual StreamID getStreamID() const = 0 ;



                virtual StreamID getInputStreamID() const ;



                virtual StreamID getOutputStreamID() const ;



                virtual const std::string toString( 
                    Ceylan::VerbosityLevels level = Ceylan::high ) const ;



                static const Size UsualBufferSize ;
                
                
                static const Size BigBufferSize ;
                



            protected:



                explicit File( const std::string & name, 
                    OpeningFlag openFlag = CreateToWriteBinary,
                    PermissionFlag permissionFlag = OwnerReadWrite ) ;



                virtual FileSystemManager & getCorrespondingFileSystemManager()
                    const = 0 ;
                    


                virtual void reopen() = 0 ;


                virtual std::string interpretState() const = 0 ;



                std::string _name ;



                OpeningFlag _openFlag ;



                PermissionFlag _permissions ;


                bool _lockedForReading: 1, _lockedForWriting: 1 ;

                                

                static FileSystemManager & GetCorrespondingFileSystemManager() ;




            private:



                File( const File & source ) ;



                File & operator = ( const File & source ) ;

                

        } ;
        
        
    }

}



#endif // CEYLAN_FILE_H_

---