• You can use your BPath to initialize other, more powerful objects (BEntry, BNode and its kids). See "Converting a BPath".

• BPaths can be passed through BMessages. To add a BPath to a BMessage, you have to flatten it first: BPath implements BFlattenable for exactly this reason. The receiver of the BMessage can resurrect the flattened object as a BPath object or as an entry_ref structure. See "Passing a BPath in a BMessage".

• BPath objects are ideal for caching references to files. BPaths don't consume much in the way of system resources—they don't contain file descriptors, for example. So they're great for keeping track of the files that your application is interested in.

In the way that they're used, BPaths and entry_refs are nearly identical. In particular, entry_refs can do all three of the things listed here. Whether you use BPaths (pathnames in general) or entry_refs is largely a matter of taste.

You initialize a BPath—in other words, you establish the path that the object represents—by passing a string (or two, or a BDirectory and a string) to the constructor or to the SetTo() function. Upon initialization, the BPath object concatenates the strings and then "normalizes" the passed-in strings if it has to (this emphasis is important, as we'll see in a moment). The following elements trigger normalization:

• a relative pathname (after concatenation; e.g. boot/lbj)

• the presence of "." or ".." (/boot/lbj/../lbj/./fido)

• redundant slashes (/boot//lbj)

• a trailing slash (/boot/lbj/)

During normalization, BPath conjures up an absolute pathname in the form

• /dir1/dir2/.../dirN/leaf

It does this by applying the following rules:

• relative pathnames are reckoned off of the current working directory

• "." is ignored (at the head of a path, it's taken as the cwd).

• ".." bumps up one directory level

• redundant slashes are coalesced

• a trailing slash is removed.

(The one exception to this final rule is / as a full pathname.)

There's a subtle side-effect that you get with normalization: When you normalize a pathname, all the elements in the path up to but not including the leaf must exist. In other words, a normalized BPath object gives you the same guarantee of existence as does an entry_ref structure. The subtlety, here, is that an unnormalized BPath needn't exist at all.

For example, here we create a BPath for a pathname that contains a non-existent directory:

/* We'll assume that "/abc/def/" doesn't exist. */
BPath path("/abc/def/ghi.jkl");

/* Nonetheless, the BPath is successfully initialized.
* The Path() function returns a pointer to the object's
* pathname string.
*/
printf("Path: %sn". path.Path());

On the command line we see:

$ Path: /abc/def/ghi.jkl

But if we tickle the normalization machine…

/* The redundant slash causes a normalization. */
BPath path("/abc/def//ghi.jkl");

…the object is invalid:

$ Path: (null)

/* The trailing bool forces normalization. */
BPath path("/abc/def/ghi.jkl", true);
printf("Path: %sn", path.Path());

$Path: (null)

BPath objects are passed back to you (by reference) by a number of Storage Kit functions. However, you shouldn't find any functions that ask for a BPath object. This is a convention of usage:

• If an API element returns a pathname to you, it does so in the form of a BPath. If it asks for a pathname from you (as an argument), it asks for a const char*.

As an example of a function that returns a BPath to you, recall BEntry's GetPath() function:

status_t BEntry::GetPath(BPath *path)

(As an aside, this is where the auto-allocation comes in handy—because BPath allocates the pathname storage for you, you don't have to mess around with ugly buffer and length arguments.)

On the other hand, BEntry's SetTo() takes a pathname as a const char*:

status_t BEntry::SetTo(const char *path)

If you've got a BPath loaded up with a pathname, you would call this function thus:

entry.SetTo(path.Path());

The constructors and SetTo() functions in (most of) the Storage Kit classes have const char* versions that can be called as shown here.

Let's say you've got a BPath object that you want to send to some other application. To do this, you have to add it to a BMessage object through the latter's AddFlat() function. As an inheritor from BFlattenable the BPath knows how to flatten itself for just this purpose.

BMessage msg;
BPath path("/boot/lbj/fido");

/* The check here is important, as we'll describe
* in a moment.
*/
if (msg.AddFlat("pathname", &path) != B_OK)
   /* handle the error */

The receiver of the message can retrieve the pathname as a BPath object by calling FindFlat():

void MyApp::MessageReceived(BMessage *msg)
{
   BPath path;

   if (msg->FindFlat("pathname", &path) != B_OK)
      /* handle the error */
   ...
}

Alternatively, the pathname can be retrieved as an entry_ref through FindRef():

void MyApp::MessageReceived(BMessage *msg)
{
   entry_ref ref;

   if (msg->FindRef("pathname", &ref) != B_OK)
      /* handle the error */
   ...
}

If you want to skip all the conversion business and simply pass the pathname as a string, use AddString(). The receiver, of course, would have to call FindString() to retrieve your pathname string.

As mentioned earlier, most of the Storage Kit classes have constructors and SetTo() functions that accept const char* arguments. If you want to turn your BPath into a BFile (for example), you would do this (including error checks):

status_t err;

BFile file(path.Path());
err = InitCheck();

or

err = file.SetTo(path.Path());

To convert a BPath to an entry_ref, pass the pathname to the get_ref_for_path() function:

entry_ref ref;
status_t err;

err = get_ref_for_path(path.Path(), &ref);

For you Node Monitor users: You can't convert directly to a node_ref structure. The quickest way from here to there is:

node_ref nref;
status_t err;

/* We'll skip InitCheck() and catch errors in GetNodeRef(). */
BEntry entry(path.Path());
err = entry.GetNodeRef(&nref);

Remember, a BPath represents a pathname, not a node. It isn't "updated" when the file system changes:

• A BPath's pathname string never changes behind your back, even if the entry that it originally pointed to is renamed, moved, or deleted.

For example:

BEntry entry;
BPath path;

/* Set a BPath, construct a BEntry from it, rename
* the entry, and then print the BPath's pathname.
*/
if (path.SetTo("/boot/lbj/fido") == B_OK)
   if (entry.SetTo(&path) == B_OK)
      if (entry.Rename("rover") == B_OK)
         printf("Pathname: %sn", path.Path());

We see…

$ Pathname: /boot/lbj/fido

...even though the entry that the BPath was constructed to represent has been renamed.