ai::FilePath Class Reference

#include <IAIFilePath.hpp>

List of all members.

Public Member Functions
	FilePath () AINOTHROW
	Default constructor.
	FilePath (const FilePath &)
	Copies a file-path object.
	FilePath (const ai::UnicodeString &path, bool expandName=true)
	Creates an initialized file-path object from a Unicode string containing a path native to Windows, Unix, or Mac OS, or a URL.
	FilePath (const MiFile &)
	Creates as intialized file-path object from a file reference.
	FilePath (const SPPlatformFileReference &)
	FilePath (const CFStringRef)
	Creates an initialized file-path object from a CFString file specification in Mac OS.
	FilePath (const CFURLRef)
	Creates an initialized file-path object from a FSRef file specification in Mac OS.
	~FilePath ()
	Destructor.
FilePath &	operator= (const FilePath &)
	Assignment operator.
bool	IsEmpty () const
	Reports whether a file-path object is empty.
void	MakeEmpty ()
	Sets the referenced path of this object to a NULL path.
bool	Equal (const FilePath &filePath, const bool resolveLinks=false) const
	Compares this file path to another for equality.
bool	operator== (const FilePath &) const
	Equality operator.
bool	operator!= (const FilePath &) const
	Inequality operator.
bool	operator< (const FilePath &) const
	Less-than operator, compares file path strings.
bool	StartsWithDelimiter () const
	Reports whether this path starts with a delimiter, and is therefore an absolute, not relative, path.
bool	EndsWithDelimiter () const
	Reports whether this path ends with a delimiter, and therefore references a folder or directory, rather than a file.
void	AddComponent (const ai::UnicodeString &addend=ai::UnicodeString())
	Adds a component to this path.
void	AddComponent (const FilePath &addend)
	Adds a component to this path.
void	RemoveComponent ()
	Removes the end component from this path.
void	AddExtension (const ai::UnicodeString &ext)
	Adds a file extension to this path.
void	AddExtension (const std::string &ext)
	Adds a file extension to this path.
void	RemoveExtension ()
	Removes the file extension, if any, from this path.
bool	Exists (const bool resolveLinks, ai::UnicodeString *longPath=0, bool *isFile=0) const
	Reports whether this file or directory exists after querying the file system.
void	Resolve ()
	Resolves any alias or shortcut for this path by querying file system, and alters the object to point directly to the target file.
void	Set (const ai::UnicodeString &path, bool expandName=true)
	Sets this file path from a Unicode string containing a path native to Windows, Unix, or Mac OS, or a URL.
void	SetFromMiFile (const MiFile &)
	Internal.
void	SetFromSPFileRef (const SPPlatformFileReference &)
void	SetFromCFString (const CFStringRef)
	Sets this file path from an CFStringRef file specification in Mac OS.
void	SetFromCFURL (const CFURLRef)
	Sets this file path from an FSRef file specification in Mac OS.
ai::UnicodeString	GetFileName (const bool displayName=false) const
	Retrieves the file name including an extension, if applicable, but without the path.
ai::UnicodeString	GetFileNameNoExt () const
	Retrieves the file name without the extension and path.
ai::UnicodeString	GetFileExtension () const
	Retrieves the file extension, without the dot, or NULL if the file name ends with a dot.
ai::UnicodeString	GetFullPath (const bool displayName=false) const
	Retrieves the full path in notation native to the current platform.
ai::UnicodeString	GetDirectory (const bool displayName=false) const
	Retrieves the directory name, ending with a delimiter, without the filename, in notation native to the current platform.
ai::UnicodeString	GetShortPath () const
	Retrieves an operating-system-specific short version of the path.
FilePath	GetParent () const
	Retrieves the parent of the object represented by this path.
AIErr	GetCreatorAndType (ai::uint32 *creator, ai::uint32 *type) const
	Retrieves the creator and type of this file or directory (4-character codes) in Mac OS.
ai::UnicodeString	GetAsURL (const bool displayName) const
	Retrieves this path as a Uniform Resource Locator (URL), which contains only ASCII characters; any special characters are escaped with URL percent (%) encoding.
void	GetAsSPPlatformFileRef (SPPlatformFileReference &) const
AIErr	GetAsMiFile (MiFile &) const
	Internal.
AIErr	GetAsMiFile (MiFile *&) const
	Internal.
CFStringRef	GetAsCFString () const
	Creates a CFString from this file path in Mac OS.
CFURLRef	GetAsCFURL () const
	Creates an FSRef from this file path in Mac OS.
Static Public Member Functions
static void	ResetVolumeCache () AINOTHROW
	Resets cached information about volumes, used to increase the efficiency of filesystem operations.
static const char	GetDelimiter () AINOTHROW
	Return the relative path of 'path' to 'base'.

---

Constructor & Destructor Documentation

ai::FilePath::FilePath

(

)

Default constructor.

Creates an empty file-path object.

ai::FilePath::FilePath

(

const FilePath &

)

Copies a file-path object.

ai::FilePath::FilePath	(	const ai::UnicodeString &	path,
		bool	expandName = true
	)			[explicit]

Creates an initialized file-path object from a Unicode string containing a path native to Windows, Unix, or Mac OS, or a URL.

Parameters:

	path	The new path.
	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).

Returns:

The new object.

ai::FilePath::FilePath

(

const MiFile &

)

[explicit]

Creates as intialized file-path object from a file reference.

Internal. Creates an initialized file-path object from a MiFile (Illustrator core only).

ai::FilePath::FilePath

(

const SPPlatformFileReference &

)

[explicit]

ai::FilePath::FilePath

(

const

CFStringRef

)

[explicit]

Creates an initialized file-path object from a CFString file specification in Mac OS.

Returns:

The new object.

ai::FilePath::FilePath

(

const

CFURLRef

)

[explicit]

Creates an initialized file-path object from a FSRef file specification in Mac OS.

Returns:

The new object. Creates an initialized file-path object from a CFURLRef URL specification in Mac OS.

The new object.

ai::FilePath::~FilePath

(

)

Destructor.

---

Member Function Documentation

void ai::FilePath::AddComponent

(

const FilePath &

addend

)

[inline]

Adds a component to this path.

Adds or ignores appropriate delimiters as needed. Does not add delimiters to the end of a path unless explicitly requested by sending an empty addend.

Parameters:

addend

A file-path object containing the component to add to the path of this object.

Returns:

Nothing.

References AddComponent(), and GetFullPath().

void ai::FilePath::AddComponent

(

const ai::UnicodeString &

addend = ai::UnicodeString()

)

Adds a component to this path.

Adds or ignores appropriate delimiters as needed. Does not add delimiters to the end of a path unless explicitly requested by sending an empty addend.

Parameters:

addend

[in/out] A Unicode string containing the component to add, in which to return the lengthened path string.

Returns:

Nothing.

Referenced by AddComponent().

void ai::FilePath::AddExtension

(

const std::string &

ext

)

[inline]

Adds a file extension to this path.

Adds or ignores dots as needed so that only one dot appears before the extension.

Parameters:

ext

The extension text in a C string.

Returns:

Nothing

References AddExtension().

void ai::FilePath::AddExtension

(

const ai::UnicodeString &

ext

)

Adds a file extension to this path.

Adds or ignores dots as needed so that only one dot appears before the extension.

Parameters:

ext

The extension text in a Unicode string.

Returns:

Nothing

Referenced by AddExtension().

bool ai::FilePath::EndsWithDelimiter

(

)

const

Reports whether this path ends with a delimiter, and therefore references a folder or directory, rather than a file.

Returns:

True if the path ends with a delimiter

bool ai::FilePath::Equal	(	const FilePath &	filePath,
		const bool	resolveLinks = false
	)			const

Compares this file path to another for equality.

Parameters:

	filePath	The path object to compare to this one
	resolveLinks	Optional. True to resolve links, aliases, and/or shortcuts if the paths are not identical. Default is false.

Returns:

True if the paths are identical, whether or not the file exists, or if links are resolved and the two paths refer to the same file.
False if the paths are not identical and resolveLinks is false.

bool ai::FilePath::Exists	(	const bool	resolveLinks,
		ai::UnicodeString *	longPath = 0,
		bool *	isFile = 0
	)			const

Reports whether this file or directory exists after querying the file system.

Parameters:

	resolveLinks	True to resolve links, aliases, and shortcuts for the full path returned in longPath.
	longPath	[out] Optional. A buffer in which to return a full long, Unicode version of the path, if the file or directory is found. Return value undefined if function returns false. Can be NULL.
	isFile	[out] Optional. A buffer in which to return true if a file is found, false if a directory is found. Return value undefined if function returns false.Can be NULL.

Returns:

True if the file or directory exists, false otherwise.

CFStringRef ai::FilePath::GetAsCFString

(

)

const

Creates a CFString from this file path in Mac OS.

Returns:

The file specification object.

CFURLRef ai::FilePath::GetAsCFURL

(

)

const

Creates an FSRef from this file path in Mac OS.

Parameters:

result

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

Returns:

An operating-system status code. Creates a CFURL from this file path in Mac OS.

The URL specification object.

AIErr ai::FilePath::GetAsMiFile

(

MiFile *&

)

const

Internal.

Creates an MiFile based on this path (Illustrator core only).

AIErr ai::FilePath::GetAsMiFile

(

MiFile &

)

const

Internal.

Fills in the existing MiFile from this path (Illustrator core only).

void ai::FilePath::GetAsSPPlatformFileRef

(

SPPlatformFileReference &

)

const

ai::UnicodeString ai::FilePath::GetAsURL

(

const bool

displayName

)

const

Retrieves this path as a Uniform Resource Locator (URL), which contains only ASCII characters; any special characters are escaped with URL percent (%) encoding.

Parameters:

displayName

True to get the display name.

Returns:

The URL string.

AIErr ai::FilePath::GetCreatorAndType	(	ai::uint32 *	creator,
		ai::uint32 *	type
	)			const

Retrieves the creator and type of this file or directory (4-character codes) in Mac OS.

Parameters:

	creator	[out] A buffer in which to return the creator, a 4-character code.
	type	[out] A buffer in which to return the type, a 4-character code.

Returns:

An error code, kNoErr on success.

static const char ai::FilePath::GetDelimiter

(

)

[static]

Return the relative path of 'path' to 'base'.

Return the absolute path for 'relative' from 'base'. Retrieves the path component delimiter for the current platform.

Returns:

The delimiter character.

ai::UnicodeString ai::FilePath::GetDirectory

(

const bool

displayName = false

)

const

Retrieves the directory name, ending with a delimiter, without the filename, in notation native to the current platform.

If path represents a directory, the result is the same as GetFullPath().

Parameters:

displayName

True to get the display name.

Returns:

The directory path string.

ai::UnicodeString ai::FilePath::GetFileExtension

(

)

const

Retrieves the file extension, without the dot, or NULL if the file name ends with a dot.

Returns:

The extension string.

ai::UnicodeString ai::FilePath::GetFileName

(

const bool

displayName = false

)

const

Retrieves the file name including an extension, if applicable, but without the path.

Parameters:

displayName

True to get the display name.

Returns:

The file name string.

ai::UnicodeString ai::FilePath::GetFileNameNoExt

(

)

const

Retrieves the file name without the extension and path.

Returns:

The file name string.

ai::UnicodeString ai::FilePath::GetFullPath

(

const bool

displayName = false

)

const

Retrieves the full path in notation native to the current platform.

Parameters:

displayName

True to get the display name.

Returns:

The path string.

Referenced by AddComponent().

FilePath ai::FilePath::GetParent

(

)

const

Retrieves the parent of the object represented by this path.

• If this path is a directory, gets the parent directory.
• If this path is a top-level volume, gets an empty path.

Does not access the file system, and does not guarantee that the referenced file or directory exists.

Returns:

The file-path object for the parent.

ai::UnicodeString ai::FilePath::GetShortPath

(

)

const

Retrieves an operating-system-specific short version of the path.

The file or folder must exist. Accesses the file system.

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

  Returns:

  The path string.

bool ai::FilePath::IsEmpty

(

)

const

Reports whether a file-path object is empty.

Returns:

True if the object is empty.

void ai::FilePath::MakeEmpty

(

)

Sets the referenced path of this object to a NULL path.

Returns:

Nothing.

bool ai::FilePath::operator!=

(

const FilePath &

)

const

Inequality operator.

bool ai::FilePath::operator<

(

const FilePath &

)

const

Less-than operator, compares file path strings.

FilePath& ai::FilePath::operator=

(

const FilePath &

)

Assignment operator.

Same as AIFilePathSuite::Copy().

bool ai::FilePath::operator==

(

const FilePath &

)

const

Equality operator.

void ai::FilePath::RemoveComponent

(

)

Removes the end component from this path.

Returns:

Nothing.

void ai::FilePath::RemoveExtension

(

)

Removes the file extension, if any, from this path.

Returns:

Nothing

static void ai::FilePath::ResetVolumeCache

(

)

[static]

Resets cached information about volumes, used to increase the efficiency of filesystem operations.

Returns:

Nothing.

void ai::FilePath::Resolve

(

)

Resolves any alias or shortcut for this path by querying file system, and alters the object to point directly to the target file.

The target file or directory must exist. <<or what happens?>>

Returns:

Nothing

void ai::FilePath::Set	(	const ai::UnicodeString &	path,
		bool	expandName = true
	)

Sets this file path from a Unicode string containing a path native to Windows, Unix, or Mac OS, or a URL.

Parameters:

	path	Path of file.
	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).

Returns:

Nothing.

void ai::FilePath::SetFromCFString

(

const

CFStringRef

)

Sets this file path from an CFStringRef file specification in Mac OS.

Returns:

Nothing.

void ai::FilePath::SetFromCFURL

(

const

CFURLRef

)

Sets this file path from an FSRef file specification in Mac OS.

Returns:

The operating-system status code. Sets this file path from an CFURLRef URL specification in Mac OS.

Nothing.

void ai::FilePath::SetFromMiFile

(

const MiFile &

)

Internal.

Sets this file path from an MiFile. (Illustrator core only.)

Returns:

Nothing.

void ai::FilePath::SetFromSPFileRef

(

const SPPlatformFileReference &

)

bool ai::FilePath::StartsWithDelimiter

(

)

const

Reports whether this path starts with a delimiter, and is therefore an absolute, not relative, path.

Returns:

True if the path starts with a delimiter

---

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

• IAIFilePath.hpp