Public Member Functions | List of all members
BQuery Class Reference

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. More...
 
virtual ~BQuery ()
 Destroys the BQuery object and frees any associated resources. More...
 
status_t Clear ()
 Resets the object to a uninitialized state. More...
 
status_t Fetch ()
 Start fetching entries satisfying the predicate. More...
 
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. More...
 
status_t PushOp (query_op op)
 Pushes an operator onto the predicate stack. More...
 
status_t PushUInt32 (uint32 value)
 Pushes a uint32 onto the predicate stack. More...
 
status_t PushInt32 (int32 value)
 Pushes an int32 onto the predicate stack. More...
 
status_t PushUInt64 (uint64 value)
 Pushes a uint64 onto the predicate stack. More...
 
status_t PushInt64 (int64 value)
 Pushes an int64 onto the predicate stack. More...
 
status_t PushFloat (float value)
 Pushes a float onto the predicate stack. More...
 
status_t PushDouble (double value)
 Pushes a double onto the predicate stack. More...
 
status_t PushString (const char *value, bool caseInsensitive=false)
 Pushes a string onto the predicate stack. More...
 
status_t PushDate (const char *date)
 Pushes a date string onto the predicate stack. More...
 
Assignment
status_t SetVolume (const BVolume *volume)
 Assigns volume to the BQuery object. More...
 
status_t SetPredicate (const char *expression)
 Assigns the passed-in predicate expression. More...
 
status_t SetTarget (BMessenger messenger)
 Assigns the target messenger and makes the query live. More...
 
Query Information
bool IsLive () const
 Gets whether the query associated with this object is live. More...
 
size_t PredicateLength ()
 Gets the length of the predicate string. More...
 
dev_t TargetDevice () const
 Gets the device ID identifying the volume of the BQuery object. More...
 
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. More...
 
status_t GetPredicate (BString *predicate)
 Fills out the passed-in BString object with the predicate string assigned to the BQuery object. More...
 
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. More...
 
virtual status_t GetNextRef (entry_ref *ref)
 Fills out ref with the next entry as an entry_ref. More...
 
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. More...
 
virtual status_t Rewind ()
 Rewinds the entry list back to the first entry. More...
 
virtual int32 CountEntries ()
 Unimplemented. More...
 
- Public Member Functions inherited from BEntryList
 BEntryList ()
 Creates a BEntryList object. More...
 
virtual ~BEntryList ()
 Frees all resources associated with the BEntryList object. More...
 

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_OKEverything went fine.
B_NO_INITThe object predicate or the volume wasn't set.
B_BAD_VALUEThe object predicate was invalid.
B_NOT_ALLOWEDFetch() 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
bufferA pointer to a buffer filled out with dirent structures of the entries.
lengthThe length of buffer.
countThe 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_VALUEThe predicate included unindexed attributes.
B_FILE_ERRORFetch() 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
entryA pointer to a BEntry object initialized with the entry.
traverseWhether or not to follow symbolic links.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDAt end of list.
B_BAD_VALUEThe predicate included unindexed attributes.
B_NOT_ALLOWEDFetch() 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
refA pointer to an entry_ref object filled out with the entry's data.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDAt end of list.
B_BAD_VALUEThe predicate included unindexed attributes.
B_NOT_ALLOWEDFetch() was not previously called on the object.
Since
BeOS R3

Implements BEntryList.

◆ GetPredicate() [1/2]

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

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

Parameters
bufferA pointer to a buffer which the predicate is written to.
lengththe size of buffer.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_INITThe predicate of the BQuery object wasn't set.
B_BAD_VALUEbuffer was NULL or too short.
Since
BeOS R3

◆ GetPredicate() [2/2]

status_t BQuery::GetPredicate ( BString predicate)

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

Parameters
predicateA pointer to a BString object that gets filled out with the predicate string.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_INITThe predicate of the BQuery object wasn't set.
B_BAD_VALUEpredicate was NULL.
Since
Haiku R1

◆ 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
attrNameThe name of the attribute to push on the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushAttribute() 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
dateThe date string to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushDate() 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
valueThe double to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushDouble() was called after Fetch().
Since
BeOS R3

◆ PushFloat()

status_t BQuery::PushFloat ( float  value)

Pushes a float onto the predicate stack.

Parameters
valueThe float to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushFloat() was called after Fetch().
Since
BeOS R3

◆ PushInt32()

status_t BQuery::PushInt32 ( int32  value)

Pushes an int32 onto the predicate stack.

Parameters
valueThe int32 to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushInt32() was called after Fetch().
Since
BeOS R3

◆ PushInt64()

status_t BQuery::PushInt64 ( int64  value)

Pushes an int64 onto the predicate stack.

Parameters
valueThe int64 to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushInt64() was called after Fetch().
Since
BeOS R3

◆ PushOp()

status_t BQuery::PushOp ( query_op  op)

Pushes an operator onto the predicate stack.

Parameters
opThe operator code to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushOp() 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
valueThe string to push onto the stack.
caseInsensitiveWhether or not the case of value should be ignored in the resulting query.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushString() was called after Fetch().
Since
BeOS R3

◆ PushUInt32()

status_t BQuery::PushUInt32 ( uint32  value)

Pushes a uint32 onto the predicate stack.

Parameters
valueThe uint32 to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushUInt32() was called after Fetch().
Since
BeOS R3

◆ PushUInt64()

status_t BQuery::PushUInt64 ( uint64  value)

Pushes a uint64 onto the predicate stack.

Parameters
valueThe uint64 to push onto the stack.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDPushUInt64() 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_OKEverything went fine.
B_FILE_ERRORFetch() 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
expressionThe predicate expression to set.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDSetPredicate() 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
messengerThe target messenger to set.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NO_MEMORYNot enough memory.
B_NOT_ALLOWEDSetTarget() 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
volumeThe volume to set.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NOT_ALLOWEDSetVolume() 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