Provides an interface for creating file system queries and implements BEntryList methods for iterating through the results. More...

Inherits BEntryList.

Public Member Functions
	BQuery ()
	Creates an uninitialized BQuery object.

virtual	~BQuery ()
	Destroys the BQuery object and frees any associated resources.

status_t	Clear ()
	Resets the object to a uninitialized state.

status_t	Fetch ()
	Start fetching entries satisfying the predicate.

Predicate Push
Methods to push data onto the predicate stack. Warning In BeOS R5 these methods returned `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.
status_t	PushAttr (const char *attrName)
	Pushes an attribute name onto the predicate stack.

status_t	PushOp (query_op op)
	Pushes an operator onto the predicate stack.

status_t	PushUInt32 (uint32 value)
	Pushes a `uint32` onto the predicate stack.

status_t	PushInt32 (int32 value)
	Pushes an `int32` onto the predicate stack.

status_t	PushUInt64 (uint64 value)
	Pushes a `uint64` onto the predicate stack.

status_t	PushInt64 (int64 value)
	Pushes an int64 onto the predicate stack.

status_t	PushFloat (float value)
	Pushes a `float` onto the predicate stack.

status_t	PushDouble (double value)
	Pushes a `double` onto the predicate stack.

status_t	PushString (const char *value, bool caseInsensitive=false)
	Pushes a string onto the predicate stack.

status_t	PushDate (const char *date)
	Pushes a date string onto the predicate stack.

Assignment
status_t	SetVolume (const BVolume *volume)
	Assigns volume to the BQuery object.

status_t	SetPredicate (const char *expression)
	Assigns the passed-in predicate expression.

status_t	SetTarget (BMessenger messenger)
	Assigns the target messenger and makes the query live.

Query Information
bool	IsLive () const
	Gets whether the query associated with this object is live.

size_t	PredicateLength ()
	Gets the length of the predicate string.

dev_t	TargetDevice () const
	Gets the device ID identifying the volume of the BQuery object.

Get Predicate
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.
status_t	GetPredicate (char *buffer, size_t length)
	Fills out buffer with the predicate string assigned to the BQuery object.

status_t	GetPredicate (BString *predicate)
	Fills out the passed-in BString object with the predicate string assigned to the BQuery object.

BEntryList Interface
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().
virtual status_t	GetNextEntry (BEntry *entry, bool traverse=false)
	Fills out entry with the next entry traversing symlinks if traverse is `true`.

virtual status_t	GetNextRef (entry_ref *ref)
	Fills out ref with the next entry as an entry_ref.

virtual int32	GetNextDirents (struct dirent *buffer, size_t length, int32 count=INT_MAX)
	Fill out up to count entries into the array of dirent structs pointed to by buffer.

virtual status_t	Rewind ()
	Rewinds the entry list back to the first entry.

virtual int32	CountEntries ()
	Unimplemented.

Public Member Functions inherited from BEntryList
	BEntryList ()
	Creates a BEntryList object.

virtual	~BEntryList ()
	Frees all resources associated with the BEntryList object.

virtual int32	CountEntries ()=0
	Returns the number of entries in the list.

virtual int32	GetNextDirents (struct dirent *direntBuffer, size_t bufferSize, int32 maxEntries=INT_MAX)=0
	Returns the BEntryList's next entries as dirent structures.

virtual status_t	GetNextEntry (BEntry *entry, bool traverse=false)=0
	Returns the BEntryList's next entry as a BEntry.

virtual status_t	GetNextRef (entry_ref *ref)=0
	Returns the BEntryList's next entry as an entry_ref.

virtual status_t	Rewind ()=0
	Rewinds the list pointer to the beginning of the list.

Detailed Description

Provides an interface for creating file system queries and implements BEntryList methods for iterating through the results.

Since: BeOS R3

Constructor & Destructor Documentation

◆ BQuery()

BQuery::BQuery ( )

Creates an uninitialized BQuery object.

See also: SetPredicate()

Since: BeOS R3

◆ ~BQuery()

BQuery::~BQuery ( )

virtual

Destroys the BQuery object and frees any associated resources.

Since: BeOS R3

Member Function Documentation

◆ Clear()

status_t BQuery::Clear ( )

Resets the object to a uninitialized state.

Returns: B_OK

Since: BeOS R3

◆ CountEntries()

int32 BQuery::CountEntries ( )

virtual

Unimplemented.

Returns: B_ERROR.

Since: BeOS R3

Implements BEntryList.

◆ Fetch()

status_t BQuery::Fetch ( )

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.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_INIT	The object predicate or the volume wasn't set.
B_BAD_VALUE	The object predicate was invalid.
B_NOT_ALLOWED	Fetch() already called.

Since: BeOS R3

◆ GetNextDirents()

int32 BQuery::GetNextDirents	(	struct dirent *	buffer,
		size_t	length,
		int32	count = `INT_MAX`
	)

virtual

Fill out up to count entries into the array of dirent structs pointed to by buffer.

Reads as many but no more than count entries, as many entries as remain, or as many entries as will fit into the array at buffer with the given length (in bytes), whichever is smallest.

Parameters

buffer	A pointer to a buffer filled out with dirent structures of the entries.
length	The length of buffer.
count	The maximum number of entries to be read.

Returns: The number of dirent structures stored in the buffer, 0 when there are no more entries to be read, or an error code.

Return values

B_BAD_VALUE	The predicate included unindexed attributes.
B_FILE_ERROR	Fetch() was not previously called on the object.

Since: BeOS R3

Implements BEntryList.

◆ GetNextEntry()

status_t BQuery::GetNextEntry	(	BEntry *	entry,
		bool	traverse = `false`
	)

virtual

Fills out entry with the next entry traversing symlinks if traverse is true.

Parameters

entry	A pointer to a BEntry object initialized with the entry.
traverse	Whether or not to follow symbolic links.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_ENTRY_NOT_FOUND	At end of list.
B_BAD_VALUE	The predicate included unindexed attributes.
B_NOT_ALLOWED	Fetch() was not previously called on the object.

Since: BeOS R3

Implements BEntryList.

◆ GetNextRef()

status_t BQuery::GetNextRef ( entry_ref * ref )

virtual

Fills out ref with the next entry as an entry_ref.

Parameters

ref	A pointer to an entry_ref object filled out with the entry's data.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_ENTRY_NOT_FOUND	At end of list.
B_BAD_VALUE	The predicate included unindexed attributes.
B_NOT_ALLOWED	Fetch() was not previously called on the object.

Since: BeOS R3

Implements BEntryList.

◆ GetPredicate() [1/2]

status_t BQuery::GetPredicate ( BString * predicate )

Fills out the passed-in BString object with the predicate string assigned to the BQuery object.

Parameters

predicate A pointer to a BString object that gets filled out with the predicate string.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_INIT	The predicate of the BQuery object wasn't set.
B_BAD_VALUE	predicate was `NULL`.

Since: Haiku R1

◆ GetPredicate() [2/2]

status_t BQuery::GetPredicate	(	char *	buffer,
		size_t	length
	)

Fills out buffer with the predicate string assigned to the BQuery object.

Parameters

buffer	A pointer to a buffer which the predicate is written to.
length	the size of buffer.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_INIT	The predicate of the BQuery object wasn't set.
B_BAD_VALUE	buffer was `NULL` or too short.

Since: BeOS R3

◆ IsLive()

bool BQuery::IsLive ( ) const

Gets whether the query associated with this object is live.

Returns: true, if the query is live, false otherwise.

See also: SetTarget()

Since: BeOS R3

◆ PredicateLength()

size_t BQuery::PredicateLength ( )

Gets the length of the predicate string.

This method returns the length of the string representation of the predicate (including the terminating NUL) regardless of whether the predicate has been constructed using the predicate stack or set via SetPredicate().

Returns: The length of the predicate string or 0 if an error occurred.

See also: SetPredicate()

Since: BeOS R3

◆ PushAttr()

status_t BQuery::PushAttr ( const char * attrName )

Pushes an attribute name onto the predicate stack.

Parameters

attrName The name of the attribute to push on the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushAttribute() was called after Fetch().

Since: BeOS R3

◆ PushDate()

status_t BQuery::PushDate ( const char * date )

Pushes a date string onto the predicate stack.

The supplied date can be any string understood by parsedate().

Parameters

date	The date string to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushDate() was called after Fetch().

See also: parsedate()

Since: Haiku R1

◆ PushDouble()

status_t BQuery::PushDouble ( double value )

Pushes a double onto the predicate stack.

Parameters

value The double to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushDouble() was called after Fetch().

Since: BeOS R3

◆ PushFloat()

status_t BQuery::PushFloat ( float value )

Pushes a float onto the predicate stack.

Parameters

value The float to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushFloat() was called after Fetch().

Since: BeOS R3

◆ PushInt32()

status_t BQuery::PushInt32 ( int32 value )

Pushes an int32 onto the predicate stack.

Parameters

value The int32 to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushInt32() was called after Fetch().

Since: BeOS R3

◆ PushInt64()

status_t BQuery::PushInt64 ( int64 value )

Pushes an int64 onto the predicate stack.

Parameters

value The int64 to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushInt64() was called after Fetch().

Since: BeOS R3

◆ PushOp()

status_t BQuery::PushOp ( query_op op )

Pushes an operator onto the predicate stack.

Parameters

op	The operator code to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushOp() was called after Fetch().

Since: BeOS R3

◆ PushString()

status_t BQuery::PushString	(	const char *	value,
		bool	caseInsensitive = `false`
	)

Pushes a string onto the predicate stack.

Parameters

value	The string to push onto the stack.
caseInsensitive	Whether or not the case of value should be ignored in the resulting query.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushString() was called after Fetch().

Since: BeOS R3

◆ PushUInt32()

status_t BQuery::PushUInt32 ( uint32 value )

Pushes a uint32 onto the predicate stack.

Parameters

value The uint32 to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushUInt32() was called after Fetch().

Since: BeOS R3

◆ PushUInt64()

status_t BQuery::PushUInt64 ( uint64 value )

Pushes a uint64 onto the predicate stack.

Parameters

value The uint64 to push onto the stack.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	PushUInt64() was called after Fetch().

Since: BeOS R3

◆ Rewind()

status_t BQuery::Rewind ( )

virtual

Rewinds the entry list back to the first entry.

Note: BeOS R5 does not implement this method for BQuery.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_FILE_ERROR	Fetch() was not previously called on the object.

Since: BeOS R3

Implements BEntryList.

◆ SetPredicate()

status_t BQuery::SetPredicate ( const char * expression )

Assigns the passed-in predicate 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.

Parameters

expression The predicate expression to set.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	SetPredicate() was called after Fetch().

Since: BeOS R3

◆ SetTarget()

status_t BQuery::SetTarget ( BMessenger messenger )

Assigns the target 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().

Parameters

messenger The target messenger to set.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NO_MEMORY	Not enough memory.
B_NOT_ALLOWED	SetTarget() was called after Fetch().

Since: BeOS R3

◆ SetVolume()

status_t BQuery::SetVolume ( const BVolume * volume )

Assigns 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.

Parameters

volume The volume to set.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_NOT_ALLOWED	SetVolume() was called after Fetch().

Since: BeOS R3

◆ TargetDevice()

dev_t BQuery::TargetDevice ( ) const

Gets the device ID identifying the volume of the BQuery object.

Returns: The device ID of the volume or B_NO_INIT if the volume wasn't set.

Since: BeOS R3; Haiku R1

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BQuery()

◆ ~BQuery()

Member Function Documentation

◆ Clear()

◆ CountEntries()

◆ Fetch()

◆ GetNextDirents()

◆ GetNextEntry()

◆ GetNextRef()

◆ GetPredicate() [1/2]

◆ GetPredicate() [2/2]

◆ IsLive()

◆ PredicateLength()

◆ PushAttr()

◆ PushDate()

◆ PushDouble()

◆ PushFloat()

◆ PushInt32()

◆ PushInt64()

◆ PushOp()

◆ PushString()

◆ PushUInt32()

◆ PushUInt64()

◆ Rewind()

◆ SetPredicate()

◆ SetTarget()

◆ SetVolume()

◆ TargetDevice()