All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.ifarchive.glk.FileRef 

java.lang.Object
   |
   +----org.ifarchive.glk.OpaqueObject
           |
           +----org.ifarchive.glk.FileRef
public class FileRef
extends OpaqueObject
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.

See Also:
File

Variable Index

o filemode_Read
Open the file this refers to in read mode.
o filemode_ReadWrite
Open the file this refers to in read/write mode.
o filemode_Write
Open the file this refers to in write mode.
o filemode_WriteAppend
Open the file this refers to in append mode.
o fileusage_BinaryMode
Open the file this refers to in binary mode.
o fileusage_Data
This file stores arbitrary data (preferences, statistics...)
o fileusage_InputRecord
This file stores a recording of player input.
o fileusage_SavedGame
This file stores a saved game.
o fileusage_TextMode
Open the file this refers to in text mode.
o fileusage_Transcript
This file stores a stream of text from the game.
o fileusage_TypeMask
Mask for file type bits.

Method Index

o createByName(int, String)
Create a reference to a file with a specific name.
o createByName(int, String, Object)
Create a reference to a file with a specific name.
o createByPrompt(int, int)
Create a file reference by asking the player to type a name.
o createByPrompt(int, int, Object)
Create a file reference by asking the player to type a name.
o createFromFileRef(int)
This copies an existing file reference, but changes the usage.
o createFromFileRef(int, Object)
This copies an existing file reference, but changes the usage.
o createTemp(int, Object)
This creates a reference to a temporary file.
o deleteFile()
This deletes the file this FileRef refers to.
o destroy()
Destroys a fileref which you have created.
o doesFileExist()
See if this fileref refers to an existing file.
o finalize()
If the Glk object is still in existence when this object is garbage-collected, destroy it.
o iterate(FileRef, Object[])
Iterate over file references.
o openFile(int)
Open a stream on the file this refers to.
o openFile(int, Object)
Open a stream on the file this refers to.

Variables

o fileusage_Data 
 public static final int fileusage_Data
This file stores arbitrary data (preferences, statistics...)

o fileusage_SavedGame 
 public static final int fileusage_SavedGame
This file stores a saved game.

o fileusage_Transcript 
 public static final int fileusage_Transcript
This file stores a stream of text from the game.

o fileusage_InputRecord 
 public static final int fileusage_InputRecord
This file stores a recording of player input.

o fileusage_TypeMask 
 public static final int fileusage_TypeMask
Mask for file type bits.

o fileusage_TextMode 
 public static final int fileusage_TextMode
Open the file this refers to in text mode.

o fileusage_BinaryMode 
 public static final int fileusage_BinaryMode
Open the file this refers to in binary mode.

o filemode_Write 
 public static final int filemode_Write
Open the file this refers to in write mode.

o filemode_Read 
 public static final int filemode_Read
Open the file this refers to in read mode.

o filemode_ReadWrite 
 public static final int filemode_ReadWrite
Open the file this refers to in read/write mode.

o filemode_WriteAppend 
 public static final int filemode_WriteAppend
Open the file this refers to in append mode.

Methods

o iterate 
 public static FileRef iterate(FileRef f,
                               Object r[])
Iterate over file references.

See Also:
iterate
o createByPrompt 
 public static FileRef createByPrompt(int usage,
                                      int mode)
Create a file reference by asking the player to type a name.

Parameters:
usage - The file mode (text/binary) and type.
mode - The mode in which to open the file (filemode_*)
Returns:
A new Fileref, or null if one was not created (eg: user cancel).
o createByPrompt 
 public static FileRef createByPrompt(int usage,
                                      int fmode,
                                      Object jrock)
Create a file reference by asking the player to type a name.

Parameters:
usage - The file mode (text/binary) and type.
mode - The mode in which to open the file (filemode_*)
jrock - The rock value to store.
Returns:
A new Fileref, or null if one was not created (eg: user cancel).
o createTemp 
 public static FileRef createTemp(int usage,
                                  Object jrock)
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.

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.

Parameters:
usage - The file mode (text/binary) and type.
jrock - The rock value to store.
Returns:
A new Fileref, or null if one was not created.
o createByName 
 public static FileRef createByName(int usage,
                                    String name)
Create a reference to a file with a specific name.

Parameters:
usage - The file mode (text/binary) and type.
name - The filename to open.
Returns:
A new Fileref, or null if one was not created.
See Also:
createByName
o createByName 
 public static FileRef createByName(int usage,
                                    String name,
                                    Object jrock)
Create 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.

Since filenames are highly platform-specific, you should use createByName() 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.

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.

Parameters:
usage - The file mode (text/binary) and type.
name - The filename to open.
jrock - The rock value to store.
Returns:
A new Fileref, or null if one was not created.
o createFromFileRef 
 public FileRef createFromFileRef(int usage)
This copies an existing file reference, but changes the usage.

Parameters:
usage - The new usage.
Returns:
A copy of this file reference.
See Also:
createFromFileRef
o createFromFileRef 
 public FileRef createFromFileRef(int usage,
                                  Object jrock)
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.

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.

Parameters:
usage - The new usage.
jrock - The rock value to store.
Returns:
A copy of this file reference.
o finalize 
 protected void finalize()
If the Glk object is still in existence when this object is garbage-collected, destroy it.

Overrides:
finalize in class OpaqueObject
o destroy 
 public void destroy()
Destroys a fileref which you have created. This does not affect the disk file; it just reclaims the resources allocated by the 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.

Overrides:
destroy in class OpaqueObject
o openFile 
 public Stream openFile(int fmode)
Open a stream on the file this refers to.

Parameters:
fmode - The mode to open the file in (filemode_*)
Returns:
The opened stream, or null if opening failed.
o openFile 
 public Stream openFile(int fmode,
                        Object jrock)
Open a stream on the file this refers to.

Parameters:
fmode - The mode to open the file in (filemode_*)
jrock - The rock for the stream.
Returns:
The opened stream, or null if opening failed.
o deleteFile 
 public void deleteFile()
This deletes the file this FileRef refers to. It does not destroy the FileRef itself.

o doesFileExist 
 public boolean doesFileExist()
See if this fileref refers to an existing file.

Returns:
true if the file exists, else false. 
All Packages  Class Hierarchy  This Package  Previous  Next  Index