Entries And Nodes

The most important concept that you should keep in mind when you're using the Storage Kit is that a file is considered both an entry and a node:

This concept really isn't new: If you're familiar with POSIX, then you've already dealt with entries and nodes, except you called them pathnames and file descriptors.


In the Storage Kit, entries are represented three ways:

Any entry can be given by any of these representations. Furthermore, the representations are fairly easily converted: Given an entry_ref, it's trivial to get a BEntry, from which you can easily get a pathname, which can be turned into an entry_ref. Which representation you use depends on what you're doing:


An entry_ref or BEntry isn't necessarily valid across reboots; don't archive these and expect them to work when the system is restarted. Instead, you should save pathnames (either complete or partial, depending on your specific needs; when possible, you should use the directory constants used by the find_directory() function).


Nodes are represented in two ways:

Here, again, the representations are easily converted. As for use…

Every node has a type, or flavor. There are three node flavors:

These flavors are represented by subclasses of BNode: BFile, BDirectory, and BSymLink. Note that a node_ref doesn't know its node's flavor.

More Facts

Some more facts you should be aware of:


Here are some more facts, slight alterations to the near truths spoken above:

A Node can Lose its Entry

Consider this scenario: You create a BFile object to some file. While you're reading and writing the file, the user deletes the file through the Tracker or from a Terminal. What the user has done is delete the node's entry, not the node itself. The node isn't destroyed until all references to the node, including your BFile, are deleted (or, more accurately, "closed"). The twist is that your BFile by itself has no way of knowing that the entry is gone.

So what are you supposed to do? In general, whenever you free a BFile object, you should first check to make sure the entry still exists; of course, the BFile itself can't tell you (remember: A node doesn't know about its entry), so you have to save the entry that was used to create the BFile. You ask the entry if it still exists, and then do whatever you have to do if it doesn't, such as alert the user, ask for a new entry name, and so on.

Unfortunately, this problem has another wrinkle: What if the user moves the entry while you're using the entry's node? In this case, the node isn't going to be destroyed, but if you ask the generative entry (the entry that was used to create the BFile object), it looks like the entry is gone.

There's no generic solution to the entire problem. Not because it's impossible to implement, but because the "right" solution depends on what the user meant by deleting or moving the entry. Most applications take this approach: The user knows files as entries, not as nodes. If a user opens a file through your app, moves the entry (through some other vehicle, such as the Tracker), and then asks your app to save the file, what the user really want is for you to save the node under the same name that was used to open the node.

A BDirectory Knows its Entry

BDirectory is an exception to the "ignorant node" rule: You can ask a BDirectory object for its entry (through its GetEntry() function).

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.