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:

File handling functions

File information functions

Directory 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 .

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);