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
-
filemode_Read
- Open the file this refers to in read mode.
-
filemode_ReadWrite
- Open the file this refers to in read/write mode.
-
filemode_Write
- Open the file this refers to in write mode.
-
filemode_WriteAppend
- Open the file this refers to in append mode.
-
fileusage_BinaryMode
- Open the file this refers to in binary mode.
-
fileusage_Data
- This file stores arbitrary data (preferences, statistics...)
-
fileusage_InputRecord
- This file stores a recording of player input.
-
fileusage_SavedGame
- This file stores a saved game.
-
fileusage_TextMode
- Open the file this refers to in text mode.
-
fileusage_Transcript
- This file stores a stream of text from the game.
-
fileusage_TypeMask
- Mask for file type bits.
-
createByName(int, String)
- Create a reference to a file with a specific name.
-
createByName(int, String, Object)
- Create a reference to a file with a specific name.
-
createByPrompt(int, int)
- Create a file reference by asking the player to type a name.
-
createByPrompt(int, int, Object)
- Create a file reference by asking the player to type a name.
-
createFromFileRef(int)
- This copies an existing file reference, but changes the usage.
-
createFromFileRef(int, Object)
- This copies an existing file reference, but changes the usage.
-
createTemp(int, Object)
- This creates a reference to a temporary file.
-
deleteFile()
- This deletes the file this FileRef refers to.
-
destroy()
- Destroys a fileref which you have created.
-
doesFileExist()
- See if this fileref refers to an existing file.
-
finalize()
- If the Glk object is still in existence when this object is
garbage-collected, destroy it.
-
iterate(FileRef, Object[])
- Iterate over file references.
-
openFile(int)
- Open a stream on the file this refers to.
-
openFile(int, Object)
- Open a stream on the file this refers to.
fileusage_Data
public static final int fileusage_Data
- This file stores arbitrary data (preferences, statistics...)
fileusage_SavedGame
public static final int fileusage_SavedGame
- This file stores a saved game.
fileusage_Transcript
public static final int fileusage_Transcript
- This file stores a stream of text from the game.
fileusage_InputRecord
public static final int fileusage_InputRecord
- This file stores a recording of player input.
fileusage_TypeMask
public static final int fileusage_TypeMask
- Mask for file type bits.
fileusage_TextMode
public static final int fileusage_TextMode
- Open the file this refers to in text mode.
fileusage_BinaryMode
public static final int fileusage_BinaryMode
- Open the file this refers to in binary mode.
filemode_Write
public static final int filemode_Write
- Open the file this refers to in write mode.
filemode_Read
public static final int filemode_Read
- Open the file this refers to in read mode.
filemode_ReadWrite
public static final int filemode_ReadWrite
- Open the file this refers to in read/write mode.
filemode_WriteAppend
public static final int filemode_WriteAppend
- Open the file this refers to in append mode.
iterate
public static FileRef iterate(FileRef f,
Object r[])
- Iterate over file references.
- See Also:
- iterate
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).
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).
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.
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
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.
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
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.
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
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
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.
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.
deleteFile
public void deleteFile()
- This deletes the file this FileRef refers to.
It does not destroy the FileRef itself.
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