[haiku-commits] haiku: hrev45284 - src/kits/storage docs/user/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Fri, 15 Feb 2013 01:40:00 +0100 (CET)
hrev45284 adds 2 changesets to branch 'master'
old head: b3247c59feaf0fa16e8ce009d675e166c8ca4f89
new head: 0a9ac70aeaf2ced3be4b252416d7e68972c7f5ce
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=0a9ac70+%5Eb3247c5
----------------------------------------------------------------------------
6d28790: Fix warning and cleanup for BPath docs
0a9ac70: Move BQuery docs into Haiku Book.
... removing the docs from the .cpp and .h files and cleaning up as usual.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
4 files changed, 582 insertions(+), 340 deletions(-)
docs/user/storage/Path.dox | 5 +-
docs/user/storage/Query.dox | 547 ++++++++++++++++++++++++++++++++++++++++
headers/os/storage/Query.h | 11 -
src/kits/storage/Query.cpp | 359 +++-----------------------
############################################################################
Commit: 6d287908b15e883d38d450ccc8a0a2335383acba
URL: http://cgit.haiku-os.org/haiku/commit/?id=6d28790
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Fri Feb 15 00:35:48 2013 UTC
Fix warning and cleanup for BPath docs
----------------------------------------------------------------------------
diff --git a/docs/user/storage/Path.dox b/docs/user/storage/Path.dox
index 47b679a..64929f4 100644
--- a/docs/user/storage/Path.dox
+++ b/docs/user/storage/Path.dox
@@ -81,7 +81,6 @@
- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
- Redundant slashes ("/boot//ltj")
- A trailing slash ("/boot/ltj/")
-
*/
@@ -106,7 +105,7 @@
/*!
\fn BPath::~BPath()
- \brief Destroys the BPath object and frees any of its associated
resources.
+ \brief Destroys the BPath object and frees any associated resources.
*/
@@ -456,7 +455,7 @@
The type code must be set to \c B_REF_TYPE.
\param code The type code of the flattened data, must be \c B_REF_TYPE.
- \param buf A pointer to the flattened data.
+ \param buffer A pointer to a buffer containing the flattened data.
\param size The size of \a buffer in bytes.
\returns A status code.
############################################################################
Revision: hrev45284
Commit: 0a9ac70aeaf2ced3be4b252416d7e68972c7f5ce
URL: http://cgit.haiku-os.org/haiku/commit/?id=0a9ac70
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Fri Feb 15 00:36:33 2013 UTC
Move BQuery docs into Haiku Book.
... removing the docs from the .cpp and .h files and cleaning up as usual.
----------------------------------------------------------------------------
diff --git a/docs/user/storage/Query.dox b/docs/user/storage/Query.dox
new file mode 100644
index 0000000..07239bb
--- /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@xxxxxxxxxxxxxxxx
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * 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 cb07dcd..fff4c75 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 <a href='mailto:bonefish@xxxxxxxxxxxx'>Ingo Weinhold</a>
-
- \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 990331c..6418751 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()
{
Other related posts:
- » [haiku-commits] haiku: hrev45284 - src/kits/storage docs/user/storage - jscipione
