File System
Updated 3,160 Days AgoPublic
Actions

Echo provides a file system abstraction. It provides automatic data source and storage selection based on the platform. The only requirement is that you use a FileSystem object that has been configured for the platform.

If you're using an Application a FileSystem object is created and configured using defaults. You can access it through Application::GetFileSystem().

If you're not using the Application class but still want to use platform defaults you can use the Platform interface to create a default FileSystem object for that platform see Platform::CreateDefaultFileSystem(). Normally you only need one object per application so it isn't necessarily to create one every time you need to use a FileSystem object.

We'll stick with the description of the default FileSystem objects that are created and assume you're using Application in our examples..

FIleSystem abstracts file access and, amongst other things, creates File objects features. These File objects have the usual read, write, seek etc functions as you might expect for a file interface. These objects are created by FileSystem when a file is opened. They maintain a reference (indirectly) to some concrete implementation of FileSystemSource. FileSystemSource is an abstract interface to a data source and you normally don't have to deal with them. I'm just mentioning it to explain that File accesses data through one of these interfaces.

A FileSystem object can be set up with any number of FileSystemSource objects. FileSystemSource objects are installed into the FileSystem object and one will be the default.

Each FileSystemSource is given an identifier which is used to specify that source when opening a file or performing some other operation. You specify sources by prefixing file paths/file names with identifier://. Here are some examples of opening a file:

//Open a file using the default source.
File aFile = GetFileSystem()->Open("resources/SomeText.txt");

//Open a file using the `file` source. See below about available sources.
File bFile = GetFileSystem()->Open("file://resources/SomeData.dat");

//Open a file using the `sd` source - Because in this case we know we're using the Wii platform and are happy to break portability.
File saveFile = GetFileSystem()->Open("sd://resources/MySaveFile.gamedata");

//Open a file and select the `persistent` source. See below about the persistent source.
File saveFile = GetFileSystem()->Open("persistent://resources/MySaveFile.gamedata");

Available sources

Now that you've got the general idea that FileSystem is an interface to data somewhere we need to cover how write code that doesn't need changing from platform to platform.

The simplest way to ensure you don't have to modify your file names to match the sources available on each platform is to use the default file source. The default file source is usually configured to be the best one for the target platform. You can be sure that the default will be at least readable. So specifying a file source is usually unnecessary unless you want to store data.

As a general rule treat the default file source as read only, although it doesn't have to be. The default source on some platforms may not be writeable though. For example, lets say you're building a game for a console and the console has optical media as the main way for you to distribute your game's data. It is most likely that this will be the selected default data source for that platform.

By default Echo's platform interfaces create FileSystem objects that include a persistent file source. This source can be used to save data. So good practise is to read data using the default source and save data to the persistent source.

Persistent source

The persistent source can be specified using persistent:// as a prefix to your file path. If a platform does not support storing data then this source will not be available and the returned object when attempting to open the file won't be an open.

On some platforms the persistent storage may change depending on what storage options are available. It is not within the scope of this document to explain all platform variations though. Have a look at the platform's documentation to find out where data will be saved.