(Formerly known as FileOpen, which is now obsolete)

static File* File.Open(string filename, FileMode)

MODE is either eFileRead, eFileWrite or eFileAppend, depending on whether you want to write to or read from the file. If you pass eFileWrite and a file called FILENAME already exists, it will be overwritten.

eFileAppend opens an existing file for writing and starts adding information at the end (ie. the existing contents are not deleted).

This function returns a File object, which you use to perform operations on the file. null is returned if there was a problem (eg. file not existing when MODE is eFileRead).

NOTE: You MUST close the file with the Close function when you have finished using it. There are only a limited number of file handles, and forgetting to close the file can lead to problems later on.

IMPORTANT: If you open the file for writing, then you can ONLY work with files in the game directory. You CANNOT use a path, so any filename with "" or "/" in it will automatically be rejected, for security reasons.

The only exception to this rule is the special tag $SAVEGAMEDIR$, which allows you to access files in the save game directory. This is especially important with the move to Windows Vista, in which you may not have access to the main game folder. You can use the $SAVEGAMEDIR$ tag to write and read files from the current Saved Game directory, which will always be writable. An example is below.

NOTE: Open file pointers are not persisted across save games. That is, if you open a file, then save the game; then when you restore the game, the File will not be usable and you'll have to open it again to continue any I/O. The safest practice is not to declare any global File variables.

Example:

File *output = File.Open("temp.tmp", eFileWrite);
if (output == null)
  Display("Error opening file.");
else {
  output.WriteString("test string");
  output.Close();
}

File *output = File.Open("$SAVEGAMEDIR$/temp.tmp", eFileWrite);
if (output == null)
  Display("Error opening file.");
else {
  output.WriteString("test string");
  output.Close();
}

See Also: File.Close, File.Exists, File.ReadStringBack, File.WriteString