From 0a9ac70aeaf2ced3be4b252416d7e68972c7f5ce Mon Sep 17 00:00:00 2001 From: John Scipione Date: Thu, 14 Feb 2013 19:36:33 -0500 Subject: [PATCH] Move BQuery docs into Haiku Book. ... removing the docs from the .cpp and .h files and cleaning up as usual. --- docs/user/storage/Query.dox | 547 ++++++++++++++++++++++++++++++++++++ headers/os/storage/Query.h | 11 - src/kits/storage/Query.cpp | 359 +++-------------------- 3 files changed, 580 insertions(+), 337 deletions(-) create mode 100644 docs/user/storage/Query.dox diff --git a/docs/user/storage/Query.dox b/docs/user/storage/Query.dox new file mode 100644 index 0000000000..07239bbf19 --- /dev/null +++ b/docs/user/storage/Query.dox @@ -0,0 +1,547 @@ +/* + * Copyright 2002-2013 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 hrev45283 + * src/kits/storage/Query.cpp hrev45283 + */ + + +/*! + \file Query.h + \ingroup storage + \ingroup libbe + Provides the BQuery class. +*/ + + +/*! + \class BQuery + \ingroup storage + \ingroup libbe + \brief Provides an interface for creating file system queries and + implements BEntryList methods for iterating through the results. +*/ + + +/*! + \fn BQuery::BQuery() + \brief Creates an uninitialized BQuery object. + + \see SetPredicate() +*/ + + +/*! + \fn BQuery::~BQuery() + \brief Destroys the BQuery object and frees any associated resources. +*/ + + +/*! + \fn status_t BQuery::Clear() + \brief Resets the object to a uninitialized state. + + \return \c B_OK +*/ + + +/*! + \fn status_t BQuery::Fetch() + \brief Start fetching entries satisfying the predicate. + + After Fetch() has been called GetNextEntry(), GetNextRef() and + GetNextDirents() can be used to retrieve the entities. Live query updates + may be sent immediately after this method has been called. + + Fetch() fails if it has already been called. To reuse the BQuery object it + must 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. +*/ + + +/*! + \name Predicate push methods + + Methods to push data onto the predicate stack. + + \warning In BeOS R5 these methods returned \c void. That is checking the + return value will render your code source and binary + incompatible! Calling PushXYZ() after a Fetch() does change the + predicate on R5, but it doesn't affect the active query and the + newly created predicate can not even be used for the next query, + since in order to be able to reuse the BQuery object for another + query, Clear() has to be called and Clear() also deletes the + predicate. +*/ + + +//! @{ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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(). +*/ + + +/*! + \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 be + ignored 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(). +*/ + + +/*! + \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() +*/ + + +//! @} + + +/*! + \name Assignment methods +*/ + + +//! @{ + + +/*! + \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 it + must 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(). +*/ + + +/*! + \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 on + the predicate stack, however, the two methods can not be mixed. The + predicate stack takes precedence over this method. + + The method fails if called after Fetch(). To reuse the BQuery object it + must 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(). +*/ + + +/*! + \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 might + roll in immediately after calling Fetch(). + + This methods fails if called after Fetch(). To reuse the BQuery object it + must 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(). +*/ + + +//! @} + + +/*! + \name Query information methods +*/ + + +//! @{ + + +/*! + \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. +*/ + + +/*! + \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't + set. +*/ + + +/*! + \fn size_t BQuery::PredicateLength() + \brief Gets the length of the predicate string. + + This method returns the length of the string representation of the + predicate (including the terminating \c NUL) regardless of whether the + predicate has been constructed using the predicate stack or set via + SetPredicate(). + + \return The length of the predicate string or 0 if an error occurred. +*/ + + +//! @} + + +/*! + \name Get predicate methods + + These methods fetch a string representation regardless of whether the + predicate has been constructed using the predicate stack or via + SetPredicate(). + + \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 the + BQuery 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. +*/ + + +/*! + \fn status_t BQuery::GetPredicate(BString* predicate) + \brief Fills out the passed-in BString object with the predicate string + assigned to the BQuery object. + + \param predicate A pointer to a BString object that gets filled out with + the 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. +*/ + + +//! @} + + +/*! + \name BEntryList interface methods + + These 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 by + GetNextRef() 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. +*/ + + +/*! + \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 the + entry'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. +*/ + + +/*! + \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 structs + pointed to by \a buffer. + + Reads as many but no more than \a count entries, as many entries as + remain, or as many entries as will fit into the array at \a buffer with + the given \a length (in bytes), whichever is smallest. + + \param buffer A pointer to a buffer filled out with dirent structures of + the 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 there + are 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. +*/ + + +/*! + \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. +*/ + + +/*! + \fn int32 BQuery::CountEntries() + \brief Unimplemented. + + \return \c B_ERROR. +*/ + + +//! @} + + +/// private methods, won't show up in docs + + +/*! + \fn bool BQuery::_HasFetched() const + \brief Gets whether Fetch() has already been called on this object. + + \return \c true, if Fetch() was already called, \c false otherwise. +*/ + + +/*! + \fn status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError) + \brief Pushes a node onto the predicate stack. + + If the stack has not been allocate until this time, this method does + allocate it. + + If the supplied node is \c NULL, it is assumed that there was not enough + memory to allocate the node and thus \c B_NO_MEMORY is returned. + + In case the method fails, the caller retains the ownership of the supplied + node and thus is responsible for deleting it, if \a deleteOnError is + \c false. If it is \c true, the node is deleted, if an error occurs. + + \param node The node to push. + \param deleteOnError Whether or not to delete the node if an error occurs. + + \return A status code. + \retval B_OK Everything went fine. + \retval B_NO_MEMORY \a node was \c NULL or there was insufficient memory to + allocate the predicate stack or push the node. + \retval B_NOT_ALLOWED _PushNode() was called after Fetch(). +*/ + + +/*! + \fn status_t BQuery::_SetPredicate(const char* expression) + \brief Helper method to set the predicate. + + Does not check whether Fetch() has already been invoked. + + \param expression The predicate string to set. + + \return A status code. + \retval B_OK Everything went fine. + \retval B_NO_MEMORY There was insufficient memory to store the predicate. +*/ + + +/*! + \fn status_t BQuery::_EvaluateStack() + Evaluates the predicate stack. + + The method does nothing (and returns \c B_OK), if the stack is \c NULL. + If the stack is not \c null and Fetch() has already been called, this + method fails. + + \return A status code. + \retval B_OK Everything went fine. + \retval B_NO_MEMORY There was insufficient memory. + \retval B_NOT_ALLOWED _EvaluateStack() was called after Fetch(). +*/ + + +/*! + \fn void BQuery::_ParseDates(BString& parsedPredicate) + \brief Fills out \a parsedPredicate with a parsed predicate string. + + \param parsedPredicate The predicate string to fill out. +*/ diff --git a/headers/os/storage/Query.h b/headers/os/storage/Query.h index cb07dcd921..fff4c7522d 100644 --- a/headers/os/storage/Query.h +++ b/headers/os/storage/Query.h @@ -40,17 +40,6 @@ typedef enum { } query_op; -/*! - \class BQuery - \brief Represents a live or non-live file system query - - Provides an interface for creating file system queries. Implements - the BEntryList for iterating through the found entries. - - \author Ingo Weinhold - - \version 0.0.0 -*/ class BQuery : public BEntryList { public: BQuery(); diff --git a/src/kits/storage/Query.cpp b/src/kits/storage/Query.cpp index 990331cea2..64187511e7 100644 --- a/src/kits/storage/Query.cpp +++ b/src/kits/storage/Query.cpp @@ -32,8 +32,7 @@ using namespace std; using namespace BPrivate::Storage; -/*! \brief Creates an uninitialized BQuery. -*/ +// Creates an uninitialized BQuery. BQuery::BQuery() : BEntryList(), @@ -48,17 +47,14 @@ BQuery::BQuery() } -/*! \brief Frees all resources associated with the object. -*/ +// Frees all resources associated with the object. BQuery::~BQuery() { Clear(); } -/*! \brief Resets the object to a uninitialized state. - \return \c B_OK -*/ +// Resets the object to a uninitialized state. status_t BQuery::Clear() { @@ -82,20 +78,7 @@ BQuery::Clear() } -/*! \brief Pushes an attribute name onto the BQuery's predicate stack. - \param attrName the attribute name - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushAttribute() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes an attribute name onto the predicate stack. status_t BQuery::PushAttr(const char* attrName) { @@ -103,20 +86,7 @@ BQuery::PushAttr(const char* attrName) } -/*! \brief Pushes an operator onto the BQuery's predicate stack. - \param op the code representing the operator - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushOp() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes an operator onto the predicate stack. status_t BQuery::PushOp(query_op op) { @@ -146,20 +116,7 @@ BQuery::PushOp(query_op op) } -/*! \brief Pushes a uint32 value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushUInt32() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a uint32 onto the predicate stack. status_t BQuery::PushUInt32(uint32 value) { @@ -167,20 +124,7 @@ BQuery::PushUInt32(uint32 value) } -/*! \brief Pushes an int32 value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushInt32() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes an int32 onto the predicate stack. status_t BQuery::PushInt32(int32 value) { @@ -188,20 +132,7 @@ BQuery::PushInt32(int32 value) } -/*! \brief Pushes a uint64 value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushUInt64() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a uint64 onto the predicate stack. status_t BQuery::PushUInt64(uint64 value) { @@ -209,20 +140,7 @@ BQuery::PushUInt64(uint64 value) } -/*! \brief Pushes an int64 value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushInt64() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes an int64 onto the predicate stack. status_t BQuery::PushInt64(int64 value) { @@ -230,20 +148,7 @@ BQuery::PushInt64(int64 value) } -/*! \brief Pushes a float value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushFloat() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a float onto the predicate stack. status_t BQuery::PushFloat(float value) { @@ -251,20 +156,7 @@ BQuery::PushFloat(float value) } -/*! \brief Pushes a double value onto the BQuery's predicate stack. - \param value the value - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushDouble() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a double onto the predicate stack. status_t BQuery::PushDouble(double value) { @@ -272,22 +164,7 @@ BQuery::PushDouble(double value) } -/*! \brief Pushes a string value onto the BQuery's predicate stack. - \param value the value - \param caseInsensitive \c true, if the case of the string should be - ignored, \c false otherwise - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Not enough memory. - - \c B_NOT_ALLOWED: PushString() was called after Fetch(). - \note In BeOS R5 this method returns \c void. That is checking the return - value will render your code source and binary incompatible! - Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a string onto the predicate stack. status_t BQuery::PushString(const char* value, bool caseInsensitive) { @@ -295,20 +172,7 @@ BQuery::PushString(const char* value, bool caseInsensitive) } -/*! \brief Pushes a date value onto the BQuery's predicate stack. - The supplied date can be any string understood by the POSIX function - parsedate(). - \param date the date string - \return - - \c B_OK: Everything went fine. - - \c B_ERROR: Error parsing the string. - - \c B_NOT_ALLOWED: PushDate() was called after Fetch(). - \note Calling PushXYZ() after a Fetch() does change the predicate on R5, - but it doesn't affect the active query and the newly created - predicate can not even be used for the next query, since in order - to be able to reuse the BQuery object for another query, Clear() has - to be called and Clear() also deletes the predicate. -*/ +// Pushes a date onto the predicate stack. status_t BQuery::PushDate(const char* date) { @@ -319,15 +183,7 @@ BQuery::PushDate(const char* date) } -/*! \brief Sets the BQuery's volume. - A query is restricted to one volume. This method sets this volume. It - fails, if called after Fetch(). To reuse a BQuery object it has to be - reset via Clear(). - \param volume the volume - \return - - \c B_OK: Everything went fine. - - \c B_NOT_ALLOWED: SetVolume() was called after Fetch(). -*/ +// Assigns a volume to the BQuery object. status_t BQuery::SetVolume(const BVolume* volume) { @@ -345,18 +201,7 @@ BQuery::SetVolume(const BVolume* volume) } -/*! \brief Sets the BQuery's predicate. - A predicate can be set either using this method or constructing one on - the predicate stack. The two methods can not be mixed. The letter one - has precedence over this one. - The method fails, if called after Fetch(). To reuse a BQuery object it has - to be reset via Clear(). - \param predicate the predicate string - \return - - \c B_OK: Everything went fine. - - \c B_NOT_ALLOWED: SetPredicate() was called after Fetch(). - - \c B_NO_MEMORY: Insufficient memory to store the predicate. -*/ +// Assigns the passed-in predicate expression. status_t BQuery::SetPredicate(const char* expression) { @@ -369,16 +214,7 @@ BQuery::SetPredicate(const char* expression) } -/*! \brief Sets the BQuery's target and makes the query live. - The query update messages are sent to the specified target. They might - roll in immediately after calling Fetch(). - This methods fails, if called after Fetch(). To reuse a BQuery object it - has to be reset via Clear(). - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \a messenger was not properly initialized. - - \c B_NOT_ALLOWED: SetTarget() was called after Fetch(). -*/ +// Assigns the target messenger and makes the query live. status_t BQuery::SetTarget(BMessenger messenger) { @@ -396,9 +232,7 @@ BQuery::SetTarget(BMessenger messenger) } -/*! \brief Returns whether the query associated with this object is live. - \return \c true, if the query is live, \c false otherwise -*/ +// Gets whether the query associated with this object is live. bool BQuery::IsLive() const { @@ -406,20 +240,7 @@ BQuery::IsLive() const } -/*! \brief Returns the BQuery's predicate. - Regardless of whether the predicate has been constructed using the - predicate stack or set via SetPredicate(), this method returns a - string representation. - \param buffer a pointer to a buffer into which the predicate shall be - written - \param length the size of the provided buffer - \return - - \c B_OK: Everything went fine. - - \c B_NO_INIT: The predicate isn't set. - - \c B_BAD_VALUE: \a buffer is \c NULL or too short. - \note This method causes the predicate stack to be evaluated and cleared. - You can't interleave Push*() and GetPredicate() calls. -*/ +// Fills out buffer with the predicate string assigned to the BQuery object. status_t BQuery::GetPredicate(char* buffer, size_t length) { @@ -436,19 +257,8 @@ BQuery::GetPredicate(char* buffer, size_t length) } -/*! \brief Returns the BQuery's predicate. - Regardless of whether the predicate has been constructed using the - predicate stack or set via SetPredicate(), this method returns a - string representation. - \param predicate a pointer to a BString which shall be set to the - predicate string - \return - - \c B_OK: Everything went fine. - - \c B_NO_INIT: The predicate isn't set. - - \c B_BAD_VALUE: \c NULL \a predicate. - \note This method causes the predicate stack to be evaluated and cleared. - You can't interleave Push*() and GetPredicate() calls. -*/ +// Fills out the passed-in BString object with the predicate string +// assigned to the BQuery object. status_t BQuery::GetPredicate(BString* predicate) { @@ -463,16 +273,7 @@ BQuery::GetPredicate(BString* predicate) } -/*! \brief Returns the length of the BQuery's predicate string. - Regardless of whether the predicate has been constructed using the - predicate stack or set via SetPredicate(), this method returns the length - of its string representation (counting the terminating null). - \return - - the length of the predicate string (counting the terminating null) or - - 0, if an error occured - \note This method causes the predicate stack to be evaluated and cleared. - You can't interleave Push*() and PredicateLength() calls. -*/ +// Gets the length of the predicate string. size_t BQuery::PredicateLength() { @@ -486,10 +287,7 @@ BQuery::PredicateLength() } -/*! \brief Returns the device ID identifying the BQuery's volume. - \return the device ID of the BQuery's volume or \c B_NO_INIT, if the - volume isn't set. -*/ +// Gets the device ID identifying the volume of the BQuery object. dev_t BQuery::TargetDevice() const { @@ -497,18 +295,7 @@ BQuery::TargetDevice() const } -/*! \brief Tells the BQuery to start fetching entries satisfying the predicate. - After Fetch() has been called GetNextEntry(), GetNextRef() and - GetNextDirents() can be used to retrieve the enties. Live query updates - may be sent immediately after this method has been called. - Fetch() fails, if it has already been called. To reuse a BQuery object it - has to be reset via Clear(). - \return - - \c B_OK: Everything went fine. - - \c B_NO_INIT: The predicate or the volume aren't set. - - \c B_BAD_VALUE: The predicate is invalid. - - \c B_NOT_ALLOWED: Fetch() has already been called. -*/ +// Start fetching entries satisfying the predicate. status_t BQuery::Fetch() { @@ -538,20 +325,7 @@ BQuery::Fetch() // #pragma mark - BEntryList interface -/*! \brief Returns the BQuery's next entry as a BEntry. - Places the next entry in the list in \a entry, traversing symlinks if - \a traverse is \c true. - \param entry a pointer to a BEntry to be initialized with the found entry - \param traverse specifies whether to follow it, if the found entry - is a symbolic link. - \note The iterator used by this method is the same one used by - GetNextRef() and GetNextDirents(). - \return - - \c B_OK if successful, - - \c B_ENTRY_NOT_FOUND when at the end of the list, - - \c B_BAD_VALUE: The queries predicate includes unindexed attributes. - - \c B_FILE_ERROR: Fetch() has not been called before. -*/ +// Fills out entry with the next entry traversing symlinks if traverse is true. status_t BQuery::GetNextEntry(BEntry* entry, bool traverse) { @@ -566,18 +340,7 @@ BQuery::GetNextEntry(BEntry* entry, bool traverse) } -/*! \brief Returns the BQuery's next entry as an entry_ref. - Places an entry_ref to the next entry in the list into \a ref. - \param ref a pointer to an entry_ref to be filled in with the data of the - found entry - \note The iterator used by this method is the same one used by - GetNextEntry() and GetNextDirents(). - \return - - \c B_OK if successful, - - \c B_ENTRY_NOT_FOUND when at the end of the list, - - \c B_BAD_VALUE: The queries predicate includes unindexed attributes. - - \c B_FILE_ERROR: Fetch() has not been called before. -*/ +// Fills out ref with the next entry as an entry_ref. status_t BQuery::GetNextRef(entry_ref* ref) { @@ -605,22 +368,8 @@ BQuery::GetNextRef(entry_ref* ref) } -/*! \brief Returns the BQuery's next entries as dirent structures. - Reads a number of entries into the array of dirent structures pointed to by - \a buf. Reads as many but no more than \a count entries, as many entries as - remain, or as many entries as will fit into the array at \a buf with given - length \a length (in bytes), whichever is smallest. - \param buf a pointer to a buffer to be filled with dirent structures of - the found entries - \param length the maximal number of entries to be read. - \note The iterator used by this method is the same one used by - GetNextEntry() and GetNextRef(). - \return - - The number of dirent structures stored in the buffer, 0 when there are - no more entries to be read. - - \c B_BAD_VALUE: The queries predicate includes unindexed attributes. - - \c B_FILE_ERROR: Fetch() has not been called before. -*/ +// Fill out up to count entries into the array of dirent structs pointed +// to by buffer. int32 BQuery::GetNextDirents(struct dirent* buffer, size_t length, int32 count) { @@ -632,14 +381,7 @@ BQuery::GetNextDirents(struct dirent* buffer, size_t length, int32 count) } -/*! \brief Rewinds the entry list back to the first entry. - - Unlike R5 Haiku implements this method for BQuery. - - \return - - \c B_OK on success, - - \c B_FILE_ERROR, if Fetch() has not yet been called. -*/ +// Rewinds the entry list back to the first entry. status_t BQuery::Rewind() { @@ -649,9 +391,7 @@ BQuery::Rewind() } -/*! \brief Unimplemented method of the BEntryList interface. - \return 0. -*/ +// Unimplemented method of the BEntryList interface. int32 BQuery::CountEntries() { @@ -659,10 +399,7 @@ BQuery::CountEntries() } -/*! Returns whether Fetch() has already been called on this object. - \return \c true, if Fetch() has successfully been invoked, \c false - otherwise. -*/ +// Gets whether Fetch() has already been called on this object. bool BQuery::_HasFetched() const { @@ -670,22 +407,7 @@ BQuery::_HasFetched() const } -/*! \brief Pushs a node onto the predicate stack. - If the stack has not been allocate until this time, this method does - allocate it. - If the supplied node is \c NULL, it is assumed that there was not enough - memory to allocate the node and thus \c B_NO_MEMORY is returned. - In case the method fails, the caller retains the ownership of the supplied - node and thus is responsible for deleting it, if \a deleteOnError is - \c false. If it is \c true, the node is deleted, if an error occurs. - \param node the node to be pushed - \param deleteOnError - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: \c NULL \a node or insuffient memory to allocate the - predicate stack or push the node. - - \c B_NOT_ALLOWED: _PushNode() was called after Fetch(). -*/ +// Pushes a node onto the predicate stack. status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError) { @@ -706,13 +428,7 @@ BQuery::_PushNode(QueryNode* node, bool deleteOnError) } -/*! \brief Helper method to set the BQuery's predicate. - It is not checked whether Fetch() has already been invoked. - \param predicate the predicate string - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Insufficient memory to store the predicate. -*/ +// Helper method to set the predicate. status_t BQuery::_SetPredicate(const char* expression) { @@ -732,16 +448,7 @@ BQuery::_SetPredicate(const char* expression) } -/*! Evaluates the query's predicate stack. - The method does nothing (and returns \c B_OK), if the stack is \c NULL. - If the stack is non-null and Fetch() has already been called, the method - fails. - \return - - \c B_OK: Everything went fine. - - \c B_NO_MEMORY: Insufficient memory. - - \c B_NOT_ALLOWED: _EvaluateStack() was called after Fetch(). - - another error code -*/ +// Evaluates the predicate stack. status_t BQuery::_EvaluateStack() {