docs/user/support/DataIO.dox

   1 /*
   2  * Copyright 2007-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Stefano Ceccherini, burton666@libero.it
   7  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   8  *              John Scipione, jscipione@gmail.com
   9  *
  10  * Corresponds to:
  11  *              headers/os/support/DataIO.h     hrev47418
  12  *              src/kits/support/DataIO.cpp     hrev47418
  13  */
  14
  15
  16 /*!
  17         \file DataIO.h
  18         \ingroup support
  19         \ingroup libbe
  20         \brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO
  21                and BMemoryIO classes.
  22
  23         Pure virtual BDataIO and BPositioIO classes provide the protocol for
  24         Read(), Write(), and Seek().
  25
  26         BMallocIO and BMemoryIO classes implement the protocol, as does BFile in
  27         the Storage Kit.
  28 */
  29
  30
  31 ///// BDataIO /////
  32
  33
  34 /*!
  35         \class BDataIO
  36         \ingroup support
  37         \ingroup libbe
  38         \brief Abstract interface for objects that provide read and write access to
  39                data.
  40
  41         The interface provided by this class applies to objects or data that are
  42         limited to reading and writing data. Classes derived from this class should
  43         re-implement the Read() or the Write() method from this class or both.
  44
  45         Candidates of types of data or objects that should be derived from this class
  46         are probably broadcasting media streams (which don't support reading at a
  47         certain point in the data) or network streams that output data continuously.
  48         Objects and data that support more advanced operations like seeking or
  49         reading at writing at defined positions should derive their classes from
  50         BPositionIO, which inherits this class.
  51
  52         \since BeOS R3
  53 */
  54
  55
  56 /*!
  57         \fn BDataIO::BDataIO()
  58         \brief This constructor does nothing.
  59
  60         \since BeOS R3
  61 */
  62
  63
  64 /*!
  65         \fn BDataIO::~BDataIO()
  66         \brief This destructor does nothing.
  67
  68         \since BeOS R3
  69 */
  70
  71
  72 /*!
  73         \fn virtual ssize_t BDataIO::Read(void* buffer, size_t size)
  74         \brief Reads data from the object into a buffer.
  75
  76         Your implementation should copy data into \c buffer, with the maximum size
  77         of \c size.
  78
  79         The default implementation is a no-op returning \c B_NOT_SUPPORTED.
  80
  81         \return You should return the amount of bytes actually read, or an error
  82                 code in case of failure.
  83
  84         \since BeOS R3
  85 */
  86
  87
  88 /*!
  89         \fn virtual ssize_t BDataIO::Write(const void* buffer, size_t size)
  90         \brief Writes data from a buffer to the object.
  91
  92         Your implementation should copy data from \c buffer, with the maximum size
  93         of \c size.
  94
  95         The default implementation is a no-op returning \c B_NOT_SUPPORTED.
  96
  97         \return You should return the amount of bytes actually written, or an error
  98                 code in case of failure.
  99
 100         \since BeOS R3
 101 */
 102
 103
 104 /*!
 105         \fn virtual status_t BDataIO::Flush()
 106         \brief Writes pending data to underlying storage.
 107
 108         This method is relevant for BDataIO implementations that buffer data passed
 109         to Write(). The Flush() implementation should make sure that all such data
 110         are written to the underlying storage.
 111
 112         The default implementation is a no-op returning \c B_OK.
 113
 114         \return An error code indicating whether flushing the buffered data
 115                 succeeded.
 116
 117         \since Haiku R1
 118 */
 119
 120
 121 /*!
 122         \fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size, size_t* _bytesRead)
 123         \brief Reads an exact amount of data from the object into a buffer.
 124
 125         This is a convenience wrapper method for Read() for code that expects the
 126         exact number of bytes requested to be read. This method calls Read() in a
 127         loop to read the data. It fails when Read() returns an error or fails to
 128         read any more data (i.e. returns 0).
 129
 130         \param buffer Pointer to pre-allocated storage of at least \a size bytes
 131                into which the data shall be read. Won't be dereferenced, when
 132                \a size is 0.
 133         \param size The number of bytes to be read.
 134         \param _bytesRead Optional pointer to a pre-allocated size_t into which the
 135                number of bytes actually read will be written. When the method
 136                returns \c B_OK this will always be \a size. Can be \c NULL.
 137
 138         \return An error code indicating whether or not the method succeeded.
 139         \retval B_OK All data have been read.
 140         \retval B_PARTIAL_READ Read() didn't fail, but couldn't provide as many
 141                 bytes as requested.
 142
 143         \since Haiku R1
 144 */
 145
 146
 147 /*!
 148         \fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size,
 149                 size_t* _bytesWritten)
 150         \brief Writes an exact amount of data from a buffer to the object.
 151
 152         This is a convenience wrapper method for Write() for code that expects the
 153         exact number of bytes given to be written. This method calls Write() in a
 154         loop to write the data. It fails when Write() returns an error or fails to
 155         write any more data (i.e. returns 0).
 156
 157         \param buffer Pointer to a buffer of at least \a size bytes containing the
 158                data to be written. Won't be dereferenced, when \a size is 0.
 159         \param size The number of bytes to be written.
 160         \param _bytesWritten Optional pointer to a pre-allocated size_t into which
 161                the number of bytes actually written will be written. When the
 162                method returns \c B_OK this will always be \a size. Can be \c NULL.
 163
 164         \return An error code indicated whether the method succeeded.
 165         \retval B_OK All data have been written.
 166         \retval B_PARTIAL_READ Write() didn't fail, but couldn't write as many
 167                 bytes as provided.
 168
 169         \since Haiku R1
 170 */
 171
 172
 173 //////////// BPositionIO
 174
 175
 176 /*!
 177         \class BPositionIO
 178         \ingroup support
 179         \ingroup libbe
 180         \brief Abstract interface that provides advanced read, write and seek access
 181                to data.
 182
 183         The interface of this object applies to objects or data that allows
 184         position-aware reading and writing of data. Classes that derive from this
 185         class should at least re-implement ReadAt(), WriteAt(), Seek(),
 186         Position(), SetSize() and GetSize() methods.
 187
 188         A good example of a form of data that can derive from this object, are
 189         files. The BFile class derives from BPositionIO and provides this
 190         interface to files. If your object or data only supports linear reading
 191         and writing, consider deriving from the base-class BDataIO.
 192
 193         A final note, from BDataIO this class inherits Read() and Write(). The
 194         default implementation is to read or write the data at the current
 195         position indicated by Position(). Re-implement the methods if you require
 196         a different behavior.
 197
 198         \since Haiku R1
 199 */
 200
 201
 202 /*!
 203         \fn BPositionIO::BPositionIO()
 204         \brief This constructor does nothing.
 205
 206         \since Haiku R1
 207 */
 208
 209
 210 /*!
 211         \fn virtual BPositionIO::~BPositionIO()
 212         \brief This destructor does nothing.
 213
 214         \since Haiku R1
 215 */
 216
 217
 218 /*!
 219         \fn virtual ssize_t BPositionIO::Read(void* buffer, size_t size)
 220         \brief Read data from current position.
 221
 222         This method is derived from BDataIO. The default implementation reads data
 223         from the current position of the cursor, pointed at by Position(). If you
 224         require different behaviour, please look at BDataIO::Read() for what is
 225         expected of this method.
 226
 227         \since BeOS R3
 228 */
 229
 230
 231 /*!
 232         \fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
 233         \brief Write data to the current position.
 234
 235         This method is derived from BDataIO. The default implementation writes data
 236         to the current position of the cursor, pointed at by Position(). If you
 237         require different behaviour, please look at BDataIO::Write() for what is
 238         expected of this method.
 239
 240         \since BeOS R3
 241 */
 242
 243
 244 /*!
 245         \fn virtual ssize_t BPositionIO::ReadAt(off_t position, void* buffer,
 246                 size_t size) = 0
 247         \brief Pure virtual to read data from a certain position.
 248
 249         Your implementation should copy data from the position indicated by
 250         \a position into the \a buffer with the maximum size of \a size.
 251
 252         \return The amount of bytes actually read, or an error code.
 253
 254         \since BeOS R3
 255 */
 256
 257
 258 /*!
 259         \fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer,
 260                 size_t size) = 0
 261         \brief Pure virtual to write data to a certain position.
 262
 263         Your implementation should copy data from \a buffer to the position indicated
 264         by \a buffer with the maximum size of \a size.
 265
 266         \return The amount of bytes actually written, or an error code.
 267
 268         \since BeOS R3
 269 */
 270
 271
 272 /*!
 273         \fn virtual status_t BPositionIO::ReadAtExactly(off_t position, void* buffer, size_t size, size_t* _bytesRead)
 274         \brief Reads an exact amount of data from the object at the specified
 275                 position into a buffer.
 276
 277         This is a convenience wrapper method for ReadAt() for code that expects the
 278         exact number of bytes requested to be read. This method calls ReadAt() in a
 279         loop to read the data. It fails when ReadAt() returns an error or fails to
 280         read any more data (i.e. returns 0).
 281
 282         \param position The object position at which to read the data.
 283         \param buffer Pointer to pre-allocated storage of at least \a size bytes
 284                into which the data shall be read. Won't be dereferenced, when
 285                \a size is 0.
 286         \param size The number of bytes to be read.
 287         \param _bytesRead Optional pointer to a pre-allocated size_t into which the
 288                number of bytes actually read will be written. When the method
 289                returns \c B_OK this will always be \a size. Can be \c NULL.
 290
 291         \return An error code indicating whether or not the method succeeded.
 292         \retval B_OK All data have been read.
 293         \retval B_PARTIAL_READ ReadAt() didn't fail, but couldn't provide as many
 294                 bytes as requested.
 295
 296         \since Haiku R1
 297 */
 298
 299
 300 /*!
 301         \fn virtual status_t BPositionIO::WriteAtExactly(off_t position, const void* buffer, size_t size,
 302                 size_t* _bytesWritten)
 303         \brief Writes an exact amount of data from a buffer to the object at the
 304                 specified position.
 305
 306         This is a convenience wrapper method for WriteAt() for code that expects the
 307         exact number of bytes given to be written. This method calls WriteAt() in a
 308         loop to write the data. It fails when WriteAt() returns an error or fails to
 309         write any more data (i.e. returns 0).
 310
 311         \param position The object position at which to write the data.
 312         \param buffer Pointer to a buffer of at least \a size bytes containing the
 313                data to be written. Won't be dereferenced, when \a size is 0.
 314         \param size The number of bytes to be written.
 315         \param _bytesWritten Optional pointer to a pre-allocated size_t into which
 316                the number of bytes actually written will be written. When the
 317                method returns \c B_OK this will always be \a size. Can be \c NULL.
 318
 319         \return An error code indicated whether the method succeeded.
 320         \retval B_OK All data have been written.
 321         \retval B_PARTIAL_READ WriteAt() didn't fail, but couldn't write as many
 322                 bytes as provided.
 323
 324         \since Haiku R1
 325 */
 326
 327
 328 /*!
 329         \fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
 330         \brief Pure virtual to move the cursor to a certain position.
 331
 332         Your implementation should move the position of the cursor to the provided
 333         point. What this actually means, depends on your object or data.
 334
 335         \param position An integer that defines a position.
 336         \param seekMode You will get one of the following values:
 337                - \c SEEK_SET Set the cursor to the position indicated by
 338                  \c position.
 339                - \c SEEK_END Set the cursor to the end of the buffer, and go
 340                  \c position beyond that.
 341                - \c SEEK_CUR Set the cursor the the current position plus
 342                  \c position.
 343         \return The new position.
 344
 345         \since BeOS R3
 346 */
 347
 348
 349 /*!
 350         \fn virtual off_t BPositionIO::Position() const = 0
 351         \brief Pure virtual to return the current position of the cursor.
 352
 353         \return Your implementation should return the current position of the cursor.
 354
 355         \since BeOS R3
 356 */
 357
 358
 359 /*!
 360         \fn virtual status_t BPositionIO::SetSize(off_t size)
 361         \brief Set the size of the object or data.
 362
 363         The default implementation returns \c B_ERROR. If your object or data allows
 364         the size to be changed, reimplement this method.
 365
 366         \return Return \c B_OK if everything succeeded, else return the appropriate
 367                 error code.
 368
 369         \since BeOS R3
 370 */
 371
 372
 373 /*!
 374         \fn virtual status_t BPositionIO::GetSize(off_t* size) const
 375         \brief Get the size of the object or data.
 376
 377         The default implementation uses Seek() with the \c SEEK_END flag to
 378         determine the size of the buffer. If your data or object has a different way
 379         of determining size, reimplement this method.
 380
 381         Please check that NULL is not passed into \c size if you reimplement it in
 382         your class.
 383
 384         \param[out] size The size of the object is put into this parameter.
 385
 386         \return This method returns \c B_OK on success or an error code on error.
 387
 388         \see SetSize()
 389         \see Seek()
 390
 391         \since BeOS R3
 392 */
 393
 394
 395 //////////// BMemoryIO
 396
 397
 398 /*!
 399         \class BMemoryIO
 400         \ingroup support
 401         \ingroup libbe
 402         \brief A BPositionIO derived class that works on memory buffers.
 403
 404         This class is used if you require access that confirms to the BPositionIO
 405         interface on memory buffers that you created. If you would like to use that
 406         interface on new buffers, have a look at BMallocIO.
 407
 408         This class is particularly useful if you would like to use a class or method
 409         that are written to make use of the BPositionIO interface. It might also
 410         be used for 'secure' reading and writing from buffers, since this class
 411         automatically checks the bounds of anything you might want to do.
 412
 413         This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
 414         Position() interface from BPositionIO.
 415
 416         \since BeOS R3
 417 */
 418
 419
 420 /*!
 421         \fn BMemoryIO::BMemoryIO(void *data, size_t length)
 422         \brief Create a read/write object.
 423
 424         \param data A pointer to the buffer to adopt.
 425         \param length The size of the buffer.
 426
 427         \see BMemoryIO(const void *buffer, size_t length) for a read-only
 428          implementation.
 429
 430         \since BeOS R3
 431 */
 432
 433
 434 /*!
 435         \fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
 436         \brief Create a read-only object.
 437
 438         \param buffer A pointer to the \c const (read-only) buffer to adopt.
 439         \param length The size of the buffer.
 440
 441         \see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
 442
 443         \since BeOS R3
 444 */
 445
 446
 447 /*!
 448         \fn BMemoryIO::~BMemoryIO()
 449         \brief The destructor does nothing.
 450
 451         \since BeOS R3
 452 */
 453
 454
 455 /*!
 456         \fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
 457         \brief Read from a given position.
 458
 459         \param[in] pos The offset where to start reading data.
 460         \param[out] buffer The buffer to copy the read bytes into.
 461         \param[in] size The size of the \a buffer.
 462
 463         \return The amount of read bytes or an error code.
 464         \retval B_BAD_VALUE The position is less than zero or the buffer given on
 465                 construction is invalid.
 466
 467         \since BeOS R3
 468 */
 469
 470
 471 /*!
 472         \fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
 473         \brief Write at a given position.
 474
 475         \param pos The offset to write to.
 476         \param buffer The buffer to copy the bytes from.
 477         \param size The number of bytes to write.
 478
 479         \return The amount of bytes written or an error code.
 480         \retval B_NOT_ALLOWED The object is constructed as a read-only object.
 481         \retval B_BAD_VALUE The position is less than zero or the buffer given on
 482                 construction is invalid.
 483
 484         \since BeOS R3
 485 */
 486
 487
 488 /*!
 489         \fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
 490         \brief Move the cursor to a given position.
 491
 492         \param position The position to move the cursor to.
 493         \param seek_mode The mode determines where the cursor is placed.
 494                Possibilities include:
 495                - \c SEEK_SET The cursor is set to \a position.
 496                - \c SEEK_CUR The \a position is added to the current position of
 497                  the cursor.
 498                - \c SEEK_END The cursor is put at the end of the data, plus
 499                  \a position added to it.
 500
 501         \return The new position.
 502
 503         \since BeOS R3
 504 */
 505
 506
 507 /*!
 508         \fn off_t BMemoryIO::Position() const
 509         \brief Return the current position.
 510
 511         \return The current position as an off_t.
 512
 513         \since BeOS R3
 514 */
 515
 516
 517 /*!
 518         \fn status_t BMemoryIO::SetSize(off_t size)
 519         \brief Resize the buffer.
 520
 521         This method does not actually resize the buffer. If the new size is greater
 522         than the size of the buffer, resizing will fail. It will only succeed if the
 523         new size is less than the size of the buffer. The buffer itself will not be
 524         resized though.
 525
 526         This method might be useful in some cases. If the buffer is larger than the
 527         data it holds, changing the size will enable you to use the Seek() method
 528         with the flag \c SEEK_END and not get an error if you read or write from
 529         that position, since you actually have a buffer at the end.
 530
 531         \retval B_OK The buffer is resized.
 532         \retval B_NOT_ALLOWED The buffer is read-only.
 533         \retval B_ERROR The \c size is larger than the size of the buffer.
 534
 535         \since BeOS R3
 536 */
 537
 538
 539 //////////// BMallocIO
 540
 541
 542 /*!
 543         \class BMallocIO
 544         \ingroup support
 545         \ingroup libbe
 546         \brief A BPositionIO derived class that creates a memory buffer.
 547
 548         This class creates a memory buffer and provides a BPositionIO interface to
 549         work on it. The memory buffer grows and shrinks automatically.
 550         This is especially useful if you want to use a method or function that
 551         works on an object derived from BPositionIO and you want to do something with
 552         the resulting data, or it could be useful if you want to read and write to
 553         memory in a safe way, since this class has boundary checking.
 554
 555         BMallocIO allocates a buffer based on a certain block size. This provides a
 556         mechanism that will prevent it from needing to allocate new memory too often.
 557         The default block size is 256 bytes, you can change it with SetBlockSize(). If
 558         you are sure you are going to use a bigger buffer, change the block size so
 559         that you won't have to allocate more memory too often, especially if you use
 560         this class in performance-critical code.
 561
 562         If you require a BPositionIO derived object that works on buffers you
 563         provide, have a look at BMemoryIO.
 564
 565         \since BeOS R3
 566 */
 567
 568
 569 /*!
 570         \fn BMallocIO::BMallocIO()
 571         \brief Create a new memory buffer with block size 256.
 572
 573         \see SetBlockSize()
 574
 575         \since BeOS R3
 576 */
 577
 578
 579 /*!
 580         \fn BMallocIO::~BMallocIO()
 581         \brief Destroy the object and free the internal buffer.
 582
 583         \since BeOS R3
 584 */
 585
 586
 587 /*!
 588         \fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
 589         \brief Read data at a certain position.
 590
 591         \param[in] pos Offset into the data where to read from.
 592         \param[out] buffer The buffer to copy the read bytes in.
 593         \param [in] size Size of the buffer.
 594
 595         \return The number of read bytes, or \c B_BAD_VALUE if
 596                     the provided \a buffer is invalid.
 597
 598         \since BeOS R3
 599 */
 600
 601
 602 /*!
 603         \fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
 604         \brief Write data to a certain position.
 605
 606         \param pos Offset into the data where to write to.
 607         \param buffer The buffer to copy from.
 608         \param size The size of the buffer.
 609
 610         \return The number of bytes written or \c B_BAD_VALUE if the provided.
 611                 \a buffer is invalid.
 612
 613         \since BeOS R3
 614 */
 615
 616
 617 /*!
 618         \fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
 619         \brief Move the cursor to a given position.
 620
 621         \param position The position to move the cursor to.
 622         \param seekMode The mode determines where the cursor is placed. Possibilities:
 623                - \c SEEK_SET The cursor is set to \a position.
 624                - \c SEEK_CUR The \c position is added to the current position of the
 625                  cursor.
 626                - \c SEEK_END The cursor is put at the end of the data, plus
 627                  \a position added to it.
 628
 629         \return The new position as an off_t.
 630
 631         \since BeOS R3
 632 */
 633
 634
 635 /*!
 636         \fn off_t BMallocIO::Position() const
 637         \brief Return the position of the cursor.
 638
 639         \since BeOS R3
 640 */
 641
 642
 643 /*!
 644         \fn status_t BMallocIO::SetSize(off_t size)
 645         \brief Change the size of the buffer.
 646
 647         This method changes the size of the current buffer. If \a size is smaller
 648         than the current size, the data will be cleared.
 649
 650         \param size The new size of the buffer.
 651
 652         \return A status code.
 653         \retval B_OK Resizing the data succeeded.
 654         \retval B_NO_MEMORY Failed to allocate the necessary memory.
 655
 656         \since BeOS R3
 657 */
 658
 659
 660 /*!
 661         \fn void BMallocIO::SetBlockSize(size_t blockSize)
 662         \brief Change the block size to a certain value.
 663
 664         This class allocates memory in blocks. If you are in performance-critical
 665         code you might want to tweak this setting to create a better performance in
 666         case you know you are going to allocate more than the default block size of
 667         256.
 668
 669         \param blockSize The new block size.
 670
 671         \since BeOS R3
 672 */
 673
 674
 675 /*!
 676         \fn const void* BMallocIO::Buffer() const
 677         \brief Return a pointer to the internal buffer.
 678
 679         As with any pointer to internal buffers the Haiku API exposes,
 680         make sure you don't change anything since it doesn't belong to you.
 681
 682         \since BeOS R3
 683 */
 684
 685
 686 /*!
 687         \fn size_t BMallocIO::BufferLength() const
 688         \brief Return the number of bytes in the buffer.
 689
 690         This number doesn't have to be the same size as the buffer is. Because memory
 691         is allocated in blocks the actual size of the buffer may be greater, but this
 692         method only returns the number of bytes that are actually used.
 693
 694         \since BeOS R3
 695 */