6: File References

You deal with disk files using file references. Each fileref is an opaque C structure pointer; see section 1.6, "Opaque Objects".

A file reference contains platform-specific information about the name and location of the file, and possibly its type, if the platform has a notion of file type. It also includes a flag indication whether the file is a text file or binary file. [Note that this is different from the standard C I/O library, in which you specify text or binary mode when the file is opened.]

A fileref does not have to refer to a file which actually exists. You can create a fileref for a nonexistent file, and then open it in write mode to create a new file.

You always provide a usage argument when you create a fileref. The usage is a mask of constants to indicate the file type and the mode (text or binary.) These values are used when you create a new file, and also to filter file lists when the player is selecting a file to load. The constants are as follows:

• fileusage_SavedGame: A file which stores game state.
• fileusage_Transcript: A file which contains a stream of text from the game (often an echo stream from a window.)
• fileusage_InputRecord: A file which records player input.
• fileusage_Data: Any other kind of file (preferences, statistics, arbitrary data.)

• fileusage_BinaryMode: The file contents will be stored exactly as they are written, and read back in the same way. The resulting file may not be viewable on platform-native text file viewers.
• fileusage_TextMode: The file contents will be transformed to a platform-native text file as they are written out. Newlines may be converted to linefeeds or linefeed-plus-carriage-return combinations; Latin-1 characters may be converted to native character codes. When reading a file in text mode, native line breaks will be converted back to newline (0x0A) characters, and native character codes may be converted to Latin-1. [Line breaks will always be converted; other conversions are more questionable. If you write out a file in text mode, and then read it back in text mode, high-bit characters (128 to 255) may be transformed or lost.]

In general, you should use text mode if the player expects to read the file with a platform-native text editor; you should use binary mode if the file is to be read back by your program, or if the data must be stored exactly. Text mode is appropriate for fileusage_Transcript; binary mode is appropriate for fileusage_SavedGame and probably for fileusage_InputRecord. fileusage_Data files may be text or binary, depending on what you use them for.

6.1: The Types of File References

There are four different functions for creating a fileref, depending on how you wish to specify it. Remember that it is always possible that a fileref creation will fail and return NULL.

frefid_t glk_fileref_create_temp(glui32 usage, glui32 rock);

This creates a reference to a temporary file. It is always a new file (one which does not yet exist). The file (once created) will be somewhere out of the player's way. [This is why no name is specified; the player will never need to know it.]

A temporary file should not be used for long-term storage. It may be deleted automatically when the program exits, or at some later time, say when the machine is turned off or rebooted. You do not have to worry about deleting it yourself.

frefid_t glk_fileref_create_by_prompt(glui32 usage, glui32 fmode, glui32 rock);

This creates a reference to a file by asking the player to locate it. The library may simply prompt the player to type a name, or may use a platform-native file navigation tool. (The prompt, if any, is inferred from the usage argument.)

fmode must be one of these values:

• filemode_Read: The file must already exist; the player will be asked to select from existing files which match the usage.
• filemode_Write: The file should not exist; if the player selects an existing file, he will be warned that it will be replaced.
• filemode_ReadWrite: The file may or may not exist; if it already exists, the player will be warned that it will be modified.
• filemode_WriteAppend: Same behavior as filemode_ReadWrite.

The fmode argument should generally match the fmode which will be used to open the file.

[It is possible that the prompt or file tool will have a "cancel" option. If the player chooses this, glk_fileref_create_by_prompt() will return NULL. This is a major reason why you should make sure the return value is valid before you use it.]

frefid_t glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock);

This creates a reference to a file with a specific name. The file will be in a fixed location relevant to your program, and visible to the player. [This usually means "in the same directory as your program."]

Since filenames are highly platform-specific, you should use glk_fileref_create_by_name() with care. It is legal to pass any string in the name argument. However, the library may have to mangle, transform, or truncate the string to make it a legal native filename. [For example, if you create two filerefs with the names "File" and "FILE", they may wind up pointing to the same file; the platform may not support case distinctions in file names. Another example: on a platform where file type is specified by filename suffix, the library will add an appropriate suffix based on the usage; any suffix in the string will be overwritten or added to. For that matter, remember that the period is not a legal character in Acorn filenames...]

The most conservative approach is to pass a string of no more than 8 characters, consisting entirely of upper-case letters and numbers, starting with a letter. You can then be reasonably sure that the resulting filename will display all the characters you specify -- in some form.

frefid_t glk_fileref_create_from_fileref(glui32 usage, frefid_t fref, glui32 rock);

This copies an existing file reference, but changes the usage. (The original fileref is not modified.)

The use of this function can be tricky. If you change the type of the fileref (fileusage_Data, fileusage_SavedGame, etc), the new reference may or may not point to the same actual disk file. [This generally depends on whether the platform uses suffixes to indicate file type.] If you do this, and open both file references for writing, the results are unpredictable. It is safest to change the type of a fileref only if it refers to a nonexistent file.

If you change the mode of a fileref (fileusage_TextMode, fileusage_BinaryMode), but leave the rest of the type unchanged, the new fileref will definitely point to the same disk file as the old one.

Obviously, if you write to a file in text mode and then read from it in binary mode, the results are platform-dependent.

6.2: Other File Reference Functions

void glk_fileref_destroy(frefid_t fref);

Destroys a fileref which you have created. This does not affect the disk file; it just reclaims the resources allocated by the glk_fileref_create... function.

It is legal to destroy a fileref after opening a file with it (while the file is still open.) The fileref is only used for the opening operation, not for accessing the file stream.

frefid_t glk_fileref_iterate(frefid_t fref, glui32 *rockptr);

This iterates through all the existing filerefs. See section 1.6.2, "Iterating Through Opaque Objects".

glui32 glk_fileref_get_rock(frefid_t fref);

This retrieves the fileref's rock value. See section 1.6.1, "Rocks".

void glk_fileref_delete_file(frefid_t fref);

This deletes the file referred to by fref. It does not destroy the fileref itself.

glui32 glk_fileref_does_file_exist(frefid_t fref);

This returns TRUE (1) if the fileref refers to an existing file, and FALSE (0) if not.