Cross-Platform C++

ot::io
class FileSystem  (abstract)

#include "ot/io/FileSystem.h"

ot::ManagedObject An abstract base class representing a file system. This documentation is provided to aid installations that wish to implement their own customized FileSystem. FileSystem methods should not normally be called directly, use the methods on the File class instead.

OpenTop treats file pathnames and handles as abstract data types which only have meaning when combined with a FileSystem object.

A FileSystem knows how pathnames are constructed and how relative pathnames can be combined to create an absolute pathname. A FileSystem also knows how to perform file i/o, with the consequence that all OpenTop file i/o is delegated to a FileSystem object.

There can be more than one FileSystem object, each one representing different file systems supported by the target platform. However, there can be only one global FileSystem. The global FileSystem is used by most OpenTop classes that have to resolve or open files using abstract pathnames.

The global FileSystem object can be set by applications by use of the SetFileSystem() method.

OpenTop provides concrete FileSystem implementations that are adequate for most circumstances.




Method Summary
 virtual String canonicalize(const String& path) const
         Returns a canonical form of path.
 virtual bool checkAccess(const String& path, AccessMode mode) const=0
         Tests if file path can be opened with the specified mode.
 virtual void closeFile(FileDescriptor* pFD) const=0
         Closes the file specified by the FileDescriptor pFD.
 virtual void createDirectory(const String& path) const=0
         Creates a directory.
 virtual void deleteFile(const String& path) const=0
         Deletes the named file or directory from the file system.
 virtual RefPtr< FileDescriptor > getConsoleFD(ConsoleStream stream) const=0
         Returns a FileDescriptor for one of the standard Console streams.
 virtual String getCurrentDirectory() const=0
         Returns the current directory for the active process.
 virtual int getFileAttributeFlags(const String& path) const=0
         Returns an integer used as a bit field, each bit representing a file attribute.
static RefPtr< FileSystem > GetFileSystem()
         Returns a reference to the global FileSystem object.
 virtual DateTime getLastModifiedTime(const String& path) const=0
         Returns the time the file was last modified.
 virtual size_t getLength(const String& path) const=0
         Returns the length (in bytes) of the file.
 virtual size_t getPrefixLength(const String& path) const=0
         Returns the length of the prefix of an abstract path name.
 virtual String getSeparator() const
         Returns the separator character as a String.
 virtual CharType getSeparatorChar() const=0
         Returns the character which is used to separate the parts of a hierarchical path name.
 virtual bool isAbsolute(const String& path) const=0
         Tests if path represents an absolute file name.
 virtual bool isCaseSensitive() const=0
         Tests if the FileSystem represents files in a case-sensitive manner.
 virtual std::list< String > listDirectory(const String& path) const=0
         Returns a list of the files contained within a directory.
 virtual String normalize(const String& path) const
         Converts a pathname into normalized form.
 virtual RefPtr< FileDescriptor > openFile(const String& path, int accessMode, CreationDisp creationDisp, int attributes) const=0
         Opens a file and returns a FileDescriptor representing the open file.
 virtual size_t readFile(FileDescriptor* pFD, Byte* pBuffer, size_t bufLen) const=0
         Reads up to bufLen bytes from an open file into the supplied buffer.
 virtual void rename(const String& path1, const String& path2) const=0
         Renames a file.
 virtual String resolve(const String& path) const
         Resolve a relative pathname.
 virtual String resolve(const String& parent, const String& child) const
         Resolves a relative child pathname against a parent pathname to create an absolute pathname.
static void SetFileSystem(FileSystem* pFileSystem)
         Sets the global FileSystem object.
 virtual void setLastModifiedTime(const String& path, const DateTime& time) const=0
         Updates the date and time a file was last modified.
 virtual void setReadOnly(const String& path, bool bReadOnly) const=0
         Changes a file's access permissions to be 'read only'.
 virtual void writeFile(FileDescriptor* pFD, const Byte* pBuffer, size_t bufLen) const=0
         Writes an array of bytes to an open file.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Enumerations

enum { EndOfFile =-1}  /* end of file reached */ 



enum AccessMode { ReadAccess = 0x01,  /* Request read access */ 
  WriteAccess = 0x02}  /* Request write access */ 



enum Attribute { Exists = 0x01,  /* File exists */ 
  RegularFile = 0x02,  /* A regular file i.e. not a directory */ 
  Directory = 0x04,  /* File is a directory */ 
  Hidden = 0x08,  /* File is hidden */ 
  ReadOnly = 0x10}  /* File is read-only for the current process */ 



enum ConsoleStream { Stdin = 0,  /* standard input */ 
  Stdout = 1,  /* standard output */ 
  Stderr = 2}  /* standard error */ 



enum CreationDisp { OpenExisting /* open existing file only */ 
  OpenCreateAppend /* open existing or create new, preserve existing contents */ 
  OpenCreateExclusive /* create non-existing file only */ 
  OpenCreateTruncate /* open existing or create new, destroy existing contents */ 


Method Detail

canonicalize

virtual String canonicalize(const String& path) const
Returns a canonical form of path. The canonical form of a file path name gives the shortest possible name that can uniquely identify the file. The canonical form is obtained by resolving the path and passing the result to File::GetCanonicalPath().

For example, the canonical form of the path docs/../images/image1.jpg may be /home/http/images/image1.jpg if /home/http/ is the current directory.

See also:
File::GetCanonicalPath()

checkAccess

virtual bool checkAccess(const String& path,
                         AccessMode mode) const=0
Tests if file path can be opened with the specified mode.

Returns:
true if the file can be opened with the mode requested; false otherwise

closeFile

virtual void closeFile(FileDescriptor* pFD) const=0
Closes the file specified by the FileDescriptor pFD.


createDirectory

virtual void createDirectory(const String& path) const=0
Creates a directory.


deleteFile

virtual void deleteFile(const String& path) const=0
Deletes the named file or directory from the file system. Directories must be empty before they can be deleted.

Exceptions:
FileNotFoundException - if the file does not exist
IOException - if an error occurs deleting the file

getConsoleFD

virtual RefPtr< FileDescriptorgetConsoleFD(ConsoleStream stream) const=0
Returns a FileDescriptor for one of the standard Console streams.


getCurrentDirectory

virtual String getCurrentDirectory() const=0
Returns the current directory for the active process.


getFileAttributeFlags

virtual int getFileAttributeFlags(const String& path) const=0
Returns an integer used as a bit field, each bit representing a file attribute. The bit values are designated by the enum FileSystem::Attribute.


GetFileSystem

static RefPtr< FileSystem > GetFileSystem()
Returns a reference to the global FileSystem object. If a global FileSystem has not yet been registered, a default FileSystem is created. This is platform-dependent and is suitable for most applications.

See also:
SetFileSystem()

getLastModifiedTime

virtual DateTime getLastModifiedTime(const String& path) const=0
Returns the time the file was last modified.

Exceptions:
FileNotFoundException - if the file does not exist
IOException - if an error occurs accessing the file

getLength

virtual size_t getLength(const String& path) const=0
Returns the length (in bytes) of the file.

Exceptions:
FileNotFoundException - if the file does not exist
IOException - if an error occurs accessing the file

getPrefixLength

virtual size_t getPrefixLength(const String& path) const=0
Returns the length of the prefix of an abstract path name. See File for a description of abstract pathnames.


getSeparator

virtual String getSeparator() const
Returns the separator character as a String.

See also:
getSeparatorChar()

getSeparatorChar

virtual CharType getSeparatorChar() const=0
Returns the character which is used to separate the parts of a hierarchical path name.


isAbsolute

virtual bool isAbsolute(const String& path) const=0
Tests if path represents an absolute file name.

Returns:
true if path is absolute; false otherwise

isCaseSensitive

virtual bool isCaseSensitive() const=0
Tests if the FileSystem represents files in a case-sensitive manner. Unix/Linux systems are usually case-sensitive whereas Windows is not.


listDirectory

virtual std::list< StringlistDirectory(const String& path) const=0
Returns a list of the files contained within a directory.


normalize

virtual String normalize(const String& path) const
Converts a pathname into normalized form. The normalized form uses a platform-dependent filename separator character. Contiguous separator characters (following the system-dependent prefix) are replaced with a single one and trailing separator characters are removed.

Parameters:
path - the pathname to normalize

openFile

virtual RefPtr< FileDescriptoropenFile(const String& path,
                                          int accessMode,
                                          CreationDisp creationDisp,
                                          int attributes) const=0
Opens a file and returns a FileDescriptor representing the open file.

Exceptions:
IOException - if an error occurs opening the file

readFile

virtual size_t readFile(FileDescriptor* pFD,
                        Byte* pBuffer,
                        size_t bufLen) const=0
Reads up to bufLen bytes from an open file into the supplied buffer.

Parameters:
pBuffer - A pointer to the buffer into which the bytes will be copied. This must be capable of holding at least bufLen bytes.
bufLen - The maximum number of bytes to read into the passed buffer.
Returns:
The number of bytes read or zero if the end of the file has been reached.
Exceptions:
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an I/O error occurs

rename

virtual void rename(const String& path1,
                    const String& path2) const=0
Renames a file.


resolve

virtual String resolve(const String& path) const
Resolve a relative pathname. In the normal case a relative pathname is resolved against the current directory. On the UNIX platform this is always the case. On Windows platforms, a relative pathname is resolved against the current directory unless it starts with the separator character, in which case it is resolved against the root of the current drive.


resolve

virtual String resolve(const String& parent,
                       const String& child) const
Resolves a relative child pathname against a parent pathname to create an absolute pathname. If child is already absolute, a normalized form of child is returned without attempting to resolve it further.

Parameters:
parent - a directory name to resolve the child pathname against. The directory name need not exist in the file system.
child - a relative or absolute pathname. If child is a relative pathname it is made absolute by resolving it against parent

SetFileSystem

static void SetFileSystem(FileSystem* pFileSystem)
Sets the global FileSystem object. The global FileSystem is used to open files and resolve filenames.

To ensure that the passed object exists for as long as the application needs it, the FileSystem object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination.

See also:
GetFileSystem()
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

setLastModifiedTime

virtual void setLastModifiedTime(const String& path,
                                 const DateTime& time) const=0
Updates the date and time a file was last modified.


setReadOnly

virtual void setReadOnly(const String& path,
                         bool bReadOnly) const=0
Changes a file's access permissions to be 'read only'.


writeFile

virtual void writeFile(FileDescriptor* pFD,
                       const Byte* pBuffer,
                       size_t bufLen) const=0
Writes an array of bytes to an open file.

Parameters:
pBuffer - pointer to the start of an array of bytes to be written
bufLen - length of the byte array
Exceptions:
NullPointerException - if pBuffer is null.
IOException - if an I/O error occurs.


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements