(v13) PostScript language file name functions

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

The PFI provides the following types function for handling PostScript language file names:

Filename conversion functions

PostScript directory iteration

File name manipulation

Filename conversion functions

The following functions aid the interconversion of platform‐specific and PostScript language file names.

Convert a file name from platform-specific to PostScript language format

This function converts a platform‐specific file name to its PostScript language equivalent, appending it to *pPS . The return value is the number of bytes appended. If the value of *pMapping upon entry is TRUE , its value upon return reflects whether (FALSE ) or not (TRUE ) file mapping would be disabled for any suffix added to the input name. The pMapping pointer may be NULL on entry if this information is not required.

    uint32 PlgPfPlatformToPS(
                                PlgFwStrRecord *pPS, PlgFwTextString ptbzPlatform, int32 *pMapping);

Convert a file name from the PostScript language to a platform-specific format

This function converts a PostScript language file name to a platform‐dependent one, appending it to

*pPlatform . The return value is the number of bytes appended.

    uint32 PlgPfPSToPlatform(
                                PlgFwStrRecord *pPlatform, PlgFwTextString ptbzPS);

Skip the directory part of a PostScript language file name

This function returns a pointer to the leaf part of the file name that is, to the character immediately after the last un‐escaped directory separator, or to the terminating zero character, if the name ends in

an un‐escaped directory separator. If the file name consists only of a device name, the return value is the device name.

PlgFwTextString PlgPfPSSkipToLeafname(PlgFwTextString ptbzPS);

Strip the device name from a PostScript language file name

This function returns a pointer to the portion of the file name that follows the device name. If the input file name starts with a device name (that is, starts with a % symbol), this function returns a pointer to the character that immediately follows the second % symbol in the string. If there is no second % symbol in the string, a pointer to the string's zero terminator is returned.

Note: If there is no relative path after the device name, the return pointer could be to the string's zero terminator, even if a second % symbol is found.

If the input filename does not start with a device name, then the function will return the input file‐ name unchanged.

PlgFwTextString PlgPfPSSkipDevice(PlgFwTextString ptbzPS);

Add a terminating directory separator to a PostScript file name

This function adds a terminating PostScript directory separator to a PostScript file name unless:

• it already has one;
• it is an empty string;
• the file name consists of just a device.

The return value is TRUE if the function detects that a separator should be added to the file name.

Note: If the string record is fixed length, and if it is already full, the function will still return TRUE , but the separator will not be added.

int32 PlgPfPSAddDirSeparator(PlgFwStrRecord *pPS);

Convert the root part of a platform-specific file name to an escaped PostScript device name

This function extracts and converts the root part (if any) of a platform‐specific file name to an escaped PostScript device name. pptbInput passes in the input file name; upon return, the pointer to which pptbInput points is updated to point to the character immediately after the root part, or to the terminating zero if no root part is found.

pOutput is a pointer to the record intended to receive the converted value. The output is appended to this record.

The return value is the number of bytes appended to the output record.

    uint32 PlgPfPlatformRootToPS(
                    PlgFwStrRecord *pOutput, PlgFwTextByte **pptbInput);

Convert the device part of a PostScript language file name to a platform-specific root part

This function extracts and converts the device part (if any) of an escaped PostScript file name to a plat‐ form‐specific root name. pptbInput passes in the input file name; upon return, the pointer to which pptbInput points is updated to point to the character immediately after the PostScript device delimiter or to the terminating zero, if no device part is found.

pOutput is a pointer to the record intended to receive the converted value. The output is appended to this record.

The return value is the number of bytes appended to the output record.

    uint32 PlgPfPSDeviceNameToPlatform(
                    PlgFwStrRecord *pOutput, PlgFwTextByte **pptbInput);

Extract a path element from a PostScript language file name

This function extracts an escaped PostScript language path element from the input string, up to (but not including) the first un‐escaped directory separator, or the terminating zero. pptbInput passes in the input string; upon return, the pointer to which pptbInput points is updated to point to the terminating zero, or the directory separator, as appropriate.

pOutput is a pointer to the record intended to receive the extracted value. The output is appended to this record.

The return value is the number of bytes appended to the output record.

    uint32 PlgPfPSPathExtractElement(
                    PlgFwStrRecord *pOutput, PlgFwTextByte **pptbInput);

PostScript directory iteration

The following functions aid iteration over a directory on a PostScript device.

Iterate over PostScript language file names in a directory

This function iterates over PostScript file names in a directory. On the first call for a given directory,

fFirst should be TRUE ; subsequent calls for the same directory should have FALSE as its value.

ptbzDirname should give the PostScript language name of the directory through which to iterate.

ppSearchState should point to an uninitialized void* variable. The function uses this variable to store progress information which it alone is responsible for maintaining; no useful information is gained by inspecting *ppSearchState or the area of memory to which it may point. The same value for ppSearchState should be passed for each successive call on a given directory. If it is necessary to have more than one directory search in operation at a time, using this function, each individual directory being searched will need its own void* , passed by reference in ppSearchState .

pPSFilename is updated with the full PostScript file name for each file found. This function returns the

pPSFilename buffer pointer each time it finds a file; it returns NULL when no more files can be found.

Note: This function iterates only over file names; pPSFilename will never be set to point to a subdirectory name.

Note: If no further searches are needed in a given directory, but not all files have been exhausted, you must call PlgPfPSDirGetNextFileAbort (below) with the same ppSearchState value used when calling this function, to ensure that resources claimed in this function are correctly released.

    PlgFwTextString PlgPfPSDirGetNextFile(
                      int32 fFirst, PlgFwTextString ptbzDirname, void **ppSearchState,
                      PlgFwStrRecord *pPSFilename);

Free resources allocated by directory iteration if a search is terminated incomplete

If further directory iteration using PlgPfPSDirGetNextFile is no longer required, but the previous call to PlgPfPSDirGetNextFile did not return NULL (that is, not all files in the directory have been iterated over), this function must be called to terminate the iteration and free resources and state information set by PlgPfPSDirGetNextFile .

PlgPfPSDirGetNextFileAbort should be called using the same value of ppSearchState as was passed in to PlgPfPSDirGetNextFile .

Note: Do not call this function if PlgPfPSDirGetNextFile returned NULL.

void PlgPfPSDirGetNextFileAbort(void **ppSearchState);

File name manipulation

The following functions are provided to facilitate file name parsing and manipulation. File names are considered to have the following syntax:

[<root>] [<dir name><dir separator>]* [<leafname>]

If a function expects a file name, it will reject a root name, or a directory with a trailing separator, and will set an error, plgFwErrorStringSyntax . Directories can be supplied with or without a trailing directory separator except where required by the syntax of root directories.

These functions should always be used for file name parsing for the following reasons:

• The PC directory separator ʹ\\ ʹ is also a trail byte for some HES characters;
• When handling trailing directory separators, the root directory is a special case;

The directory separator character for any given platform is assumed to be a single byte character, which can be obtained by calling PlgFwDirectorySeparator .

Retrieve the directory separator character for this platform.

This function returns the directory separator character for this platform.

PlgFwTextCharacter PlgFwDirectorySeparator(void);

Extract the root part of an absolute file name

This function parses an absolute file name to extract the root part. The root part, stripped of any plat‐ form‐specific elements, is appended to an optional string record passed into the function as a parameter. The original filename is supplied as a pointer to a pointer, which is updated to point to the first unconsumed character following the root part and any platform‐specific suffixes.

This function returns FALSE if an error such as a relative file name is encountered.

    int32 PlgFwFileParseRoot(
                        PlgFwStrRecord *pRecord, PlgFwTextString *pptbzFilename);

Example:

Figure 18.16 Example file names

Create a platform-dependent root part

This function performs the converse of PlgFwFileParseRoot . Given a platform‐independent root part, it constructs a fully‐formed platform dependent root part and appends it to pRecord . Upon error (for example, if the contents of ptbzInput are malformed), FALSE is returned and no output generated.

    int32 PlgFwFileBuildRoot(
                        PlgFwStrRecord *pRecord, PlgFwTextString ptbzInput);

Copy a root platform-dependent root part

This function copies the root part of an absolute, platform dependent file name to the record indicated by pRecord . The return value is a pointer to the first unconsumed character of the input file name. If the file name is relative, no characters are consumed, and nothing is appended to pRecord .

    PlgFwTextString PlgFwFileCopyRoot(
                        PlgFwStrRecord *pRecord, PlgFwTextString ptbzFilename);

Skip over the next element in a path name

This function takes a string containing a file name (ptbzInput) and returns a pointer to the next directory separator character in the path, or to the terminating zero if no separators remain.

    PlgFwTextString PlgFwFileSkipPathElement(
                        PlgFwTextString ptbzInput);

Copy the next element in a path name

This function takes a string containing a file name (ptbzInput) and copies the next element of the file name into the record pointed to by pRecord . The function returns a pointer to the next directory separator character in the path, or to the terminating zero if no separators remain.

    PlgFwTextString PlgFwFileCopyPathElement(
                        PlgFwStrRecord *pRecord, PlgFwTextString ptbzInput);

Strip the directory path from a file name

This function returns a pointer to the leaf part of the file name that is, to the character immediately after the final directory separator. If the file name ends in a directory separator, or if it is just a root part, the return value will be a pointer to the terminating zero.

    PlgFwTextString PlgFwFileSkipToLeafname(
                        PlgFwTextString ptbzFilename);

Detect the presence of a trailing directory separator in a file name

This function returns a pointer whose value depends on the structure of the file name passed in, as follows:

• If the file name is only a root part, the pointer returned will be to the terminating zero of the file name.
• If the filename is not a root part, but does not end with a trailing directory separator, the pointer will be returned with a value of NULL.
• If the file name does end with a trailing directory separator, the pointer will point to the final separator.

    PlgFwTextString PlgFwFileHasTrailingSeparator(
                          PlgFwTextString ptbzFilename);

Note: To avoid possible conflicts with HES encoding, the string may be scanned from the first character.

Enforce a trailing directory separator on a file name, adding one if necessary

This function appends a trailing directory separator to any file name passed in that is not an empty string and which does not already contain one. It returns TRUE if it has appended a separator, FALSE otherwise.

    int32 PlgFwFileEnsureTrailingSeparator(
                          PlgFwStrRecord *pRecord);

Enforce a trailing directory separator on a file name, adding one, if necessary, with allocation

This function appends a trailing directory separator to any file name passed in that is not an empty string and which does not already contain one. It differs from PlgFwFileEnsureTrailingSeparator in that, if the string requires a directory separator to be added, a new string is allocated, the original con‐ tents plus a directory separator are copied to it, the old string is freed and the pointer to the new string set in *pptbzFilename . It returns TRUE if it has appended a separator, FALSE otherwise. If it returns FALSE , the string pointer will not have been altered.

Note: The pointer is to a pointer to a PlgFwMem... allocated string buffer. You must not supply a pointer derived by any other means).

    int32 PlgFwFileEnsureTrailingSeparatorRealloc(
                          PlgFwTextString *pptbzFilename);

Removes any trailing directory separator from a file name

This function removes any trailing directory separator to any file name passed in, unless it consists only of a root part. It returns TRUE if it has removed a separator, FALSE otherwise. If it returns FALSE , no changes will have been made to the string.

    int32 PlgFwFileRemoveTrailingSeparator(
                          PlgFwTextString ptbzFilename);

Concatenate a relative path and an absolute directory name

This function appends the relative path supplied to an absolute directory name held in pRecord , ensuring that only one directory separator separates the two parts.

    void PlgFwFilenameConcatenate(
                          PlgFwStrRecord *pRecord, PlgFwTextString ptbzRel);

Concatenate a relative path and an absolute directory name, with allocation

Performing a similar operation to PlgFwFilenameConcatenate , this function allocates for and returns a newly‐allocated buffer (which must be freed using PlgFwMem.. . functions), to contain the concatenated strings.

    PlgFwTextString PlgFwFilenameConcatenateAlloc(
                          PlgFwTextString ptbzAbs, PlgFwTextString ptbzRel);

Validate a file name

If the file name, coerced to an absolute path name, if necessary, is valid and no longer than the limits set by the underlying platform, this function returns TRUE , else FALSE .

    int32 PlgFwFilenameLengthOK(
                          PlgFwTextString ptbzFilename);