17 Feb 2007

The Nebula3 IO subsystem: URIs and Assigns

Nebula3 uses URIs (Uniform Resource Identifiers) instead of simple filename strings to locate IO resources. URI objects are usually created like this:

using namespace IO;
URI webUri("http://www.myhttpserver.com/index.html");
URI localUri("file:///c:/temp/text.txt");
The first URI points to a file on an HTTP server, the second URI points to a file in the local file system. When an URI object is created, it is parsed and split into its components:
  • the scheme (for instance "http", or "file")
  • the host ("www.myhttpserver.com")
  • the local path ("index.html", or "c:/temp/text.txt")
URIs may also contain additional information:
  • user info: describes login information for a secure service
  • port number: describes a network port number
  • fragment: usually describes a location inside an HTML file
  • query: a set of key/value pairs often used by web services
Nebula3 has built-in support for the "file:" and "http:" schemes already. "ftp:" support is planned for the near future.

For instance, to copy a file from a HTTP server into a local file system you could do somethis like this:

URI from("http://www.radonlabs.de/index.html");
URI to("file:///c:/temp/index.html");
IO::Server::Instance()->CopyFile(from, to);
Assigns have already been used since Nebula1 (actually the concept and name stems from the original Amiga OS back in the 80's), they are aliases (or shortcuts) for file system locations and very handy to abstract the actual location of files in a Nebula application.

For instance, instead of "C:/Program Files/MyApp/export/textures/category/mytexture.dds", you would simply use "textures:mycategory/mytexture.dds". The assign "textures:" would be defined as "C:/Programme/MyApp/export/textures".

Assigns are especially useful to describe locations like the application's installation directory or the user directory of the currently logged in user. For this reason, Nebula3 defines a few standard assigns which are initialized at application startup:
  • home: this points to the application's install directory
  • bin: this points to the directory where the application executable resides
  • temp: this points to a scratch directory which is guaranteed to be readable and writable for the current user
  • user: this points to the user directory, in an English Windows, this is for example "My Files/CompanyName/AppName". The user: directory is guaranteed to be writable (unlike the installation directory), and this is the place where config data or save game files should reside.
In Nebula3, Assigns have been extended to work with URIs. For instance, the "textures:" assign could be defined as "http://www.radonlabs.de/myapp/textures", which would automatically cause textures to be loaded from a http server instead of the local file system. Assigns can be nested, so for instance the "textures:" assign could also be set to "home:export/textures", which would automatically resolve to the location "export/textures" in the installation directory.