1/* 2 * Copyright 2002-2013 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Tyler Dauwalder 7 * Axel Dörfler, axeld@pinc-software.de 8 * John Scipione, jscipione@gmail.com 9 * Ingo Weinhold, bonefish@users.sf.net 10 * 11 * Corresponds to: 12 * headers/os/storage/Query.h hrev45283 13 * src/kits/storage/Query.cpp hrev45283 14 */ 15 16 17/*! 18 \file Query.h 19 \ingroup storage 20 \ingroup libbe 21 \brief Provides the BQuery class. 22*/ 23 24 25/*! 26 \class BQuery 27 \ingroup storage 28 \ingroup libbe 29 \brief Provides an interface for creating file system queries and 30 implements BEntryList methods for iterating through the results. 31*/ 32 33 34/*! 35 \fn BQuery::BQuery() 36 \brief Creates an uninitialized BQuery object. 37 38 \see SetPredicate() 39*/ 40 41 42/*! 43 \fn BQuery::~BQuery() 44 \brief Destroys the BQuery object and frees any associated resources. 45*/ 46 47 48/*! 49 \fn status_t BQuery::Clear() 50 \brief Resets the object to a uninitialized state. 51 52 \return \c B_OK 53*/ 54 55 56/*! 57 \fn status_t BQuery::Fetch() 58 \brief Start fetching entries satisfying the predicate. 59 60 After Fetch() has been called GetNextEntry(), GetNextRef() and 61 GetNextDirents() can be used to retrieve the entities. Live query updates 62 may be sent immediately after this method has been called. 63 64 Fetch() fails if it has already been called. To reuse the BQuery object it 65 must first be reset with the Clear() method. 66 67 \return A status code. 68 \retval B_OK Everything went fine. 69 \retval B_NO_INIT The object predicate or the volume wasn't set. 70 \retval B_BAD_VALUE The object predicate was invalid. 71 \retval B_NOT_ALLOWED Fetch() already called. 72*/ 73 74 75/*! 76 \name Predicate push methods 77 78 Methods to push data onto the predicate stack. 79 80 \warning In BeOS R5 these methods returned \c void. That is checking the 81 return value will render your code source and binary 82 incompatible! Calling PushXYZ() after a Fetch() does change the 83 predicate on R5, but it doesn't affect the active query and the 84 newly created predicate can not even be used for the next query, 85 since in order to be able to reuse the BQuery object for another 86 query, Clear() has to be called and Clear() also deletes the 87 predicate. 88*/ 89 90 91//! @{ 92 93 94/*! 95 \fn status_t BQuery::PushAttr(const char* attrName) 96 \brief Pushes an attribute name onto the predicate stack. 97 98 \param attrName The name of the attribute to push on the stack. 99 100 \return A status code. 101 \retval B_OK Everything went fine. 102 \retval B_NO_MEMORY Not enough memory. 103 \retval B_NOT_ALLOWED PushAttribute() was called after Fetch(). 104*/ 105 106 107/*! 108 \fn status_t BQuery::PushOp(query_op op) 109 \brief Pushes an operator onto the predicate stack. 110 111 \param op The operator code to push onto the stack. 112 113 \return A status code. 114 \retval B_OK Everything went fine. 115 \retval B_NO_MEMORY Not enough memory. 116 \retval B_NOT_ALLOWED PushOp() was called after Fetch(). 117*/ 118 119 120/*! 121 \fn status_t BQuery::PushUInt32(uint32 value) 122 \brief Pushes a \c uint32 onto the predicate stack. 123 124 \param value The \c uint32 to push onto the stack. 125 126 \return A status code. 127 \retval B_OK Everything went fine. 128 \retval B_NO_MEMORY Not enough memory. 129 \retval B_NOT_ALLOWED PushUInt32() was called after Fetch(). 130*/ 131 132 133/*! 134 \fn status_t BQuery::PushInt32(int32 value) 135 \brief Pushes an \c int32 onto the predicate stack. 136 137 \param value The \c int32 to push onto the stack. 138 139 \return A status code. 140 \retval B_OK Everything went fine. 141 \retval B_NO_MEMORY Not enough memory. 142 \retval B_NOT_ALLOWED PushInt32() was called after Fetch(). 143*/ 144 145 146/*! 147 \fn status_t BQuery::PushUInt64(uint64 value) 148 \brief Pushes a \c uint64 onto the predicate stack. 149 150 \param value The \c uint64 to push onto the stack. 151 152 \return A status code. 153 \retval B_OK Everything went fine. 154 \retval B_NO_MEMORY Not enough memory. 155 \retval B_NOT_ALLOWED PushUInt64() was called after Fetch(). 156*/ 157 158 159/*! 160 \fn status_t BQuery::PushInt64(int64 value) 161 \brief Pushes an int64 onto the predicate stack. 162 163 \param value The \c int64 to push onto the stack. 164 165 \return A status code. 166 \retval B_OK Everything went fine. 167 \retval B_NO_MEMORY Not enough memory. 168 \retval B_NOT_ALLOWED PushInt64() was called after Fetch(). 169*/ 170 171 172/*! 173 \fn status_t BQuery::PushFloat(float value) 174 \brief Pushes a \c float onto the predicate stack. 175 176 \param value The \c float to push onto the stack. 177 178 \return A status code. 179 \retval B_OK Everything went fine. 180 \retval B_NO_MEMORY Not enough memory. 181 \retval B_NOT_ALLOWED PushFloat() was called after Fetch(). 182*/ 183 184 185/*! 186 \fn status_t BQuery::PushDouble(double value) 187 \brief Pushes a \c double onto the predicate stack. 188 189 \param value The \c double to push onto the stack. 190 191 \return A status code. 192 \retval B_OK Everything went fine. 193 \retval B_NO_MEMORY Not enough memory. 194 \retval B_NOT_ALLOWED PushDouble() was called after Fetch(). 195*/ 196 197 198/*! 199 \fn status_t BQuery::PushString(const char* value, bool caseInsensitive) 200 \brief Pushes a string onto the predicate stack. 201 202 \param value The string to push onto the stack. 203 \param caseInsensitive Whether or not the case of \a value should be 204 ignored in the resulting query. 205 206 \return A status code. 207 \retval B_OK Everything went fine. 208 \retval B_NO_MEMORY Not enough memory. 209 \retval B_NOT_ALLOWED PushString() was called after Fetch(). 210*/ 211 212 213/*! 214 \fn status_t BQuery::PushDate(const char* date) 215 \brief Pushes a date string onto the predicate stack. 216 217 The supplied date can be any string understood by parsedate(). 218 219 \param date The date string to push onto the stack. 220 221 \return A status code. 222 \retval B_OK Everything went fine. 223 \retval B_NO_MEMORY Not enough memory. 224 \retval B_NOT_ALLOWED PushDate() was called after Fetch(). 225 226 \see parsedate() 227*/ 228 229 230//! @} 231 232 233/*! 234 \name Assignment methods 235*/ 236 237 238//! @{ 239 240 241/*! 242 \fn status_t BQuery::SetVolume(const BVolume* volume) 243 \brief Assigns \a volume to the BQuery object. 244 245 A query may only be assigned to one volume. 246 247 The method fails if called after Fetch(). To reuse the BQuery object it 248 must first be reset using the Clear() method. 249 250 \param volume The \a volume to set. 251 252 \return A status code. 253 \retval B_OK Everything went fine. 254 \retval B_NOT_ALLOWED SetVolume() was called after Fetch(). 255*/ 256 257 258/*! 259 \fn status_t BQuery::SetPredicate(const char* expression) 260 \brief Assigns the passed-in predicate \a expression. 261 262 A predicate can be set either using this method or by constructing one on 263 the predicate stack, however, the two methods can not be mixed. The 264 predicate stack takes precedence over this method. 265 266 The method fails if called after Fetch(). To reuse the BQuery object it 267 must first be reset using the Clear() method. 268 269 \param expression The predicate \a expression to set. 270 271 \return A status code. 272 \retval B_OK Everything went fine. 273 \retval B_NO_MEMORY Not enough memory. 274 \retval B_NOT_ALLOWED SetPredicate() was called after Fetch(). 275*/ 276 277 278/*! 279 \fn status_t BQuery::SetTarget(BMessenger messenger) 280 \brief Assigns the target \a messenger and makes the query live. 281 282 The query update messages are sent to the specified target. They might 283 roll in immediately after calling Fetch(). 284 285 This methods fails if called after Fetch(). To reuse the BQuery object it 286 must first be reset via Clear(). 287 288 \param messenger The target \a messenger to set. 289 290 \return A status code. 291 \retval B_OK Everything went fine. 292 \retval B_NO_MEMORY Not enough memory. 293 \retval B_NOT_ALLOWED SetTarget() was called after Fetch(). 294*/ 295 296 297//! @} 298 299 300/*! 301 \name Query information methods 302*/ 303 304 305//! @{ 306 307 308/*! 309 \fn bool BQuery::IsLive() const 310 \brief Gets whether the query associated with this object is live. 311 \return \c true, if the query is live, \c false otherwise. 312*/ 313 314 315/*! 316 \fn dev_t BQuery::TargetDevice() const 317 \brief Gets the device ID identifying the volume of the BQuery object. 318 319 \return The device ID of the volume or \c B_NO_INIT if the volume wasn't 320 set. 321*/ 322 323 324/*! 325 \fn size_t BQuery::PredicateLength() 326 \brief Gets the length of the predicate string. 327 328 This method returns the length of the string representation of the 329 predicate (including the terminating \c NUL) regardless of whether the 330 predicate has been constructed using the predicate stack or set via 331 SetPredicate(). 332 333 \return The length of the predicate string or 0 if an error occurred. 334*/ 335 336 337//! @} 338 339 340/*! 341 \name Get predicate methods 342 343 These methods fetch a string representation regardless of whether the 344 predicate has been constructed using the predicate stack or via 345 SetPredicate(). 346 347 \note These methods cause the predicate stack to be evaluated and cleared. 348 You can't interleave calls to push data and GetPredicate() methods. 349*/ 350 351 352//! @{ 353 354 355/*! 356 \fn status_t BQuery::GetPredicate(char* buffer, size_t length) 357 \brief Fills out \a buffer with the predicate string assigned to the 358 BQuery object. 359 360 \param buffer A pointer to a buffer which the predicate is written to. 361 \param length the size of \a buffer. 362 363 \return A status code. 364 \retval B_OK Everything went fine. 365 \retval B_NO_INIT The predicate of the BQuery object wasn't set. 366 \retval B_BAD_VALUE \a buffer was \c NULL or too short. 367*/ 368 369 370/*! 371 \fn status_t BQuery::GetPredicate(BString* predicate) 372 \brief Fills out the passed-in BString object with the predicate string 373 assigned to the BQuery object. 374 375 \param predicate A pointer to a BString object that gets filled out with 376 the predicate string. 377 378 \return A status code. 379 \retval B_OK Everything went fine. 380 \retval B_NO_INIT The predicate of the BQuery object wasn't set. 381 \retval B_BAD_VALUE \a predicate was \c NULL. 382*/ 383 384 385//! @} 386 387 388/*! 389 \name BEntryList interface methods 390 391 These methods are used to traverse the results of a query as a BEntryList. 392 393 \note The iterator used by these methods is the same one used by 394 GetNextRef() and GetNextDirents(). 395*/ 396 397 398//! @{ 399 400 401/*! 402 \fn status_t BQuery::GetNextEntry(BEntry* entry, bool traverse) 403 \brief Fills out \a entry with the next entry traversing symlinks if 404 \a traverse is \c true. 405 406 \param entry A pointer to a BEntry object initialized with the entry. 407 \param traverse Whether or not to follow symbolic links. 408 409 \return A status code. 410 \retval B_OK Everything went fine. 411 \retval B_ENTRY_NOT_FOUND At end of list. 412 \retval B_BAD_VALUE The predicate included unindexed attributes. 413 \retval B_NOT_ALLOWED Fetch() was not previously called on the object. 414*/ 415 416 417/*! 418 \fn status_t BQuery::GetNextRef(entry_ref* ref) 419 \brief Fills out \a ref with the next entry as an entry_ref. 420 421 \param ref A pointer to an entry_ref object filled out with the 422 entry's data. 423 424 \return A status code. 425 \retval B_OK Everything went fine. 426 \retval B_ENTRY_NOT_FOUND At end of list. 427 \retval B_BAD_VALUE The predicate included unindexed attributes. 428 \retval B_NOT_ALLOWED Fetch() was not previously called on the object. 429*/ 430 431 432/*! 433 \fn int32 BQuery::GetNextDirents(struct dirent* buffer, size_t length, 434 int32 count) 435 \brief Fill out up to \a count entries into the array of dirent structs 436 pointed to by \a buffer. 437 438 Reads as many but no more than \a count entries, as many entries as 439 remain, or as many entries as will fit into the array at \a buffer with 440 the given \a length (in bytes), whichever is smallest. 441 442 \param buffer A pointer to a buffer filled out with dirent structures of 443 the entries. 444 \param length The length of \a buffer. 445 \param count The maximum number of entries to be read. 446 447 \return The number of dirent structures stored in the buffer, 0 when there 448 are no more entries to be read, or an error code. 449 \retval B_BAD_VALUE The predicate included unindexed attributes. 450 \retval B_FILE_ERROR Fetch() was not previously called on the object. 451*/ 452 453 454/*! 455 \fn status_t BQuery::Rewind() 456 \brief Rewinds the entry list back to the first entry. 457 458 \note BeOS R5 does not implement this method for BQuery. 459 460 \return A status code. 461 \retval B_OK Everything went fine. 462 \retval B_FILE_ERROR Fetch() was not previously called on the object. 463*/ 464 465 466/*! 467 \fn int32 BQuery::CountEntries() 468 \brief Unimplemented. 469 470 \return \c B_ERROR. 471*/ 472 473 474//! @} 475 476 477/// private methods, won't show up in docs 478 479 480/*! 481 \fn bool BQuery::_HasFetched() const 482 \brief Gets whether Fetch() has already been called on this object. 483 484 \return \c true, if Fetch() was already called, \c false otherwise. 485*/ 486 487 488/*! 489 \fn status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError) 490 \brief Pushes a node onto the predicate stack. 491 492 If the stack has not been allocate until this time, this method does 493 allocate it. 494 495 If the supplied node is \c NULL, it is assumed that there was not enough 496 memory to allocate the node and thus \c B_NO_MEMORY is returned. 497 498 In case the method fails, the caller retains the ownership of the supplied 499 node and thus is responsible for deleting it, if \a deleteOnError is 500 \c false. If it is \c true, the node is deleted, if an error occurs. 501 502 \param node The node to push. 503 \param deleteOnError Whether or not to delete the node if an error occurs. 504 505 \return A status code. 506 \retval B_OK Everything went fine. 507 \retval B_NO_MEMORY \a node was \c NULL or there was insufficient memory to 508 allocate the predicate stack or push the node. 509 \retval B_NOT_ALLOWED _PushNode() was called after Fetch(). 510*/ 511 512 513/*! 514 \fn status_t BQuery::_SetPredicate(const char* expression) 515 \brief Helper method to set the predicate. 516 517 Does not check whether Fetch() has already been invoked. 518 519 \param expression The predicate string to set. 520 521 \return A status code. 522 \retval B_OK Everything went fine. 523 \retval B_NO_MEMORY There was insufficient memory to store the predicate. 524*/ 525 526 527/*! 528 \fn status_t BQuery::_EvaluateStack() 529 Evaluates the predicate stack. 530 531 The method does nothing (and returns \c B_OK), if the stack is \c NULL. 532 If the stack is not \c null and Fetch() has already been called, this 533 method fails. 534 535 \return A status code. 536 \retval B_OK Everything went fine. 537 \retval B_NO_MEMORY There was insufficient memory. 538 \retval B_NOT_ALLOWED _EvaluateStack() was called after Fetch(). 539*/ 540 541 542/*! 543 \fn void BQuery::_ParseDates(BString& parsedPredicate) 544 \brief Fills out \a parsedPredicate with a parsed predicate string. 545 546 \param parsedPredicate The predicate string to fill out. 547*/ 548