Each BEntryList object has a single iterator pointer that's shared by all three GetNext…() formats (and CountEntries()). Thus, each successive call to a GetNext…() function gets the next entry, regardless of the format. For example:

BEntry entry;
entry_ref ref;

dir.GetNextEntry(&entry);
dir.GetNextRef(&ref);

Here, entry represents the first entry in the directory, and ref represents the second entry.

GetNextDirents() is different from the other two flavors in that it can retrieve more than one entry at a time. Or it will, someday; currently GetNextDirents() retrieves only one entry at a time, no matter how many you ask for.

So, which flavor of GetNext…() should you use? Here's how they compare:

• GetNextDirents() is by far the fastest (even in the current one-struct-at-a-time version), but it's also the least wieldy—the protocol isn't nearly as nice as the other two functions. The dirent structure, while jam-packed with fun facts, usually has to be turned into other structures (node_refs or entry_refs) in order to be useful.

• GetNextRef() is slower, but the entry_ref structure can be immediately usable (or, at least, cachable). Nonetheless, you're still a step away from a "real" object.

• GetNextEntry() is the slowest, but at least it hands you an object that you can sink your teeth into.

The actual timing numbers depend on your machine, the class that you're invoking the functions through, and some other factors. But the difference is (ahem) significant: GetNextDirents() is about an order of magnitude faster than GetNextEntry(), with GetNextRef() right about in the middle.

If, for example, you're simply compiling a list of leaf names, you should certainly use GetNextDirents() (painful though it may be). But if you plan on actually doing something with each and every entry that you retrieve, then bite the bullet: Use GetNextEntry().

Of the three iterator functions, GetNextDirents() needs some explanation. The dirent structure, which is what the function returns, describes aspects of the retrieved entry:

typedef struct dirent {
   dev_t d_dev;
   ino_t d_ino;
   dev_t d_pdev;
   ino_t d_pino;
   unsigned short d_reclen;
   char d_name[1];
} dirent;

The fields are:

• d_dev is a device id that identifies the device (file system) on which this entry lies.

• d_ino is the node number for this entry's node.

• d_pdev and d_pino are the device and inode numbers for the parent directory.

• d_reclen is the length of this dirent structure. The length is variable because…

• d_name is a buffer that's allocated to hold the (NULL-terminated) name of this entry.

So—let's pretend we've retrieved a dirent and we want to do something with it. In addition to looking at individual fields, we can combine some of them to make other structures:

• d_dev + d_ino = node_ref of the entry's node

• d_pdev + d_pino = node_ref of the parent directory

• d_pdev + d_pino + d_name = entry_ref for the entry

In code:

dirent* dent;
entry_ref ref;
node_ref nref;
node_ref pnref;

/* Allocate and fill the dirent here... */
...

/* Make a node_ref to this entry's node. */
nref.device = dirent->d_dev;
nref.node = dirent->d_ino;

/* Make a node_ref to this entry's parent. */
pnref.device = dirent->d_pdev;
pnref.node = dirent->d_pino;

/* Make an entry_ref to this entry. */
ref.device = dirent->d_pdev;
ref.directory = dirent->d_pino;
ref.set_name(dirent->d_name);

Where you go from here is a simple matter of programming. Me? I'm going to lunch.

Getting a dirent

Now that we know what to do with a dirent, let's see how to get one. The GetNextDirents() protocol looks like this:

int32 GetNextDirents(dirent* buf,
                     size_t bufsize,
                     int32 count = INT_MAX);

By default, the function stuffs as many dirent structs as it can into the first bufsize bytes of buf. These structures represent the next N entries in the entry list. The count argument lets you set a limit to the number of structures that you want to be retrieved at a time. The function returns the number of structures that it actually got.

Warning

Keep in mind that currently GetNextDirents() can only read one dirent at a time, regardless of the size of buf, or the value of count.

Let's try it. For the purposes of this example, we'll convert each dirent into an entry_ref, as described in the previous section.

/* This is the buffer that we'll stuff structures into. */
char buf[4096];
dirent* dent;
entry_ref ref;

/* We'll assume dir is a valid BDirectory object. */
while ((count = dir.GetNextDirents((dirent*)buf, 4096)) > 0) {
   dent = (dirent*)buf;

   /* Now we step through the dirents. */
   while (count-- > 0) {
      ref.device = dent->d_pdev;
      ref.directory = dent->d_pino;
      ref.set_name(dent->d_name);

      /* Do something with the ref. */
      ...

      /* Bump the pointer. */
      dent = (dirent*)((char*)dent + dent->d_reclen);
   }
}

Remember, the structure is variable length—you have to increment the pointer by hand, as shown here.