File operation functions
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
There is an important naming difference between directories and other file system objects in the PFI: a directory name should always be followed by a trailing directory separator (use PlgFwFileEnsureTrailingSeparator
to enforce this).
The only exception is for PlgFwFileGetInfo
, where the program cannot reasonably be expected to know before obtaining the information whether the object is or is not a directory.
The PFI provides functions to support the following kinds of file operations:
Miscellaneous file handling functions
File handling functions
The following functions support such operations as opening, closing, reading from, writing to and seeking through a file, as well as copying, renaming or deleting files.
Open a file
This function opens a file, using a set of flags from the PLGFW_OPEN_...
bits above.
The function returns a file handle upon success, or PLGFW_FILE_ROGUE
on failure. Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
PlgFwFile PlgFwFileOpen(
PlgFwErrorState *pErrState, PlgFwTextString ptbzFilename, uint32 flags );
Read from a file
This function reads data from the file specified by Handle
into the buffer specified by Buffer
, and returns the number of bytes read. If the function fails or the end of file is reached, this is the number of bytes definitely read safely. The file pointer is advanced by the number of bytes given in the return value. The Size
parameter specifies the maximum number of bytes that the function should attempt to read.
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
uint32 PlgFwFileRead(
PlgFwErrorState *pErrState, PlgFwFile Handle,
void *Buffer, uint32 Size );
Write to a file
This function writes data from the buffer specified by Buffer
into the file specified by Handle
, and returns the number of bytes written. If the function fails, this is the number of bytes definitely written
safely, although it is possible that more bytes were actually written. The file pointer is advanced by the number of bytes given in the return value. The Size
parameter specifies the maximum number of bytes that the function should attempt to write.
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
uint32 PlgFwFileWrite(
PlgFwErrorState *pErrState, PlgFwFile Handle,
void *Buffer, uint32 Size );
Seek to a given point in a file
This function seeks to a given point in an open file. The nFrom
argument is one of the PLGFW_SEEK_...
values (see File handling macros
), and defines whether the offset in *pOffset
is relative to the start of the file, the end of the file, or the current file position. The function returns TRUE
on success, or FALSE
if the seek fails. The value in *pOffset
is updated to be the new file position, even upon error (or ‐1 if not possible).
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileSeek(
PlgFwErrorState *pErrState, PlgFwFile Handle,
Hq32x2 *pOffset, uint32 nFrom);
Retrieve the current size of an open file
This function obtains the current size of an open file. The function returns TRUE
upon success and updates *pExtent
to the total size of the file. If the call fails, the function will return FALSE
, and set
*pExtent
to ‐1.
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileExtent(
PlgFwErrorState *pErrState, PlgFwFile Handle,
Hq32x2 *pExtent);
Close a file
This function closes a file. It returns TRUE
upon success, in which case the handle is closed, and all resources associated with the open file are released.
int32 PlgFwFileClose(
PlgFwErrorState *pErrState, PlgFwFile Handle );
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
Copy a file
This function copies the contents of a file to a second file. If the second file does not exist, the function will create it; if it does already exist, the function's behavior will depend on the setting of fFlags
. If PLGFWFILE_FLAG_CAN_EXIST
(see File handling macros
) is set in fFlags
, any existing file will be replaced, if possible. If fFlags
is set to zero, the copy will not be successful.
This function returns TRUE
upon success, FALSE
upon failure. Any errors will be reported via the
pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileCopy(
PlgFwErrorState *pErrState, PlgFwTextString ptbzOldname, PlgFwTextString ptbzNewname, uint32 fFlags);
Rename a file
This function renames a file, copying across media if necessary. Returns TRUE
upon success. If fFlags
is set to PLGFWFILE_FLAG_CAN_EXIST
, any existing file with the same name as the destination file name will be overwritten; if this bit is not set in fFlags
, an error will be generated instead, and the operation failed.
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileRename(
PlgFwErrorState *pErrState, PlgFwTextString ptbzOldname, PlgFwTextString ptbzNewname, uint32 fFlags);
Delete a file
This function deletes the given file. The value of fFlags
should be zero; this is reserved for future use. Returns TRUE
upon success.
Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileDelete(
PlgFwErrorState * pErrState, PlgFwTextString ptbzFilename, uint32 fFlags);
File information functions
The file information structure is opaque and supplied from dynamically‐allocated memory. It should be allocated upon need and deallocated when no longer needed. Times and file sizes are generally stored in HqU32x2s
. The actual meaning of the values for file times depends upon the platform: a function is provided to resolve these into meaningful platform‐independent values.
Allocate a file information structure
This function allocates a structure into which file information can be placed.
PlgFwFileInfo *PlgFwFileAllocFileInfo(void);
Free a file information structure
This function frees a file information structure and deallocates the memory assigned to it. Once freed, the pointer is no longer valid and should not be used.
void PlgFwFileFreeFileInfo(PlgFwFileInfo *pInfo);
Obtain information on a file system object
This function obtains information on the file system object pointed to the name in ptbzFilename
. The
fFlags
argument is no longer used and should be set to 0
.
The function returns TRUE
upon success, FALSE
upon failure. Any errors will be reported via the
pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileGetInfo(
PlgFwErrorState *pErrState, PlgFwTextString ptbzFilename, PlgFwFileInfo *pInfo, uint32 fFlags);
Obtain created, last accessed or last modified times
The following functions obtain the creation, last‐accessed and last‐modified times (respectively) stored in the file information structure. The return value is NULL if the underlying operating system does not store that value, or if it is invalid. Otherwise, a pointer is returned to a value in the structure.
HqU32x2 *PlgFwFileInfoGetCreationTime(PlgFwFileInfo *pInfo); HqU32x2 *PlgFwFileInfoGetLastAccessTime(PlgFwFileInfo *pInfo); HqU32x2 *PlgFwFileInfoGetModifiedTime(PlgFwFileInfo *pInfo);
Convert times from operating system format to a known format
The above functions provide times in an operating system specific format. It is safe to assume that later times have higher values, but apart from that, no information about the format may be available. In some cases, it will be more convenient to use this function to convert such values into the number of seconds since 00:00:00 UTC, Jan. 1, 1970.
int32 PlgFwFileTimeToSeconds(HqU32x2 *pFileTime, long double *pReturn);
Retrieve the size of a file resource fork
This function returns the size of the file fork specified by the file name and fork number supplied. The function is supplied with a pointer to a file information structure, and a number indicating a resource fork. For the Apple Macintosh platform there may be more than one fork; almost all other platforms have only one file fork. For all platforms, the zero‐indexed fork is the data fork.
The function returns either a pointer to the size of that fork, or NULL if no such fork exists in the file, or no such fork number applies to the platform.
HqU32x2 * PlgFwFileInfoGetSizeByFork(PlgFwFileInfo *pInfo, uint32 nFork);
Retrieve the file type from the file information structure
Obtain the file type from the file information. The value returned is one of the PLGFWFILE_TYPE_...
values. Note that this value is a scalar, not a bit set.
uint32 PlgFwFileInfoGetType(PlgFwFileInfo *pInfo);
Retrieve the file attributes from the file information structure
This function retrieves the file attributes from the file information structure.
Note:
Since the addition of functions PlgFwFileInfoIsReadable
and PlgFwFileInfoIsWriteable
, this function is redundant.
uint32 PlgFwFileInfoGetAttributes(PlgFwFileInfo *pInfo);
Retrieve read/write access for a file
The following functions return TRUE
if the file is readable or writable (respectively), as specified in the file information structure, otherwise they return FALSE
.
int32 PlgFwFileInfoIsReadable(PlgFwFileInfo *pInfo); int32 PlgFwFileInfoIsWriteable(PlgFwFileInfo *pInfo);
Set read/write access for a file
This function allows control over whether the specified file can be read or written to. On Windows all files are considered readable, and it is recommended that fReadable
should be set to TRUE
always.
Windows files must be writable in order to be deleted.
int32 PlgFwFileSetAccess(
PlgFwErrorState *pErrState, PlgFwTextString ptbzFilename, int32 fReadable,
int32 fWriteable);
The function returns TRUE
upon success, FALSE
upon failure. Any errors will be reported via the
pErrState
parameter, as described in Error reporting
.
Directory operations
The following functions allow the user to open a directory and obtain a handle to it, iterate through a directory, retrieve file information for files in a directory and close the directory handle again.
Create a directory
This function creates a directory according to the bits set in fFlags
. The fFlags
parameter may include settings for PLGFWFILE_FLAG_RECURSIVE
and/or PLGFWFILE_FLAG_CAN_EXIST
.
The function returns TRUE
upon success, FALSE
upon failure. Any errors will be reported via the
pErrState
parameter, as described in Error reporting
.
int32 PlgFwDirCreate(
PlgFwErrorState *pErrState, PlgFwTextString ptbzDirname, uint32 fFlags);
Open a directory for enumeration
This function opens a directory for enumeration. If fFlags
includes PLGFWDIR_OPEN_SNAPSHOT
, a snap‐ shot of the directory will be taken, and the iteration will be based upon this snapshot. If not, the iteration will be based upon the current state at each call to PlgFwDirNext
.
| Is a flag for the |
Upon success, the enumeration handle is returned; on failure PLGFWDIR_ROGUE
. Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
PlgFwDir PlgFwDirOpen(
PlgFwErrorState *pErrState, PlgFwTextString ptbzDirname, uint32 fFlags);
Find the next file in a directory
This function searches for the next leaf files system object in the directory passed to it in DirHandle
and writes the leaf file name, if a file is found, to pRecord
.
If pInfo
is non‐NULL, it will be filled with information pertinent to the file found (if any). The use of fFlags
has been deprecated and should be set to 0
.
Returns TRUE
if another leaf file name found; else FALSE
. Any errors will be reported via the pErrState
parameter, as described in Error reporting .
int32 PlgFwDirNext(
PlgFwErrorState *pErrState, PlgFwDir DirHandle, PlgFwStrRecord *pRecord, PlgFwFileInfo *pInfo, uint32 fFlags);
Close a directory enumeration handle
This function closes the enumeration handle passed to it. This function must be called on every handle successfully returned from PlgFwDirOpen
, once it is no longer needed.
The function will return TRUE
on success, or FALSE
otherwise. Any errors will be reported via the
pErrState
parameter, as described in Error reporting
.
int32 PlgFwDirClose(
PlgFwErrorState *pErrState, PlgFwDir DirHandle);
Miscellaneous file handling functions
The following functions are useful in handling files and directories, but do not fit easily into other categories:
Retrieve the applications' directory path name
This function returns a pointer to a string holding the application's directory path name, which is initialized when FrameWorks is booted and will not be changed unless the RIP asks the FrameWork to change the format in which it wants file names. The string will have a trailing directory separator, and is allocated from the heap for the caller; it must be freed after use by calling PlgFwMemFree
.
On Windows, the string points to the directory containing the code module that initialized the frame‐ work; for the RIP this will be the RIP executable, thus returning the directory containing the SW folder.
On error or if it is not possible to retrieve the string, it returns NULL.
PlgFwTextString PlgFwAppDir(void);
Retrieve disk usage information for a logical device
Given a directory name, this function will populate the various pointers passed into the function as follows:
*pFree
will be set to the number of bytes still available on that logical disk (that is, partition);*pTotalSize
will be set to the total amount of space available on that disk/partition;*pAllocSize
will be set to the allocation block size in bytes.
Any or all of these pointers may be passed as NULL if the information they represent is not required.
The function returns TRUE
on success. Any errors will be reported via the pErrState
parameter, as described in Error reporting
.
int32 PlgFwFileDiskFree(
PlgFwErrorState *pErrState, PlgFwTextString ptbzDir, HqU32x2 *pFree,
HqU32x2 *pTotalSize, uint32 *pAllocSize);