CP_FileSystem.h File Reference

Namespaces
namespace	CP_FileSystem
Files and Folders
void	DeleteObject (const CP_FileSystemSpec &inOutFileSpec, bool inNotifyFinder=true)
bool	SetLocked (const CP_FileSystemSpec &inFileSpec, bool inLockit)
bool	SetReadOnly (const CP_FileSystemSpec &inFileSpec, bool inReadOnly)
Files
void	DeleteFile (const CP_FileSystemSpec &inOutFileSpec, bool inNotifyFinder=true)
void	RenameFile (const CP_FileSystemSpec &inFileSpec, const CP_String &inNewName, CP_FileSystemSpec *outRenamedFileSpec, bool inNotifyFinder=true)
void	RenameFile (CP_FileSystemSpec &inOutFileSpec, const CP_String &inNewName, bool inNotifyFinder=true)
CP_String	GetExtension (const CP_FileSystemSpec &inFileSpec)
CP_FileSystemSpec	SetExtension (const CP_FileSystemSpec &inFileSpec, const CP_String &inFileExtension)
bool	HasExtension (const CP_FileSystemSpec &inFileSpec, const CP_String &inFileExtension)
SInt64	GetSize (const CP_FileSystemSpec &inFileSpec)
FourCharCode	GetType (const CP_FileSystemSpec &inFileSpec)
void	GetTypeAndCreator (const CP_FileSystemSpec &inFileSpec, FourCharCode *outType, FourCharCode *outCreator)
CP_Date	GetCreatedDate (const CP_FileSystemSpec &inFileSpec)
CP_Time	GetCreatedTime (const CP_FileSystemSpec &inFileSpec)
CP_Date	GetModifiedDate (const CP_FileSystemSpec &inFileSpec)
CP_Time	GetModifiedTime (const CP_FileSystemSpec &inFileSpec)
CP_OSIcon	GetLargeIcon (const CP_FileSystemSpec &inFileSpec)
CP_OSIcon	GetSmallIcon (const CP_FileSystemSpec &inFileSpec)
CP_FileSystemSpec	CreateTempFile (const CP_String &inFileNameTemplate=CP_String::emptyString, const CP_FileSystemSpec *inParentFolder=NULL)
	Creates a unique temporary file.
Folders
CP_FileSystemSpec	CreateFolder (const CP_FileSystemSpec &inParentFolderSpec, const CP_String inFolderName, bool inNotifyFinder=true)
CP_FileSystemSpec	CreateFolder (const CP_FileSystemSpec &inFolderSpec, bool inNotifyFinder=true)
void	RemoveFolder (const CP_FileSystemSpec &inOutFileSpec, bool inNotifyFinder=true)
bool	FolderExists (const CP_FileSystemSpec &inFolderSpec)
CP_FileSystemSpec	GetFolder (FourCharCode inFolderType, const OSVolume &inVolume=kOnSystemDisk)
CP_FileSystemSpec	GetTempFolder (const OSVolume &inVolume=kOnSystemDisk)
CP_FileSystemSpec	GetTempFileSpec (const CP_String &inFileName, const CP_String &inFileExtension)
CP_FileSystemSpec	CreateTempFolder (const CP_String &inFolderNameTemplate=CP_String::emptyString)
	Creates a unique temporary file.
Volumes
bool	VolumeExists (const CP_String &inVolumeName)
Testers
bool	IsWriteable (const CP_FileSystemSpec &inFileSpec)
bool	ExistsOnDisk (const CP_FileSystemSpec &inFileSpec)
Testers
bool	HasResourceFork (const CP_FileSystemSpec &inFileSpec)
Creator and Type
FourCharCode	GetCreator (const CP_FileSystemSpec &inFileSpec)
void	SetCreatorAndType (const CP_FileSystemSpec &inFileSpec, FourCharCode inCreator, FourCharCode inType)
void	SetCreator (const CP_FileSystemSpec &inFileSpec, FourCharCode inCreator)
void	SetType (const CP_FileSystemSpec &inFileSpec, FourCharCode inType)
File Info
CP_OSIcon	GetOSLargeIcon (const CP_FileSystemSpec &inFileSpec)
CP_OSIcon	GetOSSmallIcon (const CP_FileSystemSpec &inFileSpec)
CP_OSIcon	GetIconServicesIcon (const CP_FileSystemSpec &inFileSpec)
Functions
OSStatus	FSMakeFSRefUnicodeLinkSafe (const FSRef *parentRef, UniCharCount nameLength, const UniChar *name, TextEncoding textEncodingHint, FSRef *newRef) throw ()
	Make an FSRef and be smart about parentRef pointing to symlink.
OSStatus	FollowSymlink (const FSRef &inFileRef, FSRef *outResolvedFileRef, bool *outWasSymlink=NULL, bool *outIsFolder=NULL) throw ()
	Resolve a potential symlink.

---

Function Documentation

void DeleteObject (  const CP_FileSystemSpec &  inOutFileSpec, bool  inNotifyFinder )

Deletes the platforms file system file or folder with the passed in file spec. This throw an OSError exception on any errors, such as the file not existing in the platforms file system. Before calling this routine you need to make sure that the file is not currently in use or open, as this will cause an error to be thrown. This will also reset the contents of the passed in inFileSpec to reflect the fact that the file no longer exists in the file system. Parameters: [in,out]  inFileSpec  The CP_FileSystemSpec of the file/folder to be deleted. On the Mac, upon exit the file spec is updated to reflect the fact that the file no longer exists in the file system. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: exception  will be raised if the file does not exist or can't be removed. Returns: void

bool SetLocked (  const CP_FileSystemSpec &  inFileSpec, bool  inLockit )

Locks or unlocks a file or folder.* Parameters: inFileSpec  The CP_FileSystemSpec of the file to be locked/unlocked. inLockit  if true the file will be unlocked. Exceptions: exception  will be raised if the file does not exist or can't be locked. Returns: bool the state of the lock before the inLockit was carried out

bool SetReadOnly (  const CP_FileSystemSpec &  inFileSpec, bool  inReadOnly )

Set the file read only or not. Parameters: inFileSpec  The CP_FileSystemSpec of the file to be readonly/readwrite inReadOnly  if true the file will readonly. Exceptions: exception  will be raised if the file does not exist or can't change the attributes Returns: bool the state of the readonly state before change it

void DeleteFile (  const CP_FileSystemSpec &  inOutFileSpec, bool  inNotifyFinder )

Deletes the platforms file system file with the passed in file spec. This throw an OSError exception on any errors, such as the file not existing in the platforms file system. Before calling this routine you need to make sure that the file is not currently in use or open, as this will cause an error to be thrown. This will also reset the contents of the passed in inFileSpec to reflect the fact that the file no longer exists in the file system. Parameters: [in,out]  inFileSpec  The CP_FileSystemSpec of the file to be deleted. On the Mac, upon exit the file spec is updated to reflect the fact that the file no longer exists in the file system. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: exception  will be raised if the file does not exist or can't be removed. Returns: void

void RenameFile (  const CP_FileSystemSpec &  inFileSpec, const CP_String &  inNewName, CP_FileSystemSpec *  outRenamedFileSpec, bool  inNotifyFinder )

Changes the name for the file system object specified by the passed in file spec. Parameters: inFileSpec  The CP_FileSystemSpec of the file to be set. inNewName  A string containing the new name (incl. extension, if any) to be set for the file. [out]  outRenamedFileSpec  A pointer to a CP_FileSystemSpec object to contain the specifier for the renamed file on exit, or NULL if you're not interested. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: exception  will be raised if the file does not exist or can't be renamed.

void RenameFile (  CP_FileSystemSpec &  inOutFileSpec, const CP_String &  inNewName, bool  inNotifyFinder )

Changes the name for the file system object specified by the passed in file spec. The file system specifier will be updated to reflect the new name after the object has been renamed on disk. Parameters: inOutFileSpec  The CP_FileSystemSpec of the file to be set. Will be updated to reflect new name on exit. inNewName  A string containing the new name (incl. extension, if any) to be set for the file. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: exception  will be raised if the file does not exist or can't be renamed.

CP_String GetExtension (  const CP_FileSystemSpec &  inFileSpec  )

Returns the extension for the passed in file. Parameters: inFileSpec  The CP_FileSystemSpec of the file to return the extension for. Exceptions: none  Returns: void

CP_FileSystemSpec SetExtension (  const CP_FileSystemSpec &  inFileSpec, const CP_String &  inFileExtension )

Sets the extension for the passed in file spec. This will first check to see if the file has the existing extension, and if so not set it. Parameters: inFileSpec  The CP_FileSystemSpec of the file to be set. inFileExtension  A string containing the extension to be set for the file. Exceptions: none  Returns: void

bool HasExtension (  const CP_FileSystemSpec &  inFileSpec, const CP_String &  inFileExtension )

Tests the passed in file spec to see if the file it points to has the passed in file extension. Parameters: inFileSpec  The CP_FileSystemSpec of the file to be checked. inFileExtension  A string containing the extension to check for. Exceptions: none  Returns: bool True if the file has the passed in inFileExtension.

SInt64 GetSize (  const CP_FileSystemSpec &  inFileSpec  )

Returns the size of the file system object represented by the passed in CP_FileSystemSpec. Parameters: inFileSpec  The CP_FileSystemSpec of the file to return the size for. Exceptions: OSError  exceptions Returns: SInt64 The size of the file.

FourCharCode GetType (  const CP_FileSystemSpec &  inFileSpec  )

Returns the type code specified by the passed in file spec. For non MacOS builds, this will be the same as the files extension, up to 4 characters. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions. Returns: FourCharCode The type of file.

void GetTypeAndCreator (  const CP_FileSystemSpec &  inFileSpec, FourCharCode *  outType, FourCharCode *  outCreator )

Returns the type and creator code specified by the passed in file spec. For non MacOS builds the type will be the same as the files extension, up to 4 characters. For non MacOS builds the creator will be kCP_Unknown_FileType Parameters: inFileSpec  The file spec of the file. outType  The type of the file, can be NULL. outCreator  The creator of the file, can be NULL. Exceptions: OSError  exceptions. Returns: void

CP_Date GetCreatedDate (  const CP_FileSystemSpec &  inFileSpec  )

Returns the date the file represented by the passed in CP_FileSystemSpec was created. The result is returned as a CP_Date object. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions. Returns: CP_Date The created date for the file.

CP_Time GetCreatedTime (  const CP_FileSystemSpec &  inFileSpec  )

Returns the time the file represented by the passed in CP_FileSystemSpec was created. The result is returned as a CP_Time object. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions. Returns: CP_Time The created time for the file.

CP_Date GetModifiedDate (  const CP_FileSystemSpec &  inFileSpec  )

Returns the last date the file represented by the passed in CP_FileSystemSpec was modified. The result is returned as a CP_Date object. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions. Returns: CP_Date The modified date for the file.

CP_Time GetModifiedTime (  const CP_FileSystemSpec &  inFileSpec  )

Returns the last time the file represented by the passed in CP_FileSystemSpec was modified. The result is returned as a CP_Time object. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions. Returns: CP_Time The modified time for the file.

CP_OSIcon GetLargeIcon (  const CP_FileSystemSpec &  inFileSpec  )

Returns a CP_OSIcon object that represents the large icons used by the OS for the file represented by the passed in CP_FileSystemSpec. Parameters: inFileSpec  The file spec of the file. Exceptions: none  Returns: CP_OSIcon The icon for the file.

CP_OSIcon GetSmallIcon (  const CP_FileSystemSpec &  inFileSpec  )

Returns a CP_OSIcon object that represents the small icons used by the OS for the file represented by the passed in CP_FileSystemSpec. Parameters: inFileSpec  The file spec of the file. Exceptions: none  Returns: CP_OSIcon The icon for the file.

CP_FileSystemSpec CreateTempFile (  const CP_String &  inFileNameTemplate, const CP_FileSystemSpec *  inParentFolder )

Creates a unique temporary file on disk. The file is located in a temporary directory and has a unique name, which is guaranteed to not exist. The filename is characterized by the filename template passed: any trailing 'X' in the filename (excl. the extension) will be replaced with unique alphanumeric digits. The more 'X's in the filename, the larger the space of potential unique names. Parameters: inFileNameTemplate  Template for file name: the file name may be any file name with some number of 'X's appended to it (before the filename extension, if any). The trailing 'X's in the name will be replaced with a unique alphanumeric combination. You may pass an empty string to have some generic name being generated. inParentFolder  The parent folder where the file is to be created, or NULL to use the standard temporary items folder. Exceptions: OSErr  exception may be raised if file can't be created or no unique name could be found. Returns: CP_FileSystemSpec A file system specifier that points to the newly created temporary file. Todo: to be implemented

CP_FileSystemSpec CreateFolder (  const CP_FileSystemSpec &  inParentFolderSpec, const CP_String  inFolderName, bool  inNotifyFinder )

Creates a folder in the passed in parent directory with the name as specified in inFolderName. If the folder already exists, then the CP_FileSystemSpec returned points to the existing folder. Otherwise the returned CP_FileSystemSpec will point to the newly created folder. Parameters: inParentFolderSpec  A CP_FileSystemSpec representing the parent folder. inFolderName  The name of the folder or directory being created. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: OSError  exceptions Returns: CP_FileSystemSpec A CP_FileSystemSpec that points to the created folder, or the existing folder is it already exists.

CP_FileSystemSpec CreateFolder (  const CP_FileSystemSpec &  inFolderSpec, bool  inNotifyFinder )

Creates a folder at the location specified by inFolderSpec. If the folder already exists, then the CP_FileSystemSpec returned points to the existing folder. Otherwise the returned CP_FileSystemSpec will point to the newly created folder. Parameters: inFolderSpec  A CP_FileSystemSpec representing the folder. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: OSError  exceptions Returns: CP_FileSystemSpec A CP_FileSystemSpec that points to the created folder, or the existing folder is it already exists.

void RemoveFolder (  const CP_FileSystemSpec &  inOutFileSpec, bool  inNotifyFinder )

Removes the folder or directory represented by the passed in CP_FileSystemSpec. Returns CP_noErr if successful. Parameters: inOutFileSpec  The file spec of the folder. inNotifyFinder  Only used on the Mac. If true the parent folder will be notified that a change happened. Exceptions: OSError  exceptions

bool FolderExists (  const CP_FileSystemSpec &  inFolder  )

Returns true if the folder or directory represented by the passed in CP_FileSystemSpec object exists in the current file system. Parameters: inFileSpec  The file spec of the folder. Exceptions: OSError  exceptions Returns: bool True if the folder or directory exists.

CP_FileSystemSpec GetFolder (  FourCharCode  inFolderType, const OSVolume &  inVolume )

Returns a CP_FileSystemSpec object to a specific platforms folder. If the platform doesn't have the named folder, then the applications folder is returned. Parameters: inFolderType  The type of folder to return. inVolume  The volume / drive to find the folder on. Exceptions: OSStatus  exceptions. Returns: CP_FileSystemSpec CP_FileSystemSpec to the newely specified file.

CP_FileSystemSpec GetTempFolder (  const OSVolume &  inVolume  )

Returns a CP_FileSystemSpec object to a platforms temporary folder. If the platform doesn't have a temporary folder, then the applications folder is returned. Parameters: inVolume  The volume / drive to find the folder on. Exceptions: none  Returns: CP_FileSystemSpec CP_FileSystemSpec to the newely specified file.

CP_FileSystemSpec GetTempFileSpec (  const CP_String &  inFileName, const CP_String &  inFileExtension )

Returns a CP_FileSystemSpec object to a temporary file location in the platforms temporary folder. If the platform does not have a native temporary folder, then the file is created in the same folder as the application. Parameters: inFileName  Base file name for the temporary file. inFileExtension  Extension to be used to name the file. Exceptions: none  Returns: CP_FileSystemSpec CP_FileSystemSpec to the newely specified file.

CP_FileSystemSpec CreateTempFolder (  const CP_String &  inFolderNameTemplate  )

Creates a unique temporary folder on disk. The folder is located in a temporary directory and has a unique name, which is guaranteed to not exist. The foldername is characterized by the foldername template passed: any trailing 'X' in the foldername will be replaced with unique alphanumeric digits. The more 'X's in the foldername template, the larger the space of potential unique names. Exceptions: OSErr  exception may be raised if folder can't be created or no unique name could be found. Parameters: inFileNameTemplate  Template for folder name: the folder name may be any folder name with some number of 'X's appended to it. The trailing 'X's in the name will be replaced with a unique alphanumeric combination. You may pass an empty string to have some generic name being generated. Returns: CP_FileSystemSpec A file system specifier that points to the newly created temporary folder. Todo: to be implemented

bool VolumeExists (  const CP_String &  inVolumeName  )

Returns true if the volume specified by the passed in name exists in the platforms native file system. Parameters: inVolumeName  The volume to look for. Exceptions: none  Returns: bool True if the volume exists in the platforms file system.

bool IsWriteable (  const CP_FileSystemSpec &  inFileSpec  )

Returns true if the file specified by the passed in file spec is able to be written to. Parameters: inFileSpec  The file spec of the file to be checked. Exceptions: none  Returns: bool True if the file can be written to.

bool ExistsOnDisk (  const CP_FileSystemSpec &  inFileSpec  )

Returns true if the object specified by the passed in file spec exists in the platforms native file system and it is a file. Parameters: inFileSpec  The file spec of the file to be checked. Exceptions: none  Returns: bool True if the file exists in the platforms file system, false if no such object exists, or the object is not a file.

bool HasResourceFork (  const CP_FileSystemSpec &  inFileSpec  )

Returns true if the file specified by the passed in file spec has a resource fork. Parameters: inFileSpec  The file spec of the file to be checked. Exceptions: none  Returns: bool True if the file exists in the platforms file system.

FourCharCode GetCreator (  const CP_FileSystemSpec &  inFileSpec  )

Returns the creator code for the file system object represented by the passed in CP_FileSystemSpec. This can be either a file or folder. Parameters: inFileSpec  The file spec of the file or folder. Exceptions: OSError  exceptions Returns: FourCharCode The resulting creator code of the file system object.

void SetCreatorAndType (  const CP_FileSystemSpec &  inFileSpec, FourCharCode  inCreator, FourCharCode  inType )

Sets the files creator and type codes specified by the passed in file spec. Parameters: inFileSpec  The file spec of the file to be changed. inCreator  Creator code to set the file to. inType  File type to set the file to. Exceptions: none  Returns: void

void SetCreator (  const CP_FileSystemSpec &  inFileSpec, FourCharCode  inCreator )

Set the files creator code specified by the passed in file spec. Parameters: inFileSpec  The file spec of the file to be changed. inType  File type to set the file to. Exceptions: none  Returns: void

void SetType (  const CP_FileSystemSpec &  inFileSpec, FourCharCode  inType )

Sets the files type code specified by the passed in file spec. Parameters: inFileSpec  The file spec of the file to be changed. inType  File type to set the file to. Exceptions: none  Returns: void

OSStatus FSMakeFSRefUnicodeLinkSafe (  const FSRef *  parentRef, UniCharCount  nameLength, const UniChar *  name, TextEncoding  textEncodingHint, FSRef *  newRef )  throw ()

Same as FSMakeFSRefUnicode, except when parentRef points to a symlink, the function won't fail with errFSNotAFolder, but will resolve the parent link instead. Exceptions: none  Parameters: parentRef  Parent folder ref nameLength  character length of Unicode node name name  pointer to node name Unicode characters textEncodingHint  A suggested text encoding to use for the name newRef  pointer to FSRef, will contain FSRef to specified object on exit Returns: OSStatus result of FSMakeFSRefUnicode after resolving parent links

OSStatus FollowSymlink (  const FSRef &  inFileRef, FSRef *  outResolvedFileRef, bool *  outWasSymlink, bool *  outIsFolder )  throw ()

(comprehensive description) Exceptions: none  Parameters: inFileRef  The file to resolve. outResolvedFileRef  Will point to resolved object on exit. outWasSymlink  If not NULL, will contain flag on exit whether input file pointed to symlink. outIsFolder  If not NULL, will contain flag on exit whether resolved object is a folder. Returns: CP_noErr if file was symlink and pointed to one of the specified object types. fnfErr if file could not be verified (e.g. stat failed on file) or if file is not a symlink other error might be returned by filemanager

CP_OSIcon GetOSLargeIcon (  const CP_FileSystemSpec &  inFileSpec  )

Returns a CP_OSIcon object that represents the large icons used by the OS for the file represented by the passed in CP_FileSystemSpec. This is the version used by the MacOS to retrieve the icon. Parameters: inFileSpec  The file spec of the file. Exceptions: none  Returns: CP_OSIcon The icon for the file.

CP_OSIcon GetOSSmallIcon (  const CP_FileSystemSpec &  inFileSpec  )

Returns a CP_OSIcon object that represents the small icons used by the OS for the file represented by the passed in CP_FileSystemSpec. This is the version used by the MacOS to retrieve the icon. Parameters: inFileSpec  The file spec of the file. Exceptions: none  Returns: CP_OSIcon The icon for the file.

CP_OSIcon GetIconServicesIcon (  const CP_FileSystemSpec &  inFileSpec  )

Common routine used by the MacOS version of GetOSLargeIcon and GetOSSmallIcon to return a CP_OSIcon object for the represented file using the MacOS Icon Services. Parameters: inFileSpec  The file spec of the file. Exceptions: OSError  exceptions Returns: CP_OSIcon The icon for the file.

---