OS SERVICES - Using TPathName

Using TPathName

Using TPathName, you can obtain a file system entity by providing the pathname of the entity you want, or get the pathname of an entity by providing the file system entity itself.

NOTE The preferred method for your code to obtain an entity is to be handed an entity from an external source, such as the workspace. This section describes how to use TPathName to obtain entities on your own, though this is not the optimal method.

Obtaining a file system entity from a pathname

You can obtain file system entities with TPathName using either absolute or relative paths. When you construct a TPathName with an absolute path, you pass in a pathname and a parser. When you use a relative path, you construct a TPathName using a TDirectory instance, a pathname, and a parser.

The CommonPoint application system does not have a "current" or "working" directory; to use a relative pathname, you must convert it to an absolute pathname, using either TDirectory or TPathName. Relative pathnames can be combined to specify an absolute pathname.

The parser is an instance of a class derived from TPathNameParser. This class defines how to parse a system-dependent pathname. TPathName includes a member function called GetDefaultParser--this function retrieves the parser appropriate to the current system environment. If you do not pass a parser into the TPathName constructor, it retrieves the default parser for you.

NOTE TUnixPathNameParser is the only concrete parser provided in this software release.

This example passes a relative path into TPathName (using the default parser) and retrieves a TFile instance using the GetEntity member function. The myDirectory instance passed into TPathName represents an instance of TDirectory.

  THostSpecificPathName myPath = "utilities/wonderprogram/mydocument";
  TPathName thePath(myDirectory, myPath);
  TFile myFile = thePath.GetEntity();

Obtaining a pathname from a file system entity

To find the pathname for a specific entity, you construct a TPathName instance, passing in the entity.

This one-line example provides the myFile entity to TPathName and retrieves the corresponding pathname directly from the constructor.

TPathName thePath(myFile);

When you construct a TPathName by passing an absolute pathname as a parameter, the TPathName::GetEntity method returns a TFileSystemEntity instance. This means that you can retrieve entities polymorphically based on the pathname you provide. If the TPathName does not contain an absolute pathname or if the pathname does not refer to an existing entity on disk, GetEntity throws an exception.

This short example gets the entity for a path and assumes that the entity is a TFile instance. You can downcast the return value to a TFile by using the `downcast' constructor:

TFile aFile (myPath.GetEntity());

You can also downcast the return value by using the assignment operator:

TFile aFile = myPath.GetEntity();

In either case, an exception is thrown if the file system entity is not a TFile instance.

[Contents] [Previous] [Next]

Click the icon to mail questions or corrections about this material to Taligent personnel.

Generated with WebMaker