Difference between revisions of "HOWTO-Open Files"

* However, do *not* use (absolute) paths with File::open()!

* an FSNode is kind of a "portable path". If you need to process a path (e.g. coming from the config file), first create an FSNode from it, then use that for whatever you need to (e.g. pass the FSNode to File::open)

*Most of you can simply keep using class Common::File as before. The main changes in it:

**You must not pass absolute paths to <tt>File::open()</tt>! If you must open a file using a path, the correct way is to first create an FSNode from the path, then pass that to File::open.

**You can pass relative paths in a limited fashion; you must use the "/" character as separator. I am too lazy to provide details on this right now; but check out the doxygen docs of class FSDirectory.

**There are new File::open methods: You can pass an "Archive" subclass (e.g. a ZIPArchive) to it, and it will search for that file in the Archive)

<syntax type="C++">  Common::File *f = new Common::File;

  if (f && f->open(node))

  else {

   }</syntax>

<syntax type="C++">  return node.openForReading();</syntax>

You can also invoke the SearchManager directly to open a file with a specific name, but looking for it in various places (the game path, extrapath, DATADIR, current dir, etc.): SearchMan::openFile(filename). This is almost exactly what File::open(String) does, only that the later also tries to open the filename with a dot appened. I.e. if you do

<syntax type="C++"> file.open("foo")</syntax>

then if it can't find "foo", it also tries to open "foo." (this is to workaround problems on some systems, where an old DOS file without an extension incorrectly may get a dot appended when copying it). If you don't need this extra lookup, and if you may want to use the Stream directly, instead of wrapping it in a Common::File instance, you can use the SearchMan directly. To continue my example from above, instead of

<syntax type="C++">  Common::File *f = new Common::File;

  if (f && f->open(filename))

you could now do this instead (with almost identical meaning, except for the "trailing dot" hack):

<syntax type="C++">  return SearchMan.openFile(filename);</syntax>

Finally, you can creat FSNodes from "paths". Caveat: You may not assume anything about the path format, like what the separator char is; in fact, there may not even exist the *concept* of a path separator on the target system. Hence, the only valid way to do that is to feed a "path" created by another FSNode to this FSNode. I.e. you can "serialize" an FSNode to a path, via the FSNode::getPath() method, then write that to a config file. Later, you read it back in, and create a new FSNode from it. That works fine, as long as you stay on the same OS / platform.

Warning: a "path" as returned by FSNode::getPath should *not* be passed to File::open(). If you want to open a file at a specific path, first create an FSNode from it, then use that to open the file.