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