/** Copyright 2002-2014 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Tyler Dauwalder* Axel Dörfler, axeld@pinc-software.de* John Scipione, jscipione@gmail.com* Ingo Weinhold, bonefish@users.sf.net** Corresponds to:* headers/os/storage/Query.h hrev47402* src/kits/storage/Query.cpp hrev47402*//*!\file Query.h\ingroup storage\ingroup libbe\brief Provides the BQuery class.*//*!\class BQuery\ingroup storage\ingroup libbe\brief Provides an interface for creating file system queries andimplements BEntryList methods for iterating through the results.\since BeOS R3*//*!\fn BQuery::BQuery()\brief Creates an uninitialized BQuery object.\see SetPredicate()\since BeOS R3*//*!\fn BQuery::~BQuery()\brief Destroys the BQuery object and frees any associated resources.\since BeOS R3*//*!\fn status_t BQuery::Clear()\brief Resets the object to a uninitialized state.\return \c B_OK\since BeOS R3*//*!\fn status_t BQuery::Fetch()\brief Start fetching entries satisfying the predicate.After Fetch() has been called GetNextEntry(), GetNextRef() andGetNextDirents() can be used to retrieve the entities. Live query updatesmay be sent immediately after this method has been called.Fetch() fails if it has already been called. To reuse the BQuery object itmust first be reset with the Clear() method.\return A status code.\retval B_OK Everything went fine.\retval B_NO_INIT The object predicate or the volume wasn't set.\retval B_BAD_VALUE The object predicate was invalid.\retval B_NOT_ALLOWED Fetch() already called.\since BeOS R3*//*!\name Predicate PushMethods to push data onto the predicate stack.\warning In BeOS R5 these methods returned \c void. That is checking thereturn value will render your code source and binaryincompatible! Calling PushXYZ() after a Fetch() does change thepredicate on R5, but it doesn't affect the active query and thenewly created predicate can not even be used for the next query,since in order to be able to reuse the BQuery object for anotherquery, Clear() has to be called and Clear() also deletes thepredicate.*///! @{/*!\fn status_t BQuery::PushAttr(const char* attrName)\brief Pushes an attribute name onto the predicate stack.\param attrName The name of the attribute to push on the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushAttribute() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushOp(query_op op)\brief Pushes an operator onto the predicate stack.\param op The operator code to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushOp() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushUInt32(uint32 value)\brief Pushes a \c uint32 onto the predicate stack.\param value The \c uint32 to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushUInt32() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushInt32(int32 value)\brief Pushes an \c int32 onto the predicate stack.\param value The \c int32 to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushInt32() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushUInt64(uint64 value)\brief Pushes a \c uint64 onto the predicate stack.\param value The \c uint64 to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushUInt64() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushInt64(int64 value)\brief Pushes an int64 onto the predicate stack.\param value The \c int64 to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushInt64() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushFloat(float value)\brief Pushes a \c float onto the predicate stack.\param value The \c float to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushFloat() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushDouble(double value)\brief Pushes a \c double onto the predicate stack.\param value The \c double to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushDouble() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushString(const char* value, bool caseInsensitive)\brief Pushes a string onto the predicate stack.\param value The string to push onto the stack.\param caseInsensitive Whether or not the case of \a value should beignored in the resulting query.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushString() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::PushDate(const char* date)\brief Pushes a date string onto the predicate stack.The supplied date can be any string understood by parsedate().\param date The date string to push onto the stack.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED PushDate() was called after Fetch().\see parsedate()\since Haiku R1*///! @}/*!\name Assignment*///! @{/*!\fn status_t BQuery::SetVolume(const BVolume* volume)\brief Assigns \a volume to the BQuery object.A query may only be assigned to one volume.The method fails if called after Fetch(). To reuse the BQuery object itmust first be reset using the Clear() method.\param volume The \a volume to set.\return A status code.\retval B_OK Everything went fine.\retval B_NOT_ALLOWED SetVolume() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::SetPredicate(const char* expression)\brief Assigns the passed-in predicate \a expression.A predicate can be set either using this method or by constructing one onthe predicate stack, however, the two methods can not be mixed. Thepredicate stack takes precedence over this method.The method fails if called after Fetch(). To reuse the BQuery object itmust first be reset using the Clear() method.\param expression The predicate \a expression to set.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED SetPredicate() was called after Fetch().\since BeOS R3*//*!\fn status_t BQuery::SetTarget(BMessenger messenger)\brief Assigns the target \a messenger and makes the query live.The query update messages are sent to the specified target. They mightroll in immediately after calling Fetch().This methods fails if called after Fetch(). To reuse the BQuery object itmust first be reset via Clear().\param messenger The target \a messenger to set.\return A status code.\retval B_OK Everything went fine.\retval B_NO_MEMORY Not enough memory.\retval B_NOT_ALLOWED SetTarget() was called after Fetch().\since BeOS R3*///! @}/*!\name Query Information*///! @{/*!\fn bool BQuery::IsLive() const\brief Gets whether the query associated with this object is live.\return \c true, if the query is live, \c false otherwise.\sa SetTarget()\since BeOS R3*//*!\fn dev_t BQuery::TargetDevice() const\brief Gets the device ID identifying the volume of the BQuery object.\return The device ID of the volume or \c B_NO_INIT if the volume wasn'tset.\since BeOS R3\since Haiku R1*//*!\fn size_t BQuery::PredicateLength()\brief Gets the length of the predicate string.This method returns the length of the string representation of thepredicate (including the terminating \c NUL) regardless of whether thepredicate has been constructed using the predicate stack or set viaSetPredicate().\return The length of the predicate string or 0 if an error occurred.\see SetPredicate()\since BeOS R3*///! @}/*!\name Get PredicateThese methods fetch a string representation regardless of whether thepredicate has been constructed using the predicate stack or viaSetPredicate().\note These methods cause the predicate stack to be evaluated and cleared.You can't interleave calls to push data and GetPredicate() methods.*///! @{/*!\fn status_t BQuery::GetPredicate(char* buffer, size_t length)\brief Fills out \a buffer with the predicate string assigned to theBQuery object.\param buffer A pointer to a buffer which the predicate is written to.\param length the size of \a buffer.\return A status code.\retval B_OK Everything went fine.\retval B_NO_INIT The predicate of the BQuery object wasn't set.\retval B_BAD_VALUE \a buffer was \c NULL or too short.\since BeOS R3*//*!\fn status_t BQuery::GetPredicate(BString* predicate)\brief Fills out the passed-in BString object with the predicate stringassigned to the BQuery object.\param predicate A pointer to a BString object that gets filled out withthe predicate string.\return A status code.\retval B_OK Everything went fine.\retval B_NO_INIT The predicate of the BQuery object wasn't set.\retval B_BAD_VALUE \a predicate was \c NULL.\since Haiku R1*///! @}/*!\name BEntryList InterfaceThese methods are used to traverse the results of a query as a BEntryList.\note The iterator used by these methods is the same one used byGetNextRef() and GetNextDirents().*///! @{/*!\fn status_t BQuery::GetNextEntry(BEntry* entry, bool traverse)\brief Fills out \a entry with the next entry traversing symlinks if\a traverse is \c true.\param entry A pointer to a BEntry object initialized with the entry.\param traverse Whether or not to follow symbolic links.\return A status code.\retval B_OK Everything went fine.\retval B_ENTRY_NOT_FOUND At end of list.\retval B_BAD_VALUE The predicate included unindexed attributes.\retval B_NOT_ALLOWED Fetch() was not previously called on the object.\since BeOS R3*//*!\fn status_t BQuery::GetNextRef(entry_ref* ref)\brief Fills out \a ref with the next entry as an entry_ref.\param ref A pointer to an entry_ref object filled out with theentry's data.\return A status code.\retval B_OK Everything went fine.\retval B_ENTRY_NOT_FOUND At end of list.\retval B_BAD_VALUE The predicate included unindexed attributes.\retval B_NOT_ALLOWED Fetch() was not previously called on the object.\since BeOS R3*//*!\fn int32 BQuery::GetNextDirents(struct dirent* buffer, size_t length,int32 count)\brief Fill out up to \a count entries into the array of dirent structspointed to by \a buffer.Reads as many but no more than \a count entries, as many entries asremain, or as many entries as will fit into the array at \a buffer withthe given \a length (in bytes), whichever is smallest.\param buffer A pointer to a buffer filled out with dirent structures ofthe entries.\param length The length of \a buffer.\param count The maximum number of entries to be read.\return The number of dirent structures stored in the buffer, 0 when thereare no more entries to be read, or an error code.\retval B_BAD_VALUE The predicate included unindexed attributes.\retval B_FILE_ERROR Fetch() was not previously called on the object.\since BeOS R3*//*!\fn status_t BQuery::Rewind()\brief Rewinds the entry list back to the first entry.\note BeOS R5 does not implement this method for BQuery.\return A status code.\retval B_OK Everything went fine.\retval B_FILE_ERROR Fetch() was not previously called on the object.\since BeOS R3*//*!\fn int32 BQuery::CountEntries()\brief Unimplemented.\return \c B_ERROR.\since BeOS R3*///! @}