|
Rewind() applies to BDirectories only. You can't rewind a BQuery's entry list.
|
| The Storage Kit Table of Contents | The Storage Kit Index |
Derived from: none
Declared in: be/storage/EntryList.h
Library: none
BEntryList is a pure abstract class that defines the protocol for iterating over a set of file system entries. Each derived class must figure out how to create (or "discover") the entry list in the first place: BEntryList only supplies functions for getting entries out of the list, it doesn't let you put them in. The BEntryList class has two derived classes: BDirectory and BQuery.
At the heart of the BEntryList class are the three GetNext...() functions, which let you retrieve the entries as...
You call these functions iteratively; each call gets the "next" entry (or set of entries in the case of GetNextDirents()). You check the GetNext...() return value to detect the end of the list:
To get back to the top of an entry list, you call Rewind(), but note...
|
Here's an example of an iteration over all the entries in a BDirectory, retrieved as BEntry objects:
BDirectory dir("/boot/home/fido");
BEntry entry;
dir.Rewind();
while (dir.GetNextEntry(&entry) == B_OK)
/* do something with entry here. */
The final BEntryList function, CountEntries(), also only applies to BDirectories; but even there you shouldn't depend on it. The count is stale as soon as CountEntries() returns. The user could create a new file or delete a file in the directory while you're iterating over the entries. Also, CountEntries() shares the entry list pointer with the GetNext...() functions. You mustn't intermingle a CountEntries() call within your GetNext...() loop.
One more BDirectory wrinkle:
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:
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:
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:
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.
Now that we know what to do with a dirent, let's see how to get one. The GetNextDirents() protocol looks like this:
|
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.
|
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.
|
Returns the number of entries that are in the entry list.
|
|
These functions return the "next" entry in the entry list as a BEntry, entry_ref, or dirent structure. The end of the list is signalled by...
If the traverse argument is true , symlinks are traversed.
See the introduction for more information.
|
Rewinds the entry list pointer so it points to the first element in the list.
|
| The Storage Kit Table of Contents | The Storage Kit Index |
Copyright © 2000 Be, Inc. All rights reserved..