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.

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.

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.

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.

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.

Reads one line from the file into a provided string buffer, which is required 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.

ERR::NoData is returned once all lines have been read.

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.

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().

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

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, std::string_view Path, MFF Flags, APTR Meta)

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 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 MFF::NIL.