Class Documentation

Name:File
Version:1.0
ID:ID_FILE
Status:Stable
Include:files/file.h
Date:February 2002
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2002. All rights reserved.



Description

The File class is used for basic file management purposes. Unlike file handles in other systems, this object allows you to find out many details on a file with little effort. The class supports the notion of individual file compression and file finding capabilities. Since all File objects are tracked, there is no chance of the system leaving locked files behind after a program exits. Directory management is also integrated into this class to ease the management of both file types.

To read or write to a file, you need to set the Location of the file as well as the correct I/O file flags before initialisation. See the Flags field for information on the available I/O flags. Functionality for read and write operations is provided through the Read and Write actions. You can also use the Seek action to change your read/write position in a file.

Actions

The File class supports the following actions:

Activate  Activating a file object will cause it to activate its children.
ClosingTag  If a file object is non-static, calling this action will cause it to self-destruct.
Init  Initialises a file.
Read  Reads data from a file.
Rename  Changes the name of a file.
Seek  Seeks to a new read/write position within a file.
Write  Writes data to a file.

Methods

The File class implements the following methods:

CopyFile  Copies the data of a file to another location.
DeleteFile  Deletes a file from its source location.
MoveFile  Moves a file to a new location.
ReadBE  Reads small blocks of big-endian file data.
ReadLE  Reads small blocks of little-endian file data.
SetFileDate  Sets the date on a file.

Structure

The File object consists of the following public fields:

Comment  A comment string describes what the file is.
Date  The file date stamp.
Flags  File flags and options.
Location  Specifies the location of a file.
Position  The current read/write byte position in a file.
Size  The byte size of a file.
Static  Set to TRUE if a file object should be static.
TimeStamp  The last modification time set on a file, represented as a 64-bit integer.
Action:Activate
Short:Activating a file object will cause it to activate its children.

This action can be used when a static File object has been used in an object script. By calling this action, the File object will Activate all of the children that are attached to it. Activation of child objects can be a helpful technique to use when interaction with a File object is required.

Result
ERR_Okay  All child objects were sent Activate messages.
ERR_Failed  A call to ListChildren() failed.

Action:Init
Short:Initialises a file.

This action will initialise a file from its Location. After initialisation you will be allowed to retrieve information such as the File's Size and Comment. If you want to read and write data to the file, then specify the FL_READ and/or FL_WRITE modes in the Flags field to do a full initialisation.

If a file is read-only and you set the FL_WRITE flag, the initialisation process will attempt to drop back to read-only access if you also used the FL_READ flag. This will result in the FL_WRITE flag being dropped on the functions return.

Result
ERR_Okay  The File object was initialised.
ERR_MissingLocation  The Location field was not specified.
ERR_SetField  An error occurred while updating the Location field.
ERR_ResolveAssign  The Location string could not be resolved.
ERR_Search  The File could not be found.

Action:Read
Short:Reads data from a file.

Reads data from a file into the given buffer. Increases the value in the Position field by the amount of bytes read from the file data. You must have set the FL_READ bit in the Flags field when you initialised the file, or the call will fail.

Result
ERR_Okay  The file information was read into the buffer.
ERR_Args  Invalid arguments were specified.
ERR_FileReadFlag  The FL_READ flag was not specified on initialisation.
ERR_Failed  The file object refers to a directory, or the object is corrupt.

Action:Write
Short:Writes data to a file.

Writes data from the provided buffer into the file, then updates the Position field to reflect the new read/write position. You must have set the FL_WRITE bit in the Flags field when you initialised the file, or the call will fail.

Result
ERR_Okay  All of the data was written to the file location.
ERR_Args  Invalid arguments were specified.
ERR_FileWriteFlag  The FL_WRITE flag was not specified when initialising the file.
ERR_Failed  The file is a directory, or the File is corrupt.
ERR_LimitedSuccess  Some of the data was written to the file, but not all. Check the Result parameter to see how much data was written.

Method:CopyFile()
Short:Copies the data of a file to another location.
Arguments:
STRING Destination  The file location that you are copying the data to.

This method is used to copy the data of a file object to another location. All of the data will be copied, effectively creating a clone of the original file information. The file object must have been initialised with the FL_READ flag, or the copy operation will not work (this restriction does not apply to directories). If a matching file name already exists at the destination location, it will be over-written with the new data.

The Position field will be reset as a result of calling this method.

When copying directories with this method, the entire directory structure (i.e. all of the directory contents) will be copied to the new location. If an error occurs when copying a sub-directory or file, the procedure will be aborted and an error code will be returned.

Result
ERR_Okay  The file data was copied successfully.
ERR_Args  The Destination argument was not specified.
ERR_FieldNotSet  The Location field has not been set in the file object.
ERR_Failed  An unspecific failure occurred.
ERR_Read  Data could not be read from the source location.
ERR_Write  Data could not be written to the destination location.
ERR_ResolveAssign  A call to ResolveAssign() failed.
ERR_Loop  Performing the copy would cause infinite recursion.
ERR_AllocMemory  A call to AllocMemory() failed.

Method:DeleteFile()
Short:Deletes a file from its source location.

This method is used to delete files from their source location. If used on a directory, all of the directory's contents will be deleted in the call. Once a file is deleted, the object effectively becomes unusable. For this reason, file deletion should normally be followed up with a call to the Free action.

Result
ERR_Okay  File deleted successfully.
ERR_Failed  The deletion attempt failed.
ERR_MissingLocation  The Location field is not set in the file object.
ERR_ResolveAssign  The ResolveAssign() function failed.

Method:MoveFile()
Short:Moves a file to a new location.
Arguments:
STRING Destination  The file location that you are moving the data to.

This method is used to move the data of a file to another location. If the File object represents a directory, then the directory and all of its contents will be moved. The file object must have been initialised with the FL_READ flag, or the move operation will not work (this restriction does not apply to directories). If a file already exists at the destination location then it will be over-written with the new data.

The Position field will be reset as a result of calling this method.

Result
ERR_Okay  The File was moved successfully.
ERR_Args  The Destination argument was not specified.
ERR_FieldNotSet  The Location field has not been set in the file object.
ERR_Failed  An unspecific failure occurred.

Method:ReadBE()
Short:Reads small blocks of big-endian file data.
Arguments:
LONG Size  The amount of data to read - can be set to 1, 2, 4 or 8.
LARGE Result  The data read from the file will be stored in this parameter in the host system's correct format.

Calling this method will read a block of big-endian data from the file and convert it to the correct byte-order for the target platform. No adjustment is made if the target platform supports big-endian data natively.

Result
ERR_Okay  The data was read successfully.
ERR_Read  An error occurred while reading the data.

Method:ReadLE()
Short:Reads small blocks of little-endian file data.
Arguments:
LONG Size  The amount of data to read - can be set to 1, 2, 4 or 8.
LARGE Result  The data read from the file will be stored in this parameter in the host system's correct format.

Calling this method will read a block of little-endian data from the file and convert it to the correct byte-order for the target platform. No adjustment is made if the target platform supports little-endian data natively.

Result
ERR_Okay  The data was read successfully.
ERR_Read  An error occurred while reading the data.

Method:SetFileDate()
Short:Sets the date on a file.
Arguments:
LONG Year  Year (-ve for BC, +ve for AD).
LONG Month  Month (1 - 12)
LONG Day  Day (1 - 31)
LONG Hour  Hour (0 - 23
LONG Minute  Minute (0 - 59)
LONG Second  Second (0 - 59)

The SetFileDate method provides a convenient way to set the date and time information on a file object. Date information is set in a human readable year, month, day, hour, minute and second format for your convenience.

The file system engine assumes that files are limited to one type of date stamp. If a file system supports multiple date settings for each file, the SetFileDate method will set your date against all of them.

Result
ERR_Okay  The date was successfully set.
ERR_Args  Invalid arguments were specified.
ERR_NoSupport  The platform does not support file date setting.

Field:Comment
Short:A comment string describes what the file is.
Type:STRING
Status:Get/Set

The Comment field is available for file systems that support the concept of adding comments (or descriptions) to files to allow easy identification by the user. While this is extremely useful under networked and shared environments, this feature will often go unsupported due to lack of support from most available file systems. In cases such as this, the Comment field will always return NULL and attempts to set a comment will be ignored.


Field:Date
Short:The file date stamp.
Type:struct FileTime *
Status:Get/Set

The Date field allows you to obtain the time at which the file was last date-stamped, or you can use it to set a new file date. The vast majority of file systems support the concept of date stamps, so you will rarely encounter situations where dates may not be supported.

To simplify time management, information is read and set via a FileTime structure. The structure consists of the fields Year, Month, Day, Hour, Minute and Second.


Field:Flags
Short:File flags and options.
Type:LONG
Prefix:FL
Status:Read/Init

This field defines the commands to use when initialising a file. Available flags are:

FlagDescription
APPROXIMATE  Setting this flag allows a file object to find approximate matching file names when opening an existing file. In basic terms it causes file extensions to be ignored; for instance if you attempt to open a file of 'screenshot.png' when only a file name of 'screenshot.jpg' exists under the same directory, the 'screenshot.jpg' file will be opened instead. If multiple files could potentially match to the file name, the file object will select the first potential match that it comes across.
NEWSet this flag if you are creating a new file. Note that if a file with the same name already exists, the old file (with all its data), will be destroyed. If you try to create a new file on a file that is already open by some other task, the initalisation will fail.
READSet this flag if you want to read data from a file.
WRITEPrepares a file for writing data, starting at byte position 0. If you want to start writing from the end of a file, use the Seek action after your file has been initialised successfully.
BUFFERActivates a special mode where the file is located in a memory buffer rather than a disk file. You are required to set the Size field to a value of at least 1 so that the file can determine the initial buffer size. In this mode most of the available file operations are meaningless except for the Read, Write and Seek actions.
LOOPIn loop mode, the file object's position marker for read/write operations is allowed to extend past the actual file size. Any read/write operation beyond the file size will loop back to the file at a corrected offset - for example, reading position 330 of a 100 byte file will in fact start the operation from the 30th byte. Loop mode does not affect any other area besides the read, write and seek operations. The loop feature is typically used to enable multimedia data streams with minimal effort.
LINKRead-Only. The file is a symbolic link or shortcut to another file.


Field:Location
Short:Specifies the location of a file.
Type:STRING
Status:Get/Set

This field points to a standard file location string. It is compulsory to set this field for initialisation.

The correct string format for pointing to a standard file is:

   assignment:directory/file

The correct string format for pointing to a standard directory is:

   assignment:directory/

Field:Position
Short:The current read/write byte position in a file.
Type:LONG
Status:Read

This field tells you the current byte position of an open File (this affects read and write operations). If you want to change the byte position, use the Seek action.

The Position will always remain at zero when a File object represents a directory.


Field:Size
Short:The byte size of a file.
Type:LARGE
Status:Get/Set

The current byte size of a File is indicated by this field. If the File object represents a directory, the Size value will be set to zero. You can also truncate a file by setting the Size; this will result in the current read/write position being set to the end of the file.


Field:Static
Short:Set to TRUE if a file object should be static.
Type:LONG
Status:Read/Init

This field applies when a File object has been created in an object script. By default, a File object will self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE.


Field:TimeStamp
Short:The last modification time set on a file, represented as a 64-bit integer.
Type:LARGE
Status:Get

The TimeStamp field is a 64-bit representation of the last modification date/time set on a file. The figure itself is meaningless except when used for the purpose of sorting or comparison to the time stamps on other files. For a broken down time structure, refer to the Date field.