1/* 2 * Copyright 2011, Haiku, Inc. All Rights Reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Erik Jaesler, ejakowatz@users.sourceforge.net 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * /trunk/headers/os/storage/EntryList.h rev 42794 11 * /trunk/src/kits/storage/EntryList.cpp rev 42794 12 */ 13 14 15/*! 16 \file EntryList.h 17 \brief Defines the BEntryList class. 18*/ 19 20 21/*! 22 \class BEntryList 23 \ingroup storage 24 \ingroup libbe 25 \brief Interface for iterating through a list of filesystem entries. 26 27 Defines a general interface for iterating through a list of entries 28 i.e. files in a folder. 29*/ 30 31 32/*! 33 \fn BEntryList::BEntryList() 34 \brief Creates a BEntryList object. 35 36 Does nothing at this time. 37*/ 38 39 40/*! 41 \fn BEntryList::~BEntryList() 42 \brief Frees all resources associated with the BEntryList object. 43 44 Does nothing at this time. 45*/ 46 47 48/*! 49 \fn status_t BEntryList::GetNextEntry(BEntry *entry, bool traverse) 50 \brief Returns the BEntryList's next entry as a BEntry. 51 52 Places the next entry in the list in \a entry, traversing symlinks if 53 \a traverse is \c true. 54 55 \param entry a pointer to a BEntry to be initialized with the found entry. 56 \param traverse specifies whether to follow it, if the found entry 57 is a symbolic link. 58 59 \note The iterator used by this method is the same one used by 60 GetNextRef(), GetNextDirents(), Rewind() and CountEntries(). 61 62 \retval B_OK if successful 63 \retval B_ENTRY_NOT_FOUND when at the end of the list 64 \retval B_ERROR or another error code (depending on the implementation 65 of the derived class). 66*/ 67 68 69/*! 70 \fn status_t BEntryList::GetNextRef(entry_ref *ref) 71 \brief Returns the BEntryList's next entry as an entry_ref. 72 73 Places an entry_ref to the next entry in the list into \a ref. 74 75 \param ref a pointer to an entry_ref to be filled in with the data of the 76 found entry. 77 78 \note The iterator used by this method is the same one used by 79 GetNextEntry(), GetNextDirents(), Rewind() and CountEntries(). 80 81 \retval B_OK if successful 82 \retval B_ENTRY_NOT_FOUND when at the end of the list 83 \retval B_ERROR or another error code (depending on the implementation 84 of the derived class). 85*/ 86 87 88/*! 89 \fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length, 90 int32 count) 91 \brief Returns the BEntryList's next entries as dirent structures. 92 93 Reads a number of entries into the array of dirent structures pointed 94 to by \a buf. Reads as many but no more than \a count entries, as many 95 entries as remain, or as many entries as will fit into the array at 96 \a buf with given length \a length (in bytes), whichever is smallest. 97 98 \param buf A pointer to a buffer to be filled with dirent structures of 99 the found entries. 100 \param length The length of the \a buf array. 101 \param count the maximum number of entries to be read. 102 103 \note The iterator used by this method is the same one used by 104 GetNextEntry(), GetNextRef(), Rewind() and CountEntries(). 105 106 \returns 107 - The number of dirent structures stored in the buffer or 0 when 108 there are no more entries to be read. 109 - an error code (depending on the implementation of the derived class) 110 if an error occurred. 111*/ 112 113 114/*! 115 \fn status_t BEntryList::Rewind() 116 \brief Rewinds the list pointer to the beginning of the list. 117 118 \retval B_OK if successful 119 \retval B_ERROR or another error code (depending on the implementation 120 of the derived class). 121*/ 122 123 124/*! 125 \fn int32 BEntryList::CountEntries() 126 \brief Returns the number of entries in the list 127 128 \retval B_OK if successful 129 \retval B_ENTRY_NOT_FOUND when at the end of the list 130 \retval B_ERROR or another error code (depending on the implementation 131 of the derived class). 132*/