docs/user/storage/Query.dox

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