1/*
2 * Copyright 2002-2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Tyler Dauwalder
7 *		Axel Dörfler, axeld@pinc-software.de
8 *		John Scipione, jscipione@gmail.com
9 *		Ingo Weinhold, bonefish@users.sf.net
10 *
11 * Corresponds to:
12 *		headers/os/storage/Query.h	hrev47402
13 *		src/kits/storage/Query.cpp	hrev47402
14 */
15
16
17/*!
18	\file Query.h
19	\ingroup storage
20	\ingroup libbe
21	\brief Provides the BQuery class.
22*/
23
24
25/*!
26	\class BQuery
27	\ingroup storage
28	\ingroup libbe
29	\brief Provides an interface for creating file system queries and
30	       implements BEntryList methods for iterating through the results.
31
32	\since BeOS R3
33*/
34
35
36/*!
37	\fn BQuery::BQuery()
38	\brief Creates an uninitialized BQuery object.
39
40	\see SetPredicate()
41
42	\since BeOS R3
43*/
44
45
46/*!
47	\fn BQuery::~BQuery()
48	\brief Destroys the BQuery object and frees any associated resources.
49
50	\since BeOS R3
51*/
52
53
54/*!
55	\fn status_t BQuery::Clear()
56	\brief Resets the object to a uninitialized state.
57
58	\return \c B_OK
59
60	\since BeOS R3
61*/
62
63
64/*!
65	\fn status_t BQuery::Fetch()
66	\brief Start fetching entries satisfying the predicate.
67
68	After Fetch() has been called GetNextEntry(), GetNextRef() and
69	GetNextDirents() can be used to retrieve the entities. Live query updates
70	may be sent immediately after this method has been called.
71
72	Fetch() fails if it has already been called. To reuse the BQuery object it
73	must first be reset with the Clear() method.
74
75	\return A status code.
76	\retval B_OK Everything went fine.
77	\retval B_NO_INIT The object predicate or the volume wasn't set.
78	\retval B_BAD_VALUE The object predicate was invalid.
79	\retval B_NOT_ALLOWED Fetch() already called.
80
81	\since BeOS R3
82*/
83
84
85/*!
86	\name Predicate Push
87
88	Methods to push data onto the predicate stack.
89
90	\warning In BeOS R5 these methods returned \c void. That is checking the
91	         return value will render your code source and binary
92	         incompatible! Calling PushXYZ() after a Fetch() does change the
93	         predicate on R5, but it doesn't affect the active query and the
94	         newly created predicate can not even be used for the next query,
95	         since in order to be able to reuse the BQuery object for another
96	         query, Clear() has to be called and Clear() also deletes the
97	         predicate.
98*/
99
100
101//! @{
102
103
104/*!
105	\fn status_t BQuery::PushAttr(const char* attrName)
106	\brief Pushes an attribute name onto the predicate stack.
107
108	\param attrName The name of the attribute to push on the stack.
109
110	\return A status code.
111	\retval B_OK Everything went fine.
112	\retval B_NO_MEMORY Not enough memory.
113	\retval B_NOT_ALLOWED PushAttribute() was called after Fetch().
114
115	\since BeOS R3
116*/
117
118
119/*!
120	\fn status_t BQuery::PushOp(query_op op)
121	\brief Pushes an operator onto the predicate stack.
122
123	\param op The operator code to push onto the stack.
124
125	\return A status code.
126	\retval B_OK Everything went fine.
127	\retval B_NO_MEMORY Not enough memory.
128	\retval B_NOT_ALLOWED PushOp() was called after Fetch().
129
130	\since BeOS R3
131*/
132
133
134/*!
135	\fn status_t BQuery::PushUInt32(uint32 value)
136	\brief Pushes a \c uint32 onto the predicate stack.
137
138	\param value The \c uint32 to push onto the stack.
139
140	\return A status code.
141	\retval B_OK Everything went fine.
142	\retval B_NO_MEMORY Not enough memory.
143	\retval B_NOT_ALLOWED PushUInt32() was called after Fetch().
144
145	\since BeOS R3
146*/
147
148
149/*!
150	\fn status_t BQuery::PushInt32(int32 value)
151	\brief Pushes an \c int32 onto the predicate stack.
152
153	\param value The \c int32 to push onto the stack.
154
155	\return A status code.
156	\retval B_OK Everything went fine.
157	\retval B_NO_MEMORY Not enough memory.
158	\retval B_NOT_ALLOWED PushInt32() was called after Fetch().
159
160	\since BeOS R3
161*/
162
163
164/*!
165	\fn status_t BQuery::PushUInt64(uint64 value)
166	\brief Pushes a \c uint64 onto the predicate stack.
167
168	\param value The \c uint64 to push onto the stack.
169
170	\return A status code.
171	\retval B_OK Everything went fine.
172	\retval B_NO_MEMORY Not enough memory.
173	\retval B_NOT_ALLOWED PushUInt64() was called after Fetch().
174
175	\since BeOS R3
176*/
177
178
179/*!
180	\fn status_t BQuery::PushInt64(int64 value)
181	\brief Pushes an int64 onto the predicate stack.
182
183	\param value The \c int64 to push onto the stack.
184
185	\return A status code.
186	\retval B_OK Everything went fine.
187	\retval B_NO_MEMORY Not enough memory.
188	\retval B_NOT_ALLOWED PushInt64() was called after Fetch().
189
190	\since BeOS R3
191*/
192
193
194/*!
195	\fn status_t BQuery::PushFloat(float value)
196	\brief Pushes a \c float onto the predicate stack.
197
198	\param value The \c float to push onto the stack.
199
200	\return A status code.
201	\retval B_OK Everything went fine.
202	\retval B_NO_MEMORY Not enough memory.
203	\retval B_NOT_ALLOWED PushFloat() was called after Fetch().
204
205	\since BeOS R3
206*/
207
208
209/*!
210	\fn status_t BQuery::PushDouble(double value)
211	\brief Pushes a \c double onto the predicate stack.
212
213	\param value The \c double to push onto the stack.
214
215	\return A status code.
216	\retval B_OK Everything went fine.
217	\retval B_NO_MEMORY Not enough memory.
218	\retval B_NOT_ALLOWED PushDouble() was called after Fetch().
219
220	\since BeOS R3
221*/
222
223
224/*!
225	\fn status_t BQuery::PushString(const char* value, bool caseInsensitive)
226	\brief Pushes a string onto the predicate stack.
227
228	\param value The string to push onto the stack.
229	\param caseInsensitive Whether or not the case of \a value should be
230	       ignored in the resulting query.
231
232	\return A status code.
233	\retval B_OK Everything went fine.
234	\retval B_NO_MEMORY Not enough memory.
235	\retval B_NOT_ALLOWED PushString() was called after Fetch().
236
237	\since BeOS R3
238*/
239
240
241/*!
242	\fn status_t BQuery::PushDate(const char* date)
243	\brief Pushes a date string onto the predicate stack.
244
245	The supplied date can be any string understood by parsedate().
246
247	\param date The date string to push onto the stack.
248
249	\return A status code.
250	\retval B_OK Everything went fine.
251	\retval B_NO_MEMORY Not enough memory.
252	\retval B_NOT_ALLOWED PushDate() was called after Fetch().
253
254	\see parsedate()
255
256	\since Haiku R1
257*/
258
259
260//! @}
261
262
263/*!
264	\name Assignment
265*/
266
267
268//! @{
269
270
271/*!
272	\fn status_t BQuery::SetVolume(const BVolume* volume)
273	\brief Assigns \a volume to the BQuery object.
274
275	A query may only be assigned to one volume.
276
277	The method fails if called after Fetch(). To reuse the BQuery object it
278	must first be reset using the Clear() method.
279
280	\param volume The \a volume to set.
281
282	\return A status code.
283	\retval B_OK Everything went fine.
284	\retval B_NOT_ALLOWED SetVolume() was called after Fetch().
285
286	\since BeOS R3
287*/
288
289
290/*!
291	\fn status_t BQuery::SetPredicate(const char* expression)
292	\brief Assigns the passed-in predicate \a expression.
293
294	A predicate can be set either using this method or by constructing one on
295	the predicate stack, however, the two methods can not be mixed. The
296	predicate stack takes precedence over this method.
297
298	The method fails if called after Fetch(). To reuse the BQuery object it
299	must first be reset using the Clear() method.
300
301	\param expression The predicate \a expression to set.
302
303	\return A status code.
304	\retval B_OK Everything went fine.
305	\retval B_NO_MEMORY Not enough memory.
306	\retval B_NOT_ALLOWED SetPredicate() was called after Fetch().
307
308	\since BeOS R3
309*/
310
311
312/*!
313	\fn status_t BQuery::SetTarget(BMessenger messenger)
314	\brief Assigns the target \a messenger and makes the query live.
315
316	The query update messages are sent to the specified target. They might
317	roll in immediately after calling Fetch().
318
319	This methods fails if called after Fetch(). To reuse the BQuery object it
320	must first be reset via Clear().
321
322	\param messenger The target \a messenger to set.
323
324	\return A status code.
325	\retval B_OK Everything went fine.
326	\retval B_NO_MEMORY Not enough memory.
327	\retval B_NOT_ALLOWED SetTarget() was called after Fetch().
328
329	\since BeOS R3
330*/
331
332
333//! @}
334
335
336/*!
337	\name Query Information
338*/
339
340
341//! @{
342
343
344/*!
345	\fn bool BQuery::IsLive() const
346	\brief Gets whether the query associated with this object is live.
347
348	\return \c true, if the query is live, \c false otherwise.
349
350	\sa SetTarget()
351
352	\since BeOS R3
353*/
354
355
356/*!
357	\fn dev_t BQuery::TargetDevice() const
358	\brief Gets the device ID identifying the volume of the BQuery object.
359
360	\return The device ID of the volume or \c B_NO_INIT if the volume wasn't
361	        set.
362
363	\since BeOS R3
364
365	\since Haiku R1
366*/
367
368
369/*!
370	\fn size_t BQuery::PredicateLength()
371	\brief Gets the length of the predicate string.
372
373	This method returns the length of the string representation of the
374	predicate (including the terminating \c NUL) regardless of whether the
375	predicate has been constructed using the predicate stack or set via
376	SetPredicate().
377
378	\return The length of the predicate string or 0 if an error occurred.
379
380	\see SetPredicate()
381
382	\since BeOS R3
383*/
384
385
386//! @}
387
388
389/*!
390	\name Get Predicate
391
392	These methods fetch a string representation regardless of whether the
393	predicate has been constructed using the predicate stack or via
394	SetPredicate().
395
396	\note These methods cause the predicate stack to be evaluated and cleared.
397		  You can't interleave calls to push data and GetPredicate() methods.
398*/
399
400
401//! @{
402
403
404/*!
405	\fn status_t BQuery::GetPredicate(char* buffer, size_t length)
406	\brief Fills out \a buffer with the predicate string assigned to the
407	       BQuery object.
408
409	\param buffer A pointer to a buffer which the predicate is written to.
410	\param length the size of \a buffer.
411
412	\return A status code.
413	\retval B_OK Everything went fine.
414	\retval B_NO_INIT The predicate of the BQuery object wasn't set.
415	\retval B_BAD_VALUE \a buffer was \c NULL or too short.
416
417	\since BeOS R3
418*/
419
420
421/*!
422	\fn status_t BQuery::GetPredicate(BString* predicate)
423	\brief Fills out the passed-in BString object with the predicate string
424	       assigned to the BQuery object.
425
426	\param predicate A pointer to a BString object that gets filled out with
427	       the predicate string.
428
429	\return A status code.
430	\retval B_OK Everything went fine.
431	\retval B_NO_INIT The predicate of the BQuery object wasn't set.
432	\retval B_BAD_VALUE \a predicate was \c NULL.
433
434	\since Haiku R1
435*/
436
437
438//! @}
439
440
441/*!
442	\name BEntryList Interface
443
444	These methods are used to traverse the results of a query as a BEntryList.
445
446	\note The iterator used by these methods is the same one used by
447		  GetNextRef() and GetNextDirents().
448*/
449
450
451//! @{
452
453
454/*!
455	\fn status_t BQuery::GetNextEntry(BEntry* entry, bool traverse)
456	\brief Fills out \a entry with the next entry traversing symlinks if
457	       \a traverse is \c true.
458
459	\param entry A pointer to a BEntry object initialized with the entry.
460	\param traverse Whether or not to follow symbolic links.
461
462	\return A status code.
463	\retval B_OK Everything went fine.
464	\retval B_ENTRY_NOT_FOUND At end of list.
465	\retval B_BAD_VALUE The predicate included unindexed attributes.
466	\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
467
468	\since BeOS R3
469*/
470
471
472/*!
473	\fn status_t BQuery::GetNextRef(entry_ref* ref)
474	\brief Fills out \a ref with the next entry as an entry_ref.
475
476	\param ref A pointer to an entry_ref object filled out with the
477	       entry's data.
478
479	\return A status code.
480	\retval B_OK Everything went fine.
481	\retval B_ENTRY_NOT_FOUND At end of list.
482	\retval B_BAD_VALUE The predicate included unindexed attributes.
483	\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
484
485	\since BeOS R3
486*/
487
488
489/*!
490	\fn int32 BQuery::GetNextDirents(struct dirent* buffer, size_t length,
491		int32 count)
492	\brief Fill out up to \a count entries into the array of dirent structs
493	       pointed to by \a buffer.
494
495	Reads as many but no more than \a count entries, as many entries as
496	remain, or as many entries as will fit into the array at \a buffer with
497	the given \a length (in bytes), whichever is smallest.
498
499	\param buffer A pointer to a buffer filled out with dirent structures of
500		   the entries.
501	\param length The length of \a buffer.
502	\param count The maximum number of entries to be read.
503
504	\return The number of dirent structures stored in the buffer, 0 when there
505	        are no more entries to be read, or an error code.
506	\retval B_BAD_VALUE The predicate included unindexed attributes.
507	\retval B_FILE_ERROR Fetch() was not previously called on the object.
508
509	\since BeOS R3
510*/
511
512
513/*!
514	\fn status_t BQuery::Rewind()
515	\brief Rewinds the entry list back to the first entry.
516
517	\note BeOS R5 does not implement this method for BQuery.
518
519	\return A status code.
520	\retval B_OK Everything went fine.
521	\retval B_FILE_ERROR Fetch() was not previously called on the object.
522
523	\since BeOS R3
524*/
525
526
527/*!
528	\fn int32 BQuery::CountEntries()
529	\brief Unimplemented.
530
531	\return \c B_ERROR.
532
533	\since BeOS R3
534*/
535
536
537//! @}
538