Main Page | Modules | Namespace List | Class Hierarchy | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

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)

File operation

bool RecursiveDeleteDirectory (const CP_String &inDirectory)

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.

Variables

CPLAT_Begin_Namespace_CPLAT
const OSVolume 
kOnSystemDisk = "c"

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

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

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.

bool RecursiveDeleteDirectory const CP_String inDirectory  ) 
 


Variable Documentation

const OSVolume kOnSystemDisk = "c"
 


Generated on Sat Sep 17 20:01:14 2005 for CPLAT by  doxygen 1.4.0