[Scummvm-devel] New File(Manager) API

[Max Horn]

Yo folks,

finally got around to sketch down a draft of how a revised File API 
could look like. You can find the (non-working, not syntax checked 
etc.) draft in the form of a header file attached to this mail. Note 
that this is an early draft, nothing is set in stone. Feel free to 
voice your thoughts and criticism. If you don't understand something, 
I'll try to explain, just ask.

Be warned: If I get no negative feedback, I'll probably implement this 
eventually, so don't complain then, complain now :-)


There are three parts to this:

1) ReadStream & WriteStream interfaces and subclasses which implement 
them.
   These are meant to abstract away reading/writing from "streams", 
which can be files, or memory buffers, or anything else you might come 
up with. The File class implements both. And there is a XORReadStream 
which wraps around any ReadStream, adding "XOR encryption" to that 
stream (which can be used by the SCUMM frontend, and allows us to get 
rid of the SCUMM specific XOR encryption code in the File class)
These are actually mostly independent of my other changes. I'd like to 
see those (or a variation of them) in whether we do the rest or not. 
They'll allow us to unify the code in sound/voc.cpp, for example.


2) A new FilePath class. Similar to the Java "File" class, and a 
successor to FilesystemNode, this class stores an abstract "file path", 
i.e. the location of a file system node. That location can exist, but 
doesn't have to. It can be a file, a directory, or something else, like 
a slot on a memory card. Look at the attached file to get the idea.  
Ideally, all our code will be converted to use this.
For browsing the file system, there is the static FilePath::listRoots() 
method. To replace the savegame manager, there is a 
FilePath::getSavegameDir() method. Since the actual implementation of 
FilePath can change depending on the backend, this makes it possible to 
have a "special" savegame dir, which isn't a real directory but rather 
represents a specific memory card or something similar.
FilePath also allows querying a file for various properties, like 
whether it exists, what kind of file/directory it is, the file size, 
file name etc.

3) A new File class. You don't instantiate those directly anymore, 
rather you have to use a FilePath and use the makeFile() method of it. 
This makes it possible to instantiate different File subclasses 
depending on the backend, or on the file's location (special treatment 
for save files, for example).


For the backend maintainer, I hope it will be relatively simple to 
implement a custom FilePath / File implementation (at least not harder 
than the current FilesystemNode stuff). For the client of the new code, 
it should be relatively simple to deal with paths portably. Bbasically, 
instead of dealing with raw path strings, you use an intermediate 
object, which is very very easy to use. Consider this:
   FilePath filename("MONKEY.000");
   if (filename.exists()) {
      printf("File %s is %d bytes big\n", filename.getName().c_str(), 
filename.getSize());
      File *file = filename.makeFile()
      file->readByte();
      delete file;
   }

The thing which is a bit more complicated is that you can't create File 
instances directly on the stack anymore. If that is bothering people a 
lot, it wouldn't be too hard to "Fix" this, though. Just tell me.

Search path handling would also be very easy, I provided a convenience 
method tryOpenFile(), which does it. You can use it like this:

   PathList searchPaths;
   const char *dirs[] = { "", "video", "VIDEO", "data/", "DATA/", ..., 0 
};
   int i = 0;
   while (dirs[i]) {
     FilePath path(dirs[i]);
     if (path.exists() && path.isDirectory()) {
       searchPaths.push_back(path);
     }
   }
   ...
   File *myFile = tryOpen("MONKEY.000", searchPaths, kFileReadMode);
   if (!myFile)
     error("Couldn't open MONKEY.000");
   byte firstByte = myFile->readByte();
   ...

Of course the computation of "searchPaths" only has to be done once.



Cheers,

Max
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: newfile.h
URL: <http://lists.scummvm.org/pipermail/scummvm-devel/attachments/20040410/cbe0e082/attachment.h>