AIFilePathSuite Struct Reference
[API Suite List]

Provides cross-platform file referencing. More...

#include <AIFilePath.h>

Public Attributes
AIErr AIAPI(*	NewFilePath )(ai::FilePath &path)
	Creates a new, empty file path object.
AIErr AIAPI(*	DeleteFilePath )(ai::FilePath &path)
	Disposes of a file path object.
AIErr AIAPI(*	Copy )(const ai::FilePath &src, ai::FilePath &dest)
	Copies a file path object.
AIBool8 AIAPI(*	IsEmpty )(const ai::FilePath &path)
	Reports whether a file path object references a file.
void AIAPI(*	MakeEmpty )(ai::FilePath &path)
	Sets a file path object to reference a null path.
AIBool8 AIAPI(*	Equal )(const ai::FilePath &a, const ai::FilePath &b, const AIBool8 resolveLinks)
	Reports whether two file path object reference the same file, regardless of whether that file exists.
AIBool8 AIAPI(*	LessThan )(const ai::FilePath &a, const ai::FilePath &b)
	Reports whether one file path string is before another, alphabetically.
AIBool8 AIAPI(*	StartsWithDelimiter )(const ai::FilePath &path)
	Reports whether a file path string starts with a delimiter.
AIBool8 AIAPI(*	EndsWithDelimiter )(const ai::FilePath &path)
	Reports whether a file path string ends with a delimiter.
AIErr AIAPI(*	AddComponent )(const ai::UnicodeString &addend, ai::FilePath &augend)
	Adds a component to the path of a file path object, inserting the appropriate delimiter character as necessary.
void AIAPI(*	RemoveComponent )(ai::FilePath &path)
	Removes the end component from the path of a file path object.
void AIAPI(*	AddExtension )(const ai::UnicodeString &ext, ai::FilePath &path)
	Adds a file extension to the path of a file path object.
void AIAPI(*	RemoveExtension )(ai::FilePath &path)
	Removes the file extension from the path of a file path object.
AIBool8 AIAPI(*	Exists )(const ai::FilePath &path, const AIBool8 resolveLinks, ai::UnicodeString longPath, AIBool8 isFile)
	Reports whether the file or directory referenced by a file path object exists in the file system.
AIErr AIAPI(*	Resolve )(ai::FilePath &path)
	Resolves an alias or shortcut by querying the file system.
AIErr AIAPI(*	Set )(const ai::UnicodeString &pathString, AIBool8 expandName, ai::FilePath &path)
	Sets a file path from a Unicode string.
void AIAPI(*	SetFromSPFileRef )(const SPPlatformFileReference &, ai::FilePath &path)
	Sets a file path from a file specification.
AIErr AIAPI(*	SetFromCFString )(const CFStringRef, ai::FilePath &path)
	Sets a file path from a `CFString` string specification (in Mac OS only).
AIErr AIAPI(*	SetFromFSRef )(const FSRef &, ai::FilePath &path)
	Sets a file path from an `FSRef` file specification (in Mac OS only).
void AIAPI(*	SetFromCFURL )(const CFURLRef, ai::FilePath &path)
	Sets a file path from an `CFURL` URL specification (in Mac OS only).
AIErr AIAPI(*	GetFileName )(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &fileName)
	Retrieves the file name from a file path object.
AIErr AIAPI(*	GetFileNameNoExt )(const ai::FilePath &path, ai::UnicodeString &fileNameNoExt)
	Retrieves the file name from a file path object, without any extension or path.
AIErr AIAPI(*	GetFileExtension )(const ai::FilePath &path, ai::UnicodeString &ext)
	Retrieves the file extension from a file path object.
AIErr AIAPI(*	GetFullPath )(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &fullPath)
	Retrieves the full path from a file path object, in platform-specific notation.
AIErr AIAPI(*	GetDirectory )(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &directory)
	Retrieves the directory or folder from a file path object, in platform-specific notation.
AIErr AIAPI(*	GetShortPath )(const ai::FilePath &path, ai::UnicodeString &shortPath)
	Retrieves the short version of the path from a file path object, in platform-specific notation.
AIErr AIAPI(*	GetParent )(const ai::FilePath &path, ai::FilePath &parent)
	Retrieves the parent directory or folder for a file path object, as a file path object.
char AIAPI(*	GetDelimiter )(void)
	Retrieves the path component delimiter for the current platform.
void AIAPI(*	GetVolumeAndParent )(const ai::FilePath &path, FSVolumeRefNum vol, ai::uint32 parent)
	Retrieves the volume and parent of a file path (in Mac OS only).
AIErr AIAPI(*	GetCreatorAndType )(const ai::FilePath &path, ai::uint32 creator, ai::uint32 type)
	Retrieves the file creator and type of a file path as a four-character code (in Mac OS only, outside Illustrator core).
AIErr AIAPI(*	GetAsURL )(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &url)
	Retrieves the path as a URL from a file path object.
AIErr AIAPI(*	GetAsSPPlatformFileRef )(const ai::FilePath &path, SPPlatformFileReference &spPlatformFileRef)
	Retrieves the path as a file specification from a file path object.
CFStringRef AIAPI(*	GetAsCFString )(const ai::FilePath &path)
	Retrieves a file path as a `CFString` string specification (in Mac OS only).
OSStatus AIAPI(*	GetAsFSRef )(const ai::FilePath &path, FSRef &fsRef)
	Retrieves a file path as an `FSRef` file specification (in Mac OS only).
CFURLRef AIAPI(*	GetAsCFURL )(const ai::FilePath &path)
	Retrieves a file path as a `CFURL` specification (in Mac OS only).
void AIAPI(*	ResetVolumeCache )(void)
	Resets the volume cache.

Detailed Description

Provides cross-platform file referencing.

Use the ai::FilePath wrapper class rather than calling these functions directly.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIFilePathSuite and kAIFilePathVersion.

Member Data Documentation

AIErr AIAPI(* AIFilePathSuite::AddComponent)(const ai::UnicodeString &addend, ai::FilePath &augend)

Adds a component to the path of a file path object, inserting the appropriate delimiter character as necessary.

Does not add a delimiter at the end unless it is explicitly specified in the addend string.

Parameters:

	addend	The component to add.
	augend	[in, out] The file path object.

void AIAPI(* AIFilePathSuite::AddExtension)(const ai::UnicodeString &ext, ai::FilePath &path)

Adds a file extension to the path of a file path object.

Adds or ignores dots as needed so that one dot appears before the extension. (Note that this function has no return value.)

Parameters:

	ext	The extension string.
	path	[in, out] The file path object.

AIErr AIAPI(* AIFilePathSuite::Copy)(const ai::FilePath &src, ai::FilePath &dest)

Copies a file path object.

Does not affect the referenced file.

Parameters:

	src	The file path object to copy.
	dest	[out] A buffer in which to return the new file path object, which references the same file.

AIErr AIAPI(* AIFilePathSuite::DeleteFilePath)(ai::FilePath &path)

Disposes of a file path object.

Does not affect the referenced file.

Parameters:

path

The file path object.

AIBool8 AIAPI(* AIFilePathSuite::EndsWithDelimiter)(const ai::FilePath &path)

Reports whether a file path string ends with a delimiter.

Parameters:

path

The file path object.

Returns:: True if the file path name ends with a delimiter.

AIBool8 AIAPI(* AIFilePathSuite::Equal)(const ai::FilePath &a, const ai::FilePath &b, const AIBool8 resolveLinks)

Reports whether two file path object reference the same file, regardless of whether that file exists.

(Note that this function returns a boolean value, not an error code.)

Parameters:

	a	The first file path object.
	b	The second file path object.
	resolveLinks	When true, determine if the two objects refer to the same file through links, aliases, or shortcuts by querying the file system.

Returns:: True if the objects are identical, or if resolveLinks is true and the objects reference the same file.
False if resolveLinks is false and the objects are not identical, or if resolveLinks is true and the objects reference different files,

AIBool8 AIAPI(* AIFilePathSuite::Exists)(const ai::FilePath &path, const AIBool8 resolveLinks, ai::UnicodeString *longPath, AIBool8 *isFile)

Reports whether the file or directory referenced by a file path object exists in the file system.

(Note that this function returns a boolean value, not an error code.)

Parameters:

	path	The file path object.
	resolveLinks	When true, resolve links, aliases, and shortcuts for `longPath`.
	longPath	[out] Optional. A buffer in which to return a full long, Unicode version of the path. Use to convert short path names to their long counterparts. Can be null. Returns undefined if the file or directory does not exist.
	isFile	[out] Optional. A buffer in which to return true if the object references an existing file, false if it references an existing directory. Can be null. Returns undefined if the file or directory does not exist.

Returns:: True if the referenced file or directory exists.

CFStringRef AIAPI(* AIFilePathSuite::GetAsCFString)(const ai::FilePath &path)

Retrieves a file path as a CFString string specification (in Mac OS only).

(Note that this function returns a string value, not an error code.)

Parameters:

path

The file path object.

Returns:: The path string. The caller is responsible for releasing it.

CFURLRef AIAPI(* AIFilePathSuite::GetAsCFURL)(const ai::FilePath &path)

Retrieves a file path as a CFURL specification (in Mac OS only).

(Note that this function returns a string value, not an error code.)

Parameters:

path

The file path object.

Returns:: The URL specification.

OSStatus AIAPI(* AIFilePathSuite::GetAsFSRef)(const ai::FilePath &path, FSRef &fsRef)

Retrieves a file path as an FSRef file specification (in Mac OS only).

(Note that this function returns an OS status value, not an error code.)

Parameters:

	path	The file path object.
	fsRef	[out] A buffer in which to return the file specification.

Returns:: The OS status.

AIErr AIAPI(* AIFilePathSuite::GetAsSPPlatformFileRef)(const ai::FilePath &path, SPPlatformFileReference &spPlatformFileRef)

Retrieves the path as a file specification from a file path object.

Parameters:

	path	The file path object
	spPlatformFileSpec	[out] A buffer in which to return the file specification.

AIErr AIAPI(* AIFilePathSuite::GetAsURL)(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &url)

Retrieves the path as a URL from a file path object.

The URL contains only ASCII characters and special characters escaped with URL percent (\%) encoding.

Parameters:

	path	The file path object
	displayName	When true, get the display name. Attempts to translate a truncated short name to the full name.
	url	[out] A buffer in which to return the URL string.

AIErr AIAPI(* AIFilePathSuite::GetCreatorAndType)(const ai::FilePath &path, ai::uint32 *creator, ai::uint32 *type)

Retrieves the file creator and type of a file path as a four-character code (in Mac OS only, outside Illustrator core).

Parameters:

	path	The file path object.
	creator	[out] A buffer in which to return the creator code.
	type	[out] A buffer in which to return the type code.

char AIAPI(* AIFilePathSuite::GetDelimiter)(void)

Retrieves the path component delimiter for the current platform.

(Note that this function returns a character, not an error code.

Returns:: The delimiter character ("/" or "\"),

AIErr AIAPI(* AIFilePathSuite::GetDirectory)(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &directory)

Retrieves the directory or folder from a file path object, in platform-specific notation.

The string ends with a delimiter. If the path represents a directory or folder, this result is the same as for GetFullPath().

Parameters:

	path	The file path object
	displayName	When true, get the display name. Attempts to translate a truncated short name to the full name.
	directory	[out] A buffer in which to return the directory name string.

AIErr AIAPI(* AIFilePathSuite::GetFileExtension)(const ai::FilePath &path, ai::UnicodeString &ext)

Retrieves the file extension from a file path object.

Does not include the dot.

Parameters:

	path	The file path object
	ext	[out] A buffer in which to return the file extension string.

AIErr AIAPI(* AIFilePathSuite::GetFileName)(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &fileName)

Retrieves the file name from a file path object.

Includes the extension, if any, but does not include the path.

Parameters:

	path	The file path object
	displayName	When true, get the display name. Attempts to translate a truncated short name to the full name.
	fileName	[out] A buffer in which to return the file name string.

AIErr AIAPI(* AIFilePathSuite::GetFileNameNoExt)(const ai::FilePath &path, ai::UnicodeString &fileNameNoExt)

Retrieves the file name from a file path object, without any extension or path.

Parameters:

	path	The file path object
	fileNameNoExt	[out] A buffer in which to return the file name string.

AIErr AIAPI(* AIFilePathSuite::GetFullPath)(const ai::FilePath &path, const AIBool8 displayName, ai::UnicodeString &fullPath)

Retrieves the full path from a file path object, in platform-specific notation.

Parameters:

	path	The file path object
	displayName	When true, get the display name. Attempts to translate a truncated short name to the full name.
	fullPath	[out] A buffer in which to return the path string.

AIErr AIAPI(* AIFilePathSuite::GetParent)(const ai::FilePath &path, ai::FilePath &parent)

Retrieves the parent directory or folder for a file path object, as a file path object.

If the path is a directory, retrieves its parent directory. Does not access the file system. Use Exists() or Resolve() to ensure a path is valid.

Parameters:

	path	The file path object.
	parent	[out] A buffer in which to return the path object for the parent. Can be the same instance passed in, in which case it is modified to reference the parent. Returns an empty path if the given path is for a top-level volume.

AIErr AIAPI(* AIFilePathSuite::GetShortPath)(const ai::FilePath &path, ai::UnicodeString &shortPath)

Retrieves the short version of the path from a file path object, in platform-specific notation.

The referenced file or folder must exist.

Parameters:

path

The file path object

shortPath

[out] A buffer in which to return the path string, or an empty string in case of error..

In Windows, conforms to 8.3 format.
In Mac OS X, name can be truncated and a file ID appended. If the file ID is needed, the path is not valid across processes.

void AIAPI(* AIFilePathSuite::GetVolumeAndParent)(const ai::FilePath &path, FSVolumeRefNum *vol, ai::uint32 *parent)

Retrieves the volume and parent of a file path (in Mac OS only).

(Note that this function does not return an error code.)

Parameters:

	path	The file path object.
	vol	[out] A buffer in which to return the volume. Can be `null`.
	parent	[out] A buffer in which to return the parent. Can be `null`.

AIBool8 AIAPI(* AIFilePathSuite::IsEmpty)(const ai::FilePath &path)

Reports whether a file path object references a file.

(Note that this function returns a boolean value, not an error code.)

Parameters:

path

The file path object.

Returns:: True if the object is empty (does not reference a file).

AIBool8 AIAPI(* AIFilePathSuite::LessThan)(const ai::FilePath &a, const ai::FilePath &b)

Reports whether one file path string is before another, alphabetically.

(Note that this function returns a boolean value, not an error code.)

Parameters:

	a	The first file path object.
	b	The second file path object.

Returns:: True if a < b in a string comparison of file path names.

void AIAPI(* AIFilePathSuite::MakeEmpty)(ai::FilePath &path)

Sets a file path object to reference a null path.

(Note that this function has no return value.)

Parameters:

path

The file path object.

AIErr AIAPI(* AIFilePathSuite::NewFilePath)(ai::FilePath &path)

Creates a new, empty file path object.

Parameters:

path

[out] A buffer in which to return the file path object.

void AIAPI(* AIFilePathSuite::RemoveComponent)(ai::FilePath &path)

Removes the end component from the path of a file path object.

(Note that this function has no return value.)

Parameters:

path

The file path object.

void AIAPI(* AIFilePathSuite::RemoveExtension)(ai::FilePath &path)

Removes the file extension from the path of a file path object.

(Note that this function has no return value.)

Parameters:

path

[in, out] The file path object.

void AIAPI(* AIFilePathSuite::ResetVolumeCache)(void)

Resets the volume cache.

Does not return an error code.

AIErr AIAPI(* AIFilePathSuite::Resolve)(ai::FilePath &path)

Resolves an alias or shortcut by querying the file system.

The referenced file or directory must exist.

Parameters:

path

[in, out] The file path object to resolve and return. Upon return, the path object points directly to the target file.

AIErr AIAPI(* AIFilePathSuite::Set)(const ai::UnicodeString &pathString, AIBool8 expandName, ai::FilePath &path)

Sets a file path from a Unicode string.

Parameters:

	pathString	The new path, can be a path native to Windows, UNIX, or Mac OS, or a URL.
	expandName	When true, the function attempts to expand the provided path string into a full name (for example, for a short, truncated name in Windows).
	path	The file path object.

AIErr AIAPI(* AIFilePathSuite::SetFromCFString)(const CFStringRef, ai::FilePath &path)

Sets a file path from a CFString string specification (in Mac OS only).

Parameters:

	string	The new path.
	path	The file path object.

void AIAPI(* AIFilePathSuite::SetFromCFURL)(const CFURLRef, ai::FilePath &path)

Sets a file path from an CFURL URL specification (in Mac OS only).

Parameters:

	url	The new URL.
	path	The file path object.

AIErr AIAPI(* AIFilePathSuite::SetFromFSRef)(const FSRef &, ai::FilePath &path)

Sets a file path from an FSRef file specification (in Mac OS only).

Parameters:

	file	The new file.
	path	The file path object.

void AIAPI(* AIFilePathSuite::SetFromSPFileRef)(const SPPlatformFileReference &, ai::FilePath &path)

Sets a file path from a file specification.

Parameters:

	file	The new file.
	path	The file path object.

AIBool8 AIAPI(* AIFilePathSuite::StartsWithDelimiter)(const ai::FilePath &path)

Reports whether a file path string starts with a delimiter.

(Note that this function returns a boolean value, not an error code.)

Parameters:

path

The file path object.

Returns:: True if the file path name starts with a delimiter.

The documentation for this struct was generated from the following file:

AIFilePath.h

AIFilePathSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIFilePathSuite Struct Reference
[API Suite List]