Harlequin SDK file and path manipulation functions. More...

Files
file	file.h
	File related utility functions.

file	paths.h
	File name modification and manipulation functions.

file	pfile.h
	File related utility functions (platform-specific parts)

file	sanitize_path.h
	Utilities for sanitizing paths.

file	pfile.c
	Implementation of the skinkit file I/O interfaces, in terms of the Microsoft Windows API.

file	ppaths.c
	Path-related utility functions for pc.

file	psanitize_path.c
	Utilities for sanitizing paths.

file	file.c
	Platform independent implementation of the skinkit file I/O interfaces.

file	paths.c
	File-related utility functions.

file	sanitize_path.c
	Utilities for sanitizing paths.

Macros
#define	LONGESTFILENAME 2048
	The longest file name supported by the SDK.

#define	PS_DIRECTORY_SEPARATOR '/'
	PostScript 'directory' separator, as a character.

#define	PS_DEVICE_DELIMITER '%'
	PostScript device prefix and delimiter.

#define	DIRECTORY_SEPARATOR '\\'
	Platform-specific directory separator as a character.

#define	DIRECTORY_SEPARATOR_STRING "\\"
	Platform-specific directory separator as a string.

#define	MAX_FILENAME 255
	NTFS has a 255 character limit for filenames. More...

Typedefs
typedef struct FileDesc	FileDesc
	Opaque file descriptor structure which hides platform-specific content.

Enumerations
enum	PKError { PKErrorNone , PKErrorUnknown , PKErrorParameter , PKErrorPointerNull , PKErrorNumericRange , PKErrorNumericValue , PKErrorStringEmpty , PKErrorStringLength , PKErrorStringSyntax , PKErrorStringValue , PKErrorOperationDenied , PKErrorNonExistent , PKErrorAlreadyExists , PKErrorAccessDenied , PKErrorInUse , PKErrorOperationFailed , PKErrorAbort , PKErrorNoMemory , PKErrorDiskFull , PKErrorSoftwareLimit , PKErrorHardware , PKErrorUnimplemented , PKErrorFatal }
	This set of error returns should cover most cases – at least enough for the RIP to extract the information it needs from this platform abstraction layer. More...

Functions
HqBool	PKAppDir (uint8 *pAppDir)
	Copy, into the buffer provided, the directory in which the application executable lives. This directory will be terminated with a directory separator. More...

HqBool	PKCurrDir (uint8 *pCurrDir)
	Copy into the buffer provided the directory in which the application is running. This directory will be terminated with a directory separator. More...

HqBool	PKSWDir (uint8 *pSWDir)
	Copy the `SW` directory name into the buffer provided. This directory will be terminated with a directory separator. More...

HqBool	PKSetSWDir (const uint8 *pSWDir)
	Record an explicit path to the SW folder, overriding any default search rules. More...

HqBool	PKSWWriteRAM (void)
	Return a boolean indicating if a RAM device should be mounted for writing files. A RAM device may be used as the writable folder for files when using a union device. More...

uint8 *	PKSWWriteDir (void)
	Return the writable SW directory name, if set. More...

HqBool	PKSetSWWriteDir (uint8 *pSWDir)
	Record an explicit path to a writable SW folder. More...

HqBool	PKParseRoot (uint8 pOutput, const uint8 *ppInput)
	Parse the root part of an absolute filename *ppInput. More...

uint32	PKBuildRoot (uint8 pOutput, const uint8 pInput)
	Performs the inverse of PKParseRoot(), and builds a complete root part of a platform dependent filename from the variable part as previously output by PKParseRoot(). More...

HqBool	PKMakePSFilename (const uint8 filename, uint8 psFilename)
	Converts an absolute or relative filename to an absolute PostScript filename. Relative filenames are made absolute by prefixing the current working directory as returned by PKCurrDir(). More...

FileDesc *	PKOpenFile (const uint8 filename, int32 openflags, int32 pError)
	Open a file, with the given flags (from swdevice.h.) More...

int32	PKReadFile (FileDesc pDescriptor, uint8 buff, int32 len, int32 *pError)
	Read a specified number of bytes from a file into a buffer. More...

int32	PKWriteFile (FileDesc pDescriptor, const uint8 buff, int32 len, int32 *pError)
	Write a specified number of bytes from a buffer into a file. More...

int32	PKCloseFile (FileDesc pDescriptor, int32 pError)
	Close an open file. More...

HqBool	PKSeekFile (FileDesc pDescriptor, Hq32x2 destination, int32 flags, int32 *pError)
	Seek to a byte position within a file, with the given flags. More...

HqBool	PKBytesFile (FileDesc pDescriptor, Hq32x2 bytes, int32 reason, int32 *pError)
	Return the number of bytes in a file in the bytes parameter. More...

int32	PKStatusFile (const uint8 filename, STAT statbuff, int32 *pError)
	Populate a structure with information about a file. More...

int32	PKDeleteFile (const uint8 filename, int32 pError)
	Delete a file. More...

int32	PKRenameFile (const uint8 fromfile, const uint8 tofile, int32 *pError)
	Rename a file. More...

void *	PKFindFirstFile (const uint8 pszPattern, uint8 pszEntryName, int32 *pError)
	Find the first file matching a pattern. More...

HqBool	PKFindNextFile (void handle, uint8 pszEntryName, int32 *pError)
	Enumerate file entries matching a pattern. It returns, in pszEntryName, the path of an entry in the directory. Calls on the same handle will enumerate the matched entries until all entries have been enumerated. More...

HqBool	PKCloseFindFile (void handle, int32 pError)
	Close the file matching specified by the handle. More...

void *	PKDirOpen (const uint8 pszDirName, int32 pError)
	Open a directory. More...

HqBool	PKDirNext (void handle, uint8 pszEntryName, HqBool fIsFolder, int32 pError)
	Enumerate entries in a directory. It returns, in pszEntryName, the leaf name of an entry in the directory. Calls on the same handle will enumerate the entries in the directory until all entries have been enumerated. More...

HqBool	PKDirClose (void handle, int32 pError)
	Close the directory specified by the handle. More...

HqBool	PKOSFontDir (uint8 *pszFontDir)
	Get an explicit path to the OS font folder, converted to PostScript form (e.g., `%C%/WINDOWS/fonts/`). More...

int32	PKFilenameToUTF8 (const uint8 filename, uint8 utf8name, int32 *pError)
	Convert a partial filename to UTF-8. More...

int32	PKFlushFile (FileDesc pDescriptor, int32 pError)
	Flush an open file. More...

uint32	PSPrefixAndFilenameToPlatform (uint8 pPlatform, uint8 ptbzPSPrefix, uint8 *ptbzPSRelative)
	Converts a PostScript device name and prefix and a relative filename to a platform dependent filename. More...

uint8 *	PlatformSkipPathElement (uint8 *ptbzInput)
	Returns a pointer to the next element of a Platform filename. More...

uint32	PlatformPathElementToPS (uint8 pOutput, const uint8 *ppszInput)
	Converts a platform specific path element to a PostScript path element. Input is terminated by the platform directory separator DIRECTORY_SEPARATOR or zero. More...

uint8 *	PlatformFilenameSkipToLeafname (uint8 *ptbzPlatform)
	Returns a pointer to the leafname part of a Platform filename. More...

uint32	PlatformFilenameRootToPS (uint8 pOutput, const uint8 *pptbInput)
	Converts the root part (if any) of a platform specific filename to a PostScript device name. More...

uint32	PlatformFilenameToPS (uint8 pszOutput, const uint8 pszInput)
	Converts a platform specific filename to its PostScript equivalent. More...

uint8 *	PSFilenameSkipToLeafname (uint8 *ptbzPS)
	Returns a pointer to the leafname part of a PostScript filename. More...

uint8 *	PSFilenameSkipDevice (uint8 *ptbzPS)
	Skips the device name part (if any) of a PostScript filename. More...

uint32	PSFilenameToDevice (uint8 pszOutput, uint8 pszInput)
	Extracts the device name part (if any) of a PostScript filename. More...

HqBool	PlatformIsLeadByte (uint8 b)
	Determines if a byte is a lead byte of a platform-specific double-byte character encoding. More...

void	SanitizePathElementUtf8 (uint8 path_element, size_t length_without_null, HqBool modified)
	Convert a UTF8 path element to a valid form for the current platform. More...

void	SanitizePathUtf8 (uint8 path, size_t length_without_null, HqBool *modified)
	Convert a UTF8 path to a valid form for the current platform. More...

void	DeduplicateDirectorySeparators (uint8 path, size_t length_without_null)
	Replaces adjacent directory separators in the given path with a single directory separator. More...

Detailed Description

Harlequin SDK file and path manipulation functions.

The PSPrefixAndFilenameToPlatform() and PSFilenameToDevice() are used to convert "PostScript" filenames or parts of them to platform-specific form.

PSFilenameSkipDevice(), PSFilenameSkipToLeafname(), are used to decompose "PostScript" filenames into different parts.

PlatformSkipPathElement() and PlatformFilenameSkipToLeafname() are used to decompose platform-specific filenames into different parts or iterate over those parts.

PlatformFilenameRootToPS(), PlatformPathElementToPS(), PlatformFilenameToPS() are used to convert platform-specific filenames or parts of them to "PostScript" form.

Most file and directory pathnames used in the Harlequin RIP SDK are stored in unsigned character buffers length LONGESTFILENAME. When calling most of the file and path manipulation functions, you are required to provide buffers of this length.

The PKAppDir(), PKCurrDir(), PKSWDir() and PKSWWriteDir() functions retrieve copies of the application directory, working directory, base SW data directory and writeable SW data directory pathnames in platform-specific format. PKSetSWDir() and/or PKSetSWWriteDir() may be used to change the location of the base SW data directory and writeable SW data directory, if called before the RIP is started.

PKParseRoot() and PKBuildRoot() are used to decompose and construct the root fragments of platform-specific pathnames.

PKMakePSFilename() converts absolute or relative filenames from platform-specific to device-relative "PostScript" filenames.

PKFilenameToUTF8() converts filename components from platform-specific multi-byte encodings to UTF-8.

PKOpenFile() is used to open a platform-specific filename for reading or writing. PKReadFile(), PKWriteFile(), PKSeekFile(), PKBytesFile(), PKFlushFile() and PKCloseFile() are used to read, write, query, flush, or close files using the file descriptor it returns.

PKStatusFile() performs queries on platform-specific files.

PKDeleteFile() deletes platform-specific files. PKRenameFile() renames platform-specific files.

PKFindFirstFile(), PKFindNextFile() and PKCloseFindFile() can be used to enumerate platform-specific files matching a pattern.

PKDirOpen(), PKDirNext(), and PKDirClose() can be used to enumerate entries in a platform-specific directory.

The PKError enumeration defines the error codes that may be returned by the Harlequin RIP SDK platform abstractions. These should be mapped to HqnResult or another suitable error type before returning to the RIP. The function KMapPlatformError() performs this mapping to DEVICE_result for use in skin DEVICETYPE implementations.

SanitizePathUtf8() and SanitizePathElementUtf8() convert UTF-8 filenames or parts of them to valid filenames on the current platform by replacing illegal characters.

DeduplicateDirectorySeparators() sanitizes platform-specific filenames by removing excess directory separators.

Macro Definition Documentation

◆ MAX_FILENAME

#define MAX_FILENAME 255

NTFS has a 255 character limit for filenames.

NB: Windows Unicode APIs allow users to submit extended length paths. Such paths can be longer that the MAX_PATH limit defined by Windows.h, but individual file and dirctory names are still subject to the NTFS limit. See https://learn.microsoft.com/en-gb/windows/win32/fileio/naming-a-file for more information.

Enumeration Type Documentation

◆ PKError

enum PKError

This set of error returns should cover most cases – at least enough for the RIP to extract the information it needs from this platform abstraction layer.

Enumerator
PKErrorNone	No error.
PKErrorUnknown	Generic error failure.
PKErrorParameter	Generic problem with a supplied parameter.
PKErrorPointerNull	A pointer was null when it should not have been.
PKErrorNumericRange	A value was out of range.
PKErrorNumericValue	A value was illegal.
PKErrorStringEmpty	A string was empty when it should not have been.
PKErrorStringLength	The length of a string was illegal (usually: the string was too long)
PKErrorStringSyntax	A string was syntactically incorrect.
PKErrorStringValue	A string had an incorrect value.
PKErrorOperationDenied	Generic denial of operation.
PKErrorNonExistent	A file mentioned in an operation did not exist.
PKErrorAlreadyExists	A file already existed when attempting to create it.
PKErrorAccessDenied	Access to a file system resource was denied.
PKErrorInUse	A filesystem resource is already is use.
PKErrorOperationFailed	Generic failure.
PKErrorAbort	Operation was externally aborted.
PKErrorNoMemory	Operation failed due to lack of memory.
PKErrorDiskFull	Operation failed due to disk being full or a disk quota being exceed.
PKErrorSoftwareLimit	Operation failed due to a software limitation.
PKErrorHardware	Operation failed due to hardware error, e.g., an I/O error.
PKErrorUnimplemented	Operation failed because it is unimplemented.
PKErrorFatal	Operation failed, fatally.

Function Documentation

◆ DeduplicateDirectorySeparators()

void DeduplicateDirectorySeparators	(	uint8 *	path,
		size_t *	length_without_null
	)

Replaces adjacent directory separators in the given path with a single directory separator.

Parameters

path	The path to be modified.
length_without_null	The length of the given path, not including the zero terminator (if any).

◆ PKAppDir()

HqBool PKAppDir ( uint8 * pAppDir )

Copy, into the buffer provided, the directory in which the application executable lives. This directory will be terminated with a directory separator.

Parameters

[out] pAppDir Buffer of length LONGESTFILENAME to hold the application directory name.

Returns: TRUE on success; FALSE otherwise.

◆ PKBuildRoot()

uint32 PKBuildRoot	(	uint8 *	pOutput,
		const uint8 *	pInput
	)

Performs the inverse of PKParseRoot(), and builds a complete root part of a platform dependent filename from the variable part as previously output by PKParseRoot().

Parameters

[out]	pOutput	A buffer in which to store the platform-dependent root.
[in]	pInput	The root fragment.

Returns: The length of the platform-dependent root, excluding the zero-terminator; or 0 if the input is badly formed, in which case no output is generated.

◆ PKBytesFile()

HqBool PKBytesFile	(	FileDesc *	pDescriptor,
		Hq32x2 *	bytes,
		int32	reason,
		int32 *	pError
	)

Return the number of bytes in a file in the bytes parameter.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
bytes	The number of bytes is written into this.
reason	One of SW_BYTES_AVAIL_REL or SW_BYTES_TOTAL_ABS from swdevice.h.
pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE otherwise.

◆ PKCloseFile()

int32 PKCloseFile	(	FileDesc *	pDescriptor,
		int32 *	pError
	)

Close an open file.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
pError	A value which the function can set to one of the PKError values.

Returns: 0 on success; -1 on failure.

◆ PKCloseFindFile()

HqBool PKCloseFindFile	(	void *	handle,
		int32 *	pError
	)

Close the file matching specified by the handle.

Parameters

handle	A platform-specific find file handle, as returned from PKFindFirstFile().
pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE otherwise.

◆ PKCurrDir()

HqBool PKCurrDir ( uint8 * pCurrDir )

Copy into the buffer provided the directory in which the application is running. This directory will be terminated with a directory separator.

Parameters

[out] pCurrDir Buffer of length LONGESTFILENAME to hold the current directory name.

Returns: TRUE on success; FALSE otherwise.

◆ PKDeleteFile()

int32 PKDeleteFile	(	const uint8 *	filename,
		int32 *	pError
	)

Delete a file.

Parameters

filename	Full path to the file to be deleted.
pError	A value which the function can set to one of the PKError values.

Returns: Zero on success, non-zero otherwise.

◆ PKDirClose()

HqBool PKDirClose	(	void *	handle,
		int32 *	pError
	)

Close the directory specified by the handle.

Parameters

handle	A directory handle, as returned from PKDirOpen().
pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE otherwise.

◆ PKDirNext()

HqBool PKDirNext	(	void *	handle,
		uint8 *	pszEntryName,
		HqBool *	fIsFolder,
		int32 *	pError
	)

Enumerate entries in a directory. It returns, in pszEntryName, the leaf name of an entry in the directory. Calls on the same handle will enumerate the entries in the directory until all entries have been enumerated.

Parameters

	handle	A directory handle, as returned from PKDirOpen().
[out]	pszEntryName	Set to the leaf name of the entry enumerated.
[out]	fIsFolder	Set to `TRUE` if the entry enumerated is a directory, and `FALSE` if it is a file.
	pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE on failure or when there are no more files. If there are no more files, *pError is set to PKErrorNone.

◆ PKDirOpen()

void* PKDirOpen	(	const uint8 *	pszDirName,
		int32 *	pError
	)

Open a directory.

Parameters

pszDirName	Full path to the directory to be opened.
pError	A value which the function can set to one of the PKError values.

Returns: A platform-specific directory handle, or NULL if the operation failed. If this function succeeds, PKDirClose() must be called after use to free the directory handle.

◆ PKFilenameToUTF8()

int32 PKFilenameToUTF8	(	const uint8 *	filename,
		uint8 *	utf8name,
		int32 *	pError
	)

Convert a partial filename to UTF-8.

Parameters

	filename	A zero-terminated partial filename, which may be encoded in UTF-8 or in a platform-specific multi-byte encoding.
[out]	utf8name	A buffer of at least LONGESTFILENAME bytes in which to store the partial filename represented in UTF-8.
	pError	A value which the function can set to one of the PKError values.

Returns: The length of utf8name not including the zero terminator, or -1 on failure.

◆ PKFindFirstFile()

void* PKFindFirstFile	(	const uint8 *	pszPattern,
		uint8 *	pszEntryName,
		int32 *	pError
	)

Find the first file matching a pattern.

Parameters

pszPattern	platform file name pattern to be matched
pszEntryName	returns the first matched path Caller must ensure that its size is at least LONGESTFILENAME.
pError	A value which the function can set to one of the PKError values.

Returns: A platform-specific handle to the file find operation, or NULL if the operation failed. If this function succeeds, PKCloseFindFile() must be called after use to free the file find handle.

◆ PKFindNextFile()

HqBool PKFindNextFile	(	void *	handle,
		uint8 *	pszEntryName,
		int32 *	pError
	)

Enumerate file entries matching a pattern. It returns, in pszEntryName, the path of an entry in the directory. Calls on the same handle will enumerate the matched entries until all entries have been enumerated.

Parameters

	handle	A platform-specific find file handle, as returned from PKFindFirstFile().
[out]	pszEntryName	Set to the path name of the entry enumerated. Caller must ensure that its size is at least LONGESTFILENAME.
	pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE otherwise.

◆ PKFlushFile()

int32 PKFlushFile	(	FileDesc *	pDescriptor,
		int32 *	pError
	)

Flush an open file.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
pError	A value which the function can set to one of the PKError values.

Returns: 0 on success; -1 on failure.

◆ PKMakePSFilename()

HqBool PKMakePSFilename	(	const uint8 *	filename,
		uint8 *	psFilename
	)

Converts an absolute or relative filename to an absolute PostScript filename. Relative filenames are made absolute by prefixing the current working directory as returned by PKCurrDir().

Parameters

[in]	filename	The platform-dependent root
[out]	psFilename	A buffer of at least LONGESTFILENAME bytes in which to store the PS filename.

Returns: TRUE on success; FALSE on failure.

◆ PKOpenFile()

FileDesc* PKOpenFile	(	const uint8 *	filename,
		int32	openflags,
		int32 *	pError
	)

Open a file, with the given flags (from swdevice.h.)

Parameters

filename	Full path of the file to be opened
openflags	Flags to control the way in which the file is opened. See DEVICELIST_OPEN.
pError	A value which the function can set to one of the PKError values.

Returns: The file descriptor if open was successful; NULL otherwise.

◆ PKOSFontDir()

HqBool PKOSFontDir ( uint8 * pszFontDir )

Get an explicit path to the OS font folder, converted to PostScript form (e.g., %C%/WINDOWS/fonts/).

Parameters

pszFontDir Pointer to memory at least LONGESTFILENAME bytes in length, which on output contains the OS font folder path (terminated with a directory separator), converted to a PostScript path.

Returns: TRUE on success; FALSE otherwise.

◆ PKParseRoot()

HqBool PKParseRoot	(	uint8 *	pOutput,
		const uint8 **	ppInput
	)

Parse the root part of an absolute filename *ppInput.

Parameters

[out]	pOutput	A buffer in which to store the root fragment (if non-`NULL`).
[in,out]	ppInput	An absolute filename. *ppInput is updated to point to first unconsumed character of input.

For example:

     Input                   Output                  Remaining input
PC   "C:\..."                "C"                     "..."
     "\\machine\drive\..."   "machine\drive"         "..."

Unix "/..."                  ""                      "..."

Returns: FALSE if the filename is relative; TRUE if the filename is absolute. If the filename is absolute and pOutput is non-NULL the variable part of the root, excluding any platform specific root prefixes and suffices is stored in it.

◆ PKReadFile()

int32 PKReadFile	(	FileDesc *	pDescriptor,
		uint8 *	buff,
		int32	len,
		int32 *	pError
	)

Read a specified number of bytes from a file into a buffer.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
buff	Buffer into which the data read is stored.
len	The maximum number of bytes to read.
pError	A value which the function can set to one of the PKError values.

Returns: The number of bytes read, if successful; -1 otherwise.

◆ PKRenameFile()

int32 PKRenameFile	(	const uint8 *	fromfile,
		const uint8 *	tofile,
		int32 *	pError
	)

Rename a file.

Parameters

fromfile	Full path to the original file name.
tofile	Full path to the new file name.
pError	A value which the function can set to one of the PKError values.

Returns: Zero on success, non-zero otherwise.

◆ PKSeekFile()

HqBool PKSeekFile	(	FileDesc *	pDescriptor,
		Hq32x2 *	destination,
		int32	flags,
		int32 *	pError
	)

Seek to a byte position within a file, with the given flags.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
destination	The location to seek to.
flags	One of SW_SET, SW_INCR, SW_XTND. See DEVICELIST_SEEK.
pError	A value which the function can set to one of the PKError values.

Returns: TRUE on success; FALSE otherwise.

◆ PKSetSWDir()

HqBool PKSetSWDir ( const uint8 * pSWDir )

Record an explicit path to the SW folder, overriding any default search rules.

Parameters

[in] pSWDir Pointer to a UTF-8 encoded zero-terminated path, which may not exceed LONGESTFILENAME in length (inclusive of the terminator), and which must end with a directory separator.

Returns: TRUE on success; FALSE otherwise.

◆ PKSetSWWriteDir()

HqBool PKSetSWWriteDir ( uint8 * pSWDir )

Record an explicit path to a writable SW folder.

Parameters

pSWDir Pointer to a zero-terminated path, which may not exceed LONGESTFILENAME in length (inclusive of the terminator), and which must end with a directory separator.

Returns: TRUE on success; FALSE otherwise.

◆ PKStatusFile()

int32 PKStatusFile	(	const uint8 *	filename,
		STAT *	statbuff,
		int32 *	pError
	)

Populate a structure with information about a file.

Parameters

filename	The file to check status.
statbuff	Pointer to a structure in which to put the file status.
pError	A value which the function can set to one of the PKError values.

Returns: 0 on success; -1 otherwise.

◆ PKSWDir()

HqBool PKSWDir ( uint8 * pSWDir )

Copy the SW directory name into the buffer provided. This directory will be terminated with a directory separator.

Parameters

[out] pSWDir Buffer of length LONGESTFILENAME to hold the SW directory name.

Returns: TRUE on success; FALSE otherwise.

◆ PKSWWriteDir()

uint8* PKSWWriteDir ( void )

Return the writable SW directory name, if set.

Returns: The writable SW directory (set by PKSetSWWriteDir()) if set, or NULL if not set.

◆ PKSWWriteRAM()

HqBool PKSWWriteRAM ( void )

Return a boolean indicating if a RAM device should be mounted for writing files. A RAM device may be used as the writable folder for files when using a union device.

Return values

TRUE	If a RAM device should be used for writable files.
FALSE	If a file device should be used for writable files.

◆ PKWriteFile()

int32 PKWriteFile	(	FileDesc *	pDescriptor,
		const uint8 *	buff,
		int32	len,
		int32 *	pError
	)

Write a specified number of bytes from a buffer into a file.

Parameters

pDescriptor	The file descriptor, as returned from PKOpenFile().
buff	Buffer from which the data is written.
len	The maximum number of bytes to write.
pError	A value which the function can set to one of the PKError values.

Returns: The number of bytes written, if successful; -1 otherwise.

◆ PlatformFilenameRootToPS()

uint32 PlatformFilenameRootToPS	(	uint8 *	pOutput,
		const uint8 **	pptbInput
	)

Converts the root part (if any) of a platform specific filename to a PostScript device name.

Parameters

[out]	pOutput	A buffer of at least LONGESTFILENAME bytes to store the converted device name in.
[in,out]	pptbInput	A pointer to the input platform filename. This will be updated to point at the remainder of the platform name after the root is converted to a device.

Returns: The number of bytes written to the output buffer excluding the terminating zero.

◆ PlatformFilenameSkipToLeafname()

uint8* PlatformFilenameSkipToLeafname ( uint8 * ptbzPlatform )

Returns a pointer to the leafname part of a Platform filename.

Parameters

[in] ptbzPlatform A zero-terminated platform filename.

Returns: A pointer in ptbzPlatform, immediately after the last DIRECTORY_SEPARATOR. If there is is no DIRECTORY_SEPARATOR ptbzPlatform is returned.

◆ PlatformFilenameToPS()

uint32 PlatformFilenameToPS	(	uint8 *	pszOutput,
		const uint8 *	pszInput
	)

Converts a platform specific filename to its PostScript equivalent.

Parameters

[out]	pszOutput	A buffer of at least LONGESTFILENAME bytes to store the converted filename.
[in]	pszInput	The plaform filename to convert to PS form.

Returns: The number of bytes written to the output buffer excluding the terminating zero.

◆ PlatformIsLeadByte()

HqBool PlatformIsLeadByte ( uint8 b )

Determines if a byte is a lead byte of a platform-specific double-byte character encoding.

Parameters

b	The encoded byte.

Returns: TRUE if b is a lead byte, FALSE if not.

◆ PlatformPathElementToPS()

uint32 PlatformPathElementToPS	(	uint8 *	pOutput,
		const uint8 **	ppszInput
	)

Converts a platform specific path element to a PostScript path element. Input is terminated by the platform directory separator DIRECTORY_SEPARATOR or zero.

Parameters

[out]	pOutput	A buffer of at least LONGESTFILENAME bytes to store the converted PS path element name.
[in,out]	ppszInput	A pointer to the input platform filename. This will be updated to point at the terminating DIRECTORY_SEPARATOR or zero for the current path element.

Returns: The number of bytes written to the output buffer, excluding any terminating zero.

◆ PlatformSkipPathElement()

uint8* PlatformSkipPathElement ( uint8 * ptbzInput )

Returns a pointer to the next element of a Platform filename.

Parameters

[in] ptbzInput A platform filename, not including the root part.

Returns: A pointer to the next DIRECTORY_SEPARATOR in ptbzinput, or to the terminator if ptbzInput points to a leafname.

◆ PSFilenameSkipDevice()

uint8* PSFilenameSkipDevice ( uint8 * ptbzPS )

Skips the device name part (if any) of a PostScript filename.

Parameters

[in] ptbzPS A PostScript filename.

Returns: A pointer to the character immediately after the second PS_DEVICE_DELIMITER in ptbzPS, or ptbzPS if there is no device name part.

◆ PSFilenameSkipToLeafname()

uint8* PSFilenameSkipToLeafname ( uint8 * ptbzPS )

Returns a pointer to the leafname part of a PostScript filename.

Parameters

[in] ptbzPS A PS filename to extract the leafname from.

Returns: A pointer to the character immediately after the last PS_DIRECTORY_SEPARATOR. This will be a pointer to the zero terminator if ptbzPS ends with a PS_DIRECTORY_SEPARATOR, unless the filename consists of only a device name, in which case a pointer to the device name (i.e., ptbzPS) is returned.

◆ PSFilenameToDevice()

uint32 PSFilenameToDevice	(	uint8 *	pszOutput,
		uint8 *	pszInput
	)

Extracts the device name part (if any) of a PostScript filename.

Parameters

[out]	pszOutput	A buffer of at least LONGESTFILENAME bytes to store the extracted device name in.
[in]	pszInput	A PostScript filename.

Returns: The number of bytes written to the output record, not including the terminating zero. The PS_DEVICE_DELIMITER characters are excluded from the output device name.

◆ PSPrefixAndFilenameToPlatform()

uint32 PSPrefixAndFilenameToPlatform	(	uint8 *	pPlatform,
		uint8 *	ptbzPSPrefix,
		uint8 *	ptbzPSRelative
	)

Converts a PostScript device name and prefix and a relative filename to a platform dependent filename.

Parameters

[out]	pPlatform	A buffer of at least LONGESTFILENAME bytes to store the platform-dependent filename in.
[in]	ptbzPSPrefix	A UTF-8 encoded PS device name and prefix.
[in]	ptbzPSRelative	A PS filename relative to the prefix location. This filename may be encoded in a platform-specific multi-byte character set.

Returns: The number of bytes written to the output buffer excluding the terminating zero, or 0 if the operation failed.

This function takes any device name from ptbzPSPrefix to form the root, and combines the remainder of ptbzPSPrefix with ptbzPSRelative to form the path name.

◆ SanitizePathElementUtf8()

void SanitizePathElementUtf8	(	uint8 *	path_element,
		size_t	length_without_null,
		HqBool *	modified
	)

Convert a UTF8 path element to a valid form for the current platform.

Any illegal characters will be replaced by a hyphen (-).

Parameters

[in,out]	path_element	A UTF8-encoded string to be converted into a valid path element.
	length_without_null	The number of bytes in the path element, not including any zero terminators.
[out]	modified	TRUE if the path element was modified, otherwise FALSE. The value is unspecified if the function returns FALSE.

◆ SanitizePathUtf8()

void SanitizePathUtf8	(	uint8 *	path,
		size_t *	length_without_null,
		HqBool *	modified
	)

Convert a UTF8 path to a valid form for the current platform.

Any illegal characters will be replaced by a hyphen (-). Consecutive directory separators will be de-duplicated.

Parameters

[in,out]	path	A UTF8-encoded string to be converted into a valid path.
[in,out]	length_without_null	The number of bytes in the path, not including any zero terminators. This may be modified on output if the path is shortened.
[out]	modified	TRUE if the path was modified, otherwise FALSE. The value is unspecified if the function returns FALSE.

Files

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MAX_FILENAME

Enumeration Type Documentation

◆ PKError

Function Documentation

◆ DeduplicateDirectorySeparators()

◆ PKAppDir()

◆ PKBuildRoot()

◆ PKBytesFile()

◆ PKCloseFile()

◆ PKCloseFindFile()

◆ PKCurrDir()

◆ PKDeleteFile()

◆ PKDirClose()

◆ PKDirNext()

◆ PKDirOpen()

◆ PKFilenameToUTF8()

◆ PKFindFirstFile()

◆ PKFindNextFile()

◆ PKFlushFile()

◆ PKMakePSFilename()

◆ PKOpenFile()

◆ PKOSFontDir()

◆ PKParseRoot()

◆ PKReadFile()

◆ PKRenameFile()

◆ PKSeekFile()

◆ PKSetSWDir()

◆ PKSetSWWriteDir()

◆ PKStatusFile()

◆ PKSWDir()

◆ PKSWWriteDir()

◆ PKSWWriteRAM()

◆ PKWriteFile()

◆ PlatformFilenameRootToPS()

◆ PlatformFilenameSkipToLeafname()

◆ PlatformFilenameToPS()

◆ PlatformIsLeadByte()

◆ PlatformPathElementToPS()

◆ PlatformSkipPathElement()

◆ PSFilenameSkipDevice()

◆ PSFilenameSkipToLeafname()

◆ PSFilenameToDevice()

◆ PSPrefixAndFilenameToPlatform()

◆ SanitizePathElementUtf8()

◆ SanitizePathUtf8()