Streaming data of any type to a file will result in the content being written to the file at the current seek Position.

This action will prepare a file or folder at the given Path for use.

To create a new file from scratch, specify the NEW flag. This will overwrite any file that exists at the target path.

To read and write data to the file, specify the READ and/or WRITE modes in the Flags field prior to initialisation. If a file is read-only and the WRITE and READ flags are set in combination, the WRITE flag will be dropped and initialisation will continue as normal.

If neither of the NEW, READ or WRITE flags are specified, the file object is prepared and queried from disk (if it exists), but will not be opened. It will be necessary to Activate() the file in order to open it.

The File class supports RAM based file buffering - this is activated by using the BUFFER flag and setting the Size field to the desired buffer size. A file path is not required unless the buffer needs to be filled with content on initialisation. Because buffered files exist virtually, their functionality is restricted to read/write access.

Strings can also be loaded into file buffers for read/write access. This is achieved by specifying the Path string:Data\0, where Data is a sequence of characters to be loaded into a virtual memory space.

Error Codes

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. The FL::READ bit in the Flags field must have been set on file initialisation, or the call will fail.

It is normal behaviour for this call to report success in the event that no data has been read from the file, e.g. if the end of the file has been reached. The Result parameter will be returned as zero in such cases. Check the current Position against the Size to confirm that the end has been reached.

Error Codes

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.

Error Codes

File content may be buffered at any time by calling the BufferContent method. This will allocate a buffer that matches the current file size and the file's content will be read into that buffer. The BUFFER flag is set in the file object and a pointer to the content is referenced in the file's Buffer field. Standard file operations such as read, write and seek have the same effect when a file is in buffer mode.

Once a file has been buffered, the original file handle and any locks on that file are returned to the system. Physical operations on the file object such as delete, rename and attribute settings no longer have meaning when applied to a buffered file. It is not possible to drop the buffer and return the file object to its original state once buffering has been enabled.

Error Codes

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 path, 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 folder structure (i.e. all of the folder contents) will be copied to the new location. If an error occurs when copying a sub-folder or file, the procedure will be aborted and an error code will be returned.

Error Codes

This method is used to delete files from their source location. If used on a folder, all of the folder'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.

Error Codes

This method is used to move the data of a file to another location. If the file object represents a folder, then the folder 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 path then it will be over-written with the new data.

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

Error Codes

If a file object represents a folder, calling the Next() method will retrieve meta information about the next file in the folder's index. This information will be returned as a new File object that is partially initialised (the file will not be opened, but information such as size, timestamps and permissions will be retrievable).

If desired, the resulting file object can be opened by setting the READ or WRITE bits in Flags and then calling the Activate() action.

It is the responsibility of the caller to free the resulting File object once it is no longer required.

The file index can be reset by calling the Reset() action.

Error Codes

Reads one line from the file into an internal buffer, which is returned in the Result argument. Reading a line will increase the Position field by the amount of bytes read from the file. You must have set the FL::READ bit in the Flags field when you initialised the file, or the call will fail.

The line buffer is managed internally, so there is no need to free the Result string. ERR::NoData is returned once all lines have been read.

Error Codes

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

Depending on the filesystem type, multiple forms of datestamp may be supported. The default datestamp, FDT::MODIFIED defines the time at which the file data was last altered. Other types include the date on which the file was created and the date it was last archived (backed up). The following types are supported by the Type argument:

If the specified datestamp is not supported by the filesystem, ERR::NoSupport is returned by this method.

Error Codes

If a file object is a stream (indicated by the STREAM flag), the StartStream method should be used for reading or writing data to the file object. Although it is possible to call the Read and Write actions on streamed files, they will be limited to returning only the amount of data that is cached locally (if any), or writing as much as buffers will allow in software.

A single file object can support read or write streams (pass FL::READ or FL::WRITE in the Flags parameter). However, only one of the two can be active at any time. To switch between read and write modes, the stream must be stopped with the StopStream() method and then restarted with StartStream.

A stream can be limited by setting the Length parameter to a non-zero value.

If the StartStream request is successful, the file object will return action notifications to the Subscriber to indicate activity on the file stream. When reading from a stream, AC::Write notifications will be received to indicate that new data has been written to the file cache. The Buffer parameter of the reported acWrite structure may refer to a private address that contains the data that was received from the stream and the Result indicates the amount of new data available.

When writing to a stream, AC::Read notifications will be received to indicate that the stream is ready to accept more data. The Result parameter will indicate the maximum amount of data that should be written to the stream using the Write() action.

A stream can be cancelled at any time by calling StopStream().

Error Codes

This method terminates data streaming from a file (instantiated by the StartStream() method). Any resources related to the streaming process will be deallocated.

Error Codes

The Watch() method configures event based reporting for changes to any file or folder in the file system. The capabilities of this method are dependent on the host platform, with Windows and Linux systems being able to support most of the current feature set.

The path that will be monitored is determined by the File object's Path field. Both files and folders are supported as targets.

The optional MFF Flags are used to filter events to those that are desired for monitoring.

The client must provide a Callback that will be triggered when a monitored event is triggered. The Callback must follow the format ERR Routine(*File, STRING Path, LARGE Custom, LONG Flags)

Each event will be delivered in the sequence that they are originally raised. The Flags parameter will reflect the specific event that has occurred. The Custom parameter is identical to the Custom argument originally passed to this method. The Path is a string that is relative to the File's Path field.

If the callback routine returns ERR::Terminate, the watch will be disabled. It is also possible to disable an existing watch by calling this method with no parameters, or by setting the Flags parameter to 0.

Error Codes