source: nrEngine/include/FileSystemManager.h @ 1

Revision 1, 7.7 KB checked in by art, 13 years ago (diff)
2 *                                                                         *
3 *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
4 *       mailto: <>                                      *
5 *                                                                         *
6 *   This program is free software; you can redistribute it and/or modify  *
7 *   it under the terms of the GNU General Public License as published by  *
8 *   the Free Software Foundation; either version 2 of the License, or     *
9 *   (at your option) any later version.                                   *
10 *                                                                         *
11 ***************************************************************************/
14#ifndef _NR_FILESYSTEM_H_
15#define _NR_FILESYSTEM_H_
18// Includes
20#include "Prerequisities.h"
21#include "IFileSystem.h"
24* @defgroup vfs Engine's filesystem
28* Files are storing the data needed for apropriate working of the engine and the
29* underlying application. Files could be found on the disk but also on external media
30* like ftp servers or similar things. You can either implement your own file
31* loading routines to load such external files or you use the engine's file system
32* which has the ability to be fully transparent to the user.
34* Our filesystem contains a manger which does manage all available virtual file systems.
35* Each such virtual file system (vfs) can be either a local fs working on local files
36* or an http implementation of this one working on files in the internet. Each such
37* vfs is registerd by the manager, so it knows how to handle file requests.
39* Files are requested through it's name. So just ask a manger to open a file with name A.ext
40* and it will ask each vfs if it does know such a file and ask them to open it. So for you
41* as user there is no difference if the file is found on the local disk or on a ftp server.
42* However transfering file data from external fs can be slow.
44* If you know where the file is, you could also specify the file position directly, by
45* specifying the file location similar to "file:/A.ext" for local files and "ftp:/A.ext"
46* for external files. So the manager will ask that vfs thats type is specified for
47* appropriate file. This mechanism is very similar to unix one, so you should be familar with it.
49* There can also be some parameters to the certain vfs specified in the file path. For
50* example you want to open a file on a certain ftp server and not the default one.
51* So calling something like this "ftp:server.domain:user:password:/A.ext" will force the
52* ftp-vfs to login on that server and download the file.
54* We definy that all parameters given to the certain vfs systems should be separated by :
55* Which parameters can be given you can find in the documentation of each fs module.
56* There is no matter how much parameters you set, the filename must be at last.
57* i.e. "filesystem:param1:param2:..:paramn:/path/to/file/"
58* The given filename is always in context to the filesystem. For example for local
59* files you specify relative path, for ftp-servers it is always absolute.
60* Filename-conventions are always according to the module you use. Our standard module
61* to load local files, does use simple convention that all file names are relative to the
62* application and the path is separated by slash. Conversion to windows filenames is
63* done by the modules automaticaly, so "file:d:/A.ext" refers to a file on disk d in windows.
66* In our engine you have a defualt filesystem which you can you
67* for your own puprose. The filesystem we are using is based on std::ifstream
68* so it is fully compatible to all system where std::ifstream works.
69* The filesystem is built in the way that it can easy be replaced through
70* plugins which can expand the functionality of the system.
72* Each file in the system is also a resource which is managed by resource
73* manager. We do not want to separate the filesystem from resoure system
74* (as in many engine's does) because so we get the ability of simple user interface
75* and the possibility of controlling the files as resources (e.g. if they are
76* used in streams and can be un/loaded at runtime).
78* If files are handled as resources you can also still able to manage your
79* memory without forgetting of counting of the size which each file has.
80* For example unstreamed file which is loaded completely in the memory does
81* use a lot of free memory. The resource according to the file for example an image
82* is working on that file. In a naive way you will get only the size of the image
83* counted and the file size wuold be not mentioned in the resource system. So
84* you didn't realy realize how much memory does your resource need. With the system
85* we are using you know that the complete size of the resource is the image object
86* and the file opened by it.
88* Also the possibility of using files like resource does centralize the managment
89* of all opperations according to loading/unloading/removing. So you can also use
90* scripts and just load resource "File" which is handled like normal resource but
91* provides reading to the file.
93* Our filesystem has also the possibility to add an archive support to the filesystem.
94* This could be done by appropriate plugin.
96* Actually our current implementation of the engine allows us to add the filesystem
97* functionality to the engine by plugins. But because we must be able to read simple
98* files like config file which is loaded before all plugins, we must find the way
99* how to do this. So using of the filesystem as plugin is not possible.
100* But you are still able to add more supported file types (filesystems) through
101* plugins after this system is running.
103* @see ResourceManager, IResource, IStream
106namespace nrEngine{
108 //! File system manager class handles all filesystem transparent to the user
109 /**
110  * Engine's does use a file system manger to manage all available file systems.
111  * This fs is called virtual file system or VFS. You as user of the engine does
112  * use this vfs to get the data from files. The system is working transparent, so
113  * you does not notice where the files are readed from.
114  *
115  * Each certain module should register by this manager so the user get access to the
116  * file sstem provided by the module.
117  *
118  * \ingroup vfs
119  **/
120 class _NRExport FileSystemManager {
121                public:
123                        //! Initilize the virtual file system so it can be now accessed
124                        FileSystemManager();
126                        //! Release used memory and force all modules to unload
127                        ~FileSystemManager();
129                        /**
130                         * Register a new file system by the manager.
131                         * The file systems are used to access the files
132                         *
133                         * @param fs Smart pointer on the file system object
134                         **/
135                        Result addFilesystem(SharedPtr<IFileSystem> fs);
138                        /**
139                         * Remove a certain filesystem from the list. This will unload
140                         * the filesystem smart pointer, so if it not used anymore the filesystem
141                         * will be removed from the memory. This should also close all opened files.
142                         *
143                         * @param name Name of the file system
144                         **/
145                        Result removeFilesystem(const std::string& name);
148                        /**
149                         * Get the file system by it's type name.
150                         *
151                         * @param name Name of the file system
152                         **/
153                        SharedPtr<IFileSystem> getFilesystem(const std::string& name);
156                        /**
157                         **/
160                private:
161                        //! Map of registered file systems with their type names
162                        typedef std::map< std::string, SharedPtr<IFileSystem> > FilesystemMap;
164                        FilesystemMap mFilesystems;
168        };
Note: See TracBrowser for help on using the repository browser.