Introduction to the File System
Overview of File System Entities
Overview of Pathnames and Pathname Parsers
File System Exceptions
To get the full pathname from an IFileSystemEntity object, call its path function:
IPathName pathName = anEntity.path(); // get full path of entity
To get the full host-specific path name for the entity, call the hostPath function. You can pass in an optional path name parser to use in constructing the host-specific path name. For example, if you specifically want a host-specific path name in Windows format, pass in an instance of IWin32PathNameParser. If you do not explicitly specify a path name parser, you will get the parser that matches the path format of the host operating system.
IHostPathName hostPathName(anEntity.hostPath()); cout << "Path name in host path format is " << hostPathName; IHostPathName winPathName(anEntity.hostPath(IWin32PathNameParser())); cout << "Path name in Windows path format is " << winPathName;
An attribute common to all types of entities is the entity name. To get and set the name of an entity call the name and setName functions:
IFileName entityName = anEntity.name(); // get the name
anEntity.setName(IFileName("newname")); // set the name
Note: IFileName is a typedef for IText.
Another attribute common to all types of entities is the time of the most recent modification to the physical entity. You can retrieve the modification timestamp of the physical entity by calling modificationTime:
ITimeStamp modTime = anEntity.modificationTime();
You can also determine if a single file system entity object was created with either the IFile::createTemporary function or IVolume::createTemporary function. This does not check to see whether the physical object resides in any particular system temporary directory; it returns true if the entity instance was specifically created using one of those two static functions.
if (anEntity.temporary()) {
// it's a temporary entity
}
To rename an entity, call the setName function:
anEntity.setName(newName);
You can also rename an entity by moving it.
IFileSystemEntity's equality (==) and inequality operators (!=) test whether two entity objects point to the same physical object on the disk. Two objects that refer to the same physical object will compare equal, even if they were constructed from different path names:
// construct a pathname relative to current dir
IHostPathName name1("data\settings.zzz");
// construct an absolute pathname
IHostPathName name2("/program/data/settings.zzz");
// set the current directory
IDirectory::setCurrent(IDirectory("/program",
IUnixPathNameParser());
// Compare the file entities
IFile file1(name1, IFile::kMustExist, IWin32PathNameParser());
IFile file2(name2, IFile::kMustExist, IUnixPathNameParser());
if (file1 != file2) {
// major problem
}
You can test whether an entity is an instance of a particular class with the function IFileSystemEntity::isA. Pass an IFileKind representing the desired class, and isA returns true if the entity belongs to that class. Each entity class declares a constant named kKind that represents the class type.
As an example, the following code will print out the names of all of the directories that reside inside myDirectory.
for (IDirectoryIterator anEntity(myDirectory); anEntity; anEntity++) {
if (anEntity.isA(IDirectory::kKind)) {
cout << anEntity->name() << endl;
}
}
You can call a file system entity's valid function to determine if an entity instance represents a real file system object:
if (IFile(IPathName("example")).valid()) {
cout << "the file exists";
}
The valid function returns false after you call deleteSelf or any other function that deletes the physical object or invalidates the entity:
IFile aFile(IPathName("example"));
aFile.deleteSelf();
// the following statement will print "invalid"
cout << "'example' is " <<
(aFile.valid() ? "valid" : "invalid");
The valid function also returns false for entity instances created using the default constructor, because they do not refer to any physical object until assigned a good value:
IFile someFile;
// The following statement will print "invalid"
// because someFile doesn't refer to a physical object.
cout << "someFile is " <<
(someFile.valid() ? "valid" : "invalid");
someFile = IFile(IPathName("goodfile"));
// The following statement will print "valid" if the
// file 'goodfile' exists.
cout << "someFile is " <<
(someFile.valid() ? "valid" : "invalid");
However, the valid function will still return true if something else, such as another process, deletes the physical object to which the entity instance points. If your program is running in a multithreaded situation where there is a possibility that another thread or process has deleted a file, call the connected function to determine if an entity's physical file system object still exists:
if (aDirectory.connected()) {
// directory is still here
}
Note: The connected function goes out to the disk or network to verify that the entity still exists. It can be considerably slower that calling the valid function.
IVolume provides several state access functions which you can use to get information about a volume. Use the online, remote and removable functions to find out whether a volume is online or offline, whether it is remote or local, and whether or not it is a removable-media volume:
IVolume volume(IHostPathName("C:"),
IWin32PathNameParser());
IVolume::EState online = volume.online();
IVolume::EState remote = volume.remote();
IVolume::EState removable = volume.removable();
These functions return one of three values. IVolume::EState defines three values: kFalse, kTrue and kUnknown. You can use the state value returned by any of the above functions as if the state value was boolean, but the unknown status will be treated as true. This is the more conservative assumption -- if you don't know whether a volume is remote, your code will assume that it is.
Call the freeSpace function to determine the amount of space available on a particular volume:
IFileSize freeSpace = aVolume.freeSpace();
IFileSize is a class that represents a 64-bit signed integer. You can perform all the standard mathematical operations on an IFileSize object, as if it were an integer value.
You can also find out the total storage space for a particular volume by calling the totalSpace function. For example, you could calculate the percentage of total storage space used on a device:
IFileSize percentUsed =
aVolume.freeSpace() / aVolume.totalSpace();
Introduction
to the File System
Overview
of File System Entities
Overview
of Pathnames and Pathname Parsers
File System
Exceptions
Instantiating a
File System Entity from a Host-Specific Pathname
Instantiating
a File System Entity from a Portable Pathname
Instantiating
a File System Entity from Another Instance of the Same Entity
Class
Using an
Instance of IFileSystemEntity to Represent a File, Directory or
Volume
Instantiating
Host-Specific Pathnames and Pathname Parsers
Instantiating a
Portable Pathname from a Host-Specific Pathname
