FileSystemManager.h

00001 /***************************************************************************
00002  *                                                                         *
00003  *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
00004  *       mailto: <tevs@mpi-sb.mpg.de>                                      *
00005  *                                                                         *
00006  *   This program is free software; you can redistribute it and/or modify  *
00007  *   it under the terms of the GNU General Public License as published by  *
00008  *   the Free Software Foundation; either version 2 of the License, or     *
00009  *   (at your option) any later version.                                   *
00010  *                                                                         *
00011  ***************************************************************************/
00012 
00013 
00014 #ifndef _NR_FILESYSTEM_H_
00015 #define _NR_FILESYSTEM_H_
00016 
00017 //----------------------------------------------------------------------------------
00018 // Includes
00019 //----------------------------------------------------------------------------------
00020 #include "Prerequisities.h"
00021 #include "IFileSystem.h"
00022 
00023 /**
00024 * @defgroup vfs Engine's filesystem
00025 *
00026 * NOT IMPLEMENTED AT NOW !!!!
00027 *
00028 * Files are storing the data needed for apropriate working of the engine and the
00029 * underlying application. Files could be found on the disk but also on external media
00030 * like ftp servers or similar things. You can either implement your own file
00031 * loading routines to load such external files or you use the engine's file system
00032 * which has the ability to be fully transparent to the user.
00033 *
00034 * Our filesystem contains a manger which does manage all available virtual file systems.
00035 * Each such virtual file system (vfs) can be either a local fs working on local files
00036 * or an http implementation of this one working on files in the internet. Each such
00037 * vfs is registerd by the manager, so it knows how to handle file requests.
00038 *
00039 * Files are requested through it's name. So just ask a manger to open a file with name A.ext
00040 * and it will ask each vfs if it does know such a file and ask them to open it. So for you
00041 * as user there is no difference if the file is found on the local disk or on a ftp server.
00042 * However transfering file data from external fs can be slow.
00043 *
00044 * If you know where the file is, you could also specify the file position directly, by
00045 * specifying the file location similar to "file:/A.ext" for local files and "ftp:/A.ext"
00046 * for external files. So the manager will ask that vfs thats type is specified for
00047 * appropriate file. This mechanism is very similar to unix one, so you should be familar with it.
00048 *
00049 * There can also be some parameters to the certain vfs specified in the file path. For
00050 * example you want to open a file on a certain ftp server and not the default one.
00051 * So calling something like this "ftp:server.domain:user:password:/A.ext" will force the
00052 * ftp-vfs to login on that server and download the file.
00053 *
00054 * We definy that all parameters given to the certain vfs systems should be separated by :
00055 * Which parameters can be given you can find in the documentation of each fs module.
00056 * There is no matter how much parameters you set, the filename must be at last.
00057 * i.e. "filesystem:param1:param2:..:paramn:/path/to/file/file.name"
00058 * The given filename is always in context to the filesystem. For example for local
00059 * files you specify relative path, for ftp-servers it is always absolute.
00060 * Filename-conventions are always according to the module you use. Our standard module
00061 * to load local files, does use simple convention that all file names are relative to the
00062 * application and the path is separated by slash. Conversion to windows filenames is
00063 * done by the modules automaticaly, so "file:d:/A.ext" refers to a file on disk d in windows.
00064 *
00065 *
00066 * In our engine you have a defualt filesystem which you can you
00067 * for your own puprose. The filesystem we are using is based on std::ifstream
00068 * so it is fully compatible to all system where std::ifstream works.
00069 * The filesystem is built in the way that it can easy be replaced through
00070 * plugins which can expand the functionality of the system.
00071 *
00072 * Each file in the system is also a resource which is managed by resource
00073 * manager. We do not want to separate the filesystem from resoure system
00074 * (as in many engine's does) because so we get the ability of simple user interface
00075 * and the possibility of controlling the files as resources (e.g. if they are
00076 * used in streams and can be un/loaded at runtime).
00077 *
00078 * If files are handled as resources you can also still able to manage your
00079 * memory without forgetting of counting of the size which each file has.
00080 * For example unstreamed file which is loaded completely in the memory does
00081 * use a lot of free memory. The resource according to the file for example an image
00082 * is working on that file. In a naive way you will get only the size of the image
00083 * counted and the file size wuold be not mentioned in the resource system. So
00084 * you didn't realy realize how much memory does your resource need. With the system
00085 * we are using you know that the complete size of the resource is the image object
00086 * and the file opened by it.
00087 *
00088 * Also the possibility of using files like resource does centralize the managment
00089 * of all opperations according to loading/unloading/removing. So you can also use
00090 * scripts and just load resource "File" which is handled like normal resource but
00091 * provides reading to the file.
00092 *
00093 * Our filesystem has also the possibility to add an archive support to the filesystem.
00094 * This could be done by appropriate plugin.
00095 *
00096 * Actually our current implementation of the engine allows us to add the filesystem
00097 * functionality to the engine by plugins. But because we must be able to read simple
00098 * files like config file which is loaded before all plugins, we must find the way
00099 * how to do this. So using of the filesystem as plugin is not possible.
00100 * But you are still able to add more supported file types (filesystems) through
00101 * plugins after this system is running.
00102 *
00103 * @see ResourceManager, IResource, IStream
00104 **/
00105 
00106 namespace nrEngine{
00107 
00108  //! File system manager class handles all filesystem transparent to the user
00109  /**
00110   * Engine's does use a file system manger to manage all available file systems.
00111   * This fs is called virtual file system or VFS. You as user of the engine does
00112   * use this vfs to get the data from files. The system is working transparent, so
00113   * you does not notice where the files are readed from.
00114   *
00115   * Each certain module should register by this manager so the user get access to the
00116   * file sstem provided by the module.
00117   *
00118   * \ingroup vfs
00119   **/
00120  class _NRExport FileSystemManager {
00121                 public:
00122 
00123                         //! Initilize the virtual file system so it can be now accessed
00124                         FileSystemManager();
00125 
00126                         //! Release used memory and force all modules to unload
00127                         ~FileSystemManager();
00128 
00129                         /**
00130                          * Register a new file system by the manager.
00131                          * The file systems are used to access the files
00132                          * 
00133                          * @param fs Smart pointer on the file system object
00134                          **/
00135                         Result addFilesystem(SharedPtr<IFileSystem> fs);
00136 
00137                         
00138                         /**
00139                          * Remove a certain filesystem from the list. This will unload
00140                          * the filesystem smart pointer, so if it not used anymore the filesystem
00141                          * will be removed from the memory. This should also close all opened files.
00142                          *
00143                          * @param name Name of the file system
00144                          **/
00145                         Result removeFilesystem(const std::string& name);
00146 
00147                         
00148                         /**
00149                          * Get the file system by it's type name.
00150                          *
00151                          * @param name Name of the file system
00152                          **/
00153                         SharedPtr<IFileSystem> getFilesystem(const std::string& name);
00154 
00155                         
00156                         /**
00157                          **/
00158 
00159 
00160                 private:
00161                         //! Map of registered file systems with their type names
00162                         typedef std::map< std::string, SharedPtr<IFileSystem> > FilesystemMap;
00163 
00164                         FilesystemMap mFilesystems;
00165 
00166                         
00167                         
00168         };
00169                                                                  
00170 };
00171 
00172 #endif

Generated on Wed Sep 12 23:19:42 2007 for nrEngine by  doxygen 1.5.1