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 off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0 274 \brief Pure virtual to move the cursor to a certain position. 275 276 Your implementation should move the position of the cursor to the provided 277 point. What this actually means, depends on your object or data. 278 279 \param position An integer that defines a position. 280 \param seekMode You will get one of the following values: 281 - \c SEEK_SET Set the cursor to the position indicated by 282 \c position. 283 - \c SEEK_END Set the cursor to the end of the buffer, and go 284 \c position beyond that. 285 - \c SEEK_CUR Set the cursor the the current position plus 286 \c position. 287 \return The new position. 288 289 \since BeOS R3 290*/ 291 292 293/*! 294 \fn virtual off_t BPositionIO::Position() const = 0 295 \brief Pure virtual to return the current position of the cursor. 296 297 \return Your implementation should return the current position of the cursor. 298 299 \since BeOS R3 300*/ 301 302 303/*! 304 \fn virtual status_t BPositionIO::SetSize(off_t size) 305 \brief Set the size of the object or data. 306 307 The default implementation returns \c B_ERROR. If your object or data allows 308 the size to be changed, reimplement this method. 309 310 \return Return \c B_OK if everything succeeded, else return the appropriate 311 error code. 312 313 \since BeOS R3 314*/ 315 316 317/*! 318 \fn virtual status_t BPositionIO::GetSize(off_t* size) const 319 \brief Get the size of the object or data. 320 321 The default implementation uses Seek() with the \c SEEK_END flag to 322 determine the size of the buffer. If your data or object has a different way 323 of determining size, reimplement this method. 324 325 Please check that NULL is not passed into \c size if you reimplement it in 326 your class. 327 328 \param[out] size The size of the object is put into this parameter. 329 330 \return This method returns \c B_OK on success or an error code on error. 331 332 \see SetSize() 333 \see Seek() 334 335 \since BeOS R3 336*/ 337 338 339//////////// BMemoryIO 340 341 342/*! 343 \class BMemoryIO 344 \ingroup support 345 \ingroup libbe 346 \brief A BPositionIO derived class that works on memory buffers. 347 348 This class is used if you require access that confirms to the BPositionIO 349 interface on memory buffers that you created. If you would like to use that 350 interface on new buffers, have a look at BMallocIO. 351 352 This class is particularly useful if you would like to use a class or method 353 that are written to make use of the BPositionIO interface. It might also 354 be used for 'secure' reading and writing from buffers, since this class 355 automatically checks the bounds of anything you might want to do. 356 357 This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and 358 Position() interface from BPositionIO. 359 360 \since BeOS R3 361*/ 362 363 364/*! 365 \fn BMemoryIO::BMemoryIO(void *data, size_t length) 366 \brief Create a read/write object. 367 368 \param data A pointer to the buffer to adopt. 369 \param length The size of the buffer. 370 371 \see BMemoryIO(const void *buffer, size_t length) for a read-only 372 implementation. 373 374 \since BeOS R3 375*/ 376 377 378/*! 379 \fn BMemoryIO::BMemoryIO(const void *buffer, size_t length) 380 \brief Create a read-only object. 381 382 \param buffer A pointer to the \c const (read-only) buffer to adopt. 383 \param length The size of the buffer. 384 385 \see BMemoryIO(void *buffer, size_t length) for a read-write implementation. 386 387 \since BeOS R3 388*/ 389 390 391/*! 392 \fn BMemoryIO::~BMemoryIO() 393 \brief The destructor does nothing. 394 395 \since BeOS R3 396*/ 397 398 399/*! 400 \fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size) 401 \brief Read from a given position. 402 403 \param[in] pos The offset where to start reading data. 404 \param[out] buffer The buffer to copy the read bytes into. 405 \param[in] size The size of the \a buffer. 406 407 \return The amount of read bytes or an error code. 408 \retval B_BAD_VALUE The position is less than zero or the buffer given on 409 construction is invalid. 410 411 \since BeOS R3 412*/ 413 414 415/*! 416 \fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size) 417 \brief Write at a given position. 418 419 \param pos The offset to write to. 420 \param buffer The buffer to copy the bytes from. 421 \param size The number of bytes to write. 422 423 \return The amount of bytes written or an error code. 424 \retval B_NOT_ALLOWED The object is constructed as a read-only object. 425 \retval B_BAD_VALUE The position is less than zero or the buffer given on 426 construction is invalid. 427 428 \since BeOS R3 429*/ 430 431 432/*! 433 \fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode) 434 \brief Move the cursor to a given position. 435 436 \param position The position to move the cursor to. 437 \param seek_mode The mode determines where the cursor is placed. 438 Possibilities include: 439 - \c SEEK_SET The cursor is set to \a position. 440 - \c SEEK_CUR The \a position is added to the current position of 441 the cursor. 442 - \c SEEK_END The cursor is put at the end of the data, plus 443 \a position added to it. 444 445 \return The new position. 446 447 \since BeOS R3 448*/ 449 450 451/*! 452 \fn off_t BMemoryIO::Position() const 453 \brief Return the current position. 454 455 \return The current position as an off_t. 456 457 \since BeOS R3 458*/ 459 460 461/*! 462 \fn status_t BMemoryIO::SetSize(off_t size) 463 \brief Resize the buffer. 464 465 This method does not actually resize the buffer. If the new size is greater 466 than the size of the buffer, resizing will fail. It will only succeed if the 467 new size is less than the size of the buffer. The buffer itself will not be 468 resized though. 469 470 This method might be useful in some cases. If the buffer is larger than the 471 data it holds, changing the size will enable you to use the Seek() method 472 with the flag \c SEEK_END and not get an error if you read or write from 473 that position, since you actually have a buffer at the end. 474 475 \retval B_OK The buffer is resized. 476 \retval B_NOT_ALLOWED The buffer is read-only. 477 \retval B_ERROR The \c size is larger than the size of the buffer. 478 479 \since BeOS R3 480*/ 481 482 483//////////// BMallocIO 484 485 486/*! 487 \class BMallocIO 488 \ingroup support 489 \ingroup libbe 490 \brief A BPositionIO derived class that creates a memory buffer. 491 492 This class creates a memory buffer and provides a BPositionIO interface to 493 work on it. The memory buffer grows and shrinks automatically. 494 This is especially useful if you want to use a method or function that 495 works on an object derived from BPositionIO and you want to do something with 496 the resulting data, or it could be useful if you want to read and write to 497 memory in a safe way, since this class has boundary checking. 498 499 BMallocIO allocates a buffer based on a certain block size. This provides a 500 mechanism that will prevent it from needing to allocate new memory too often. 501 The default block size is 256 bytes, you can change it with SetBlockSize(). If 502 you are sure you are going to use a bigger buffer, change the block size so 503 that you won't have to allocate more memory too often, especially if you use 504 this class in performance-critical code. 505 506 If you require a BPositionIO derived object that works on buffers you 507 provide, have a look at BMemoryIO. 508 509 \since BeOS R3 510*/ 511 512 513/*! 514 \fn BMallocIO::BMallocIO() 515 \brief Create a new memory buffer with block size 256. 516 517 \see SetBlockSize() 518 519 \since BeOS R3 520*/ 521 522 523/*! 524 \fn BMallocIO::~BMallocIO() 525 \brief Destroy the object and free the internal buffer. 526 527 \since BeOS R3 528*/ 529 530 531/*! 532 \fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size) 533 \brief Read data at a certain position. 534 535 \param[in] pos Offset into the data where to read from. 536 \param[out] buffer The buffer to copy the read bytes in. 537 \param [in] size Size of the buffer. 538 539 \return The number of read bytes, or \c B_BAD_VALUE if 540 the provided \a buffer is invalid. 541 542 \since BeOS R3 543*/ 544 545 546/*! 547 \fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size) 548 \brief Write data to a certain position. 549 550 \param pos Offset into the data where to write to. 551 \param buffer The buffer to copy from. 552 \param size The size of the buffer. 553 554 \return The number of bytes written or \c B_BAD_VALUE if the provided. 555 \a buffer is invalid. 556 557 \since BeOS R3 558*/ 559 560 561/*! 562 \fn off_t BMallocIO::Seek(off_t position, uint32 seekMode) 563 \brief Move the cursor to a given position. 564 565 \param position The position to move the cursor to. 566 \param seekMode The mode determines where the cursor is placed. Possibilities: 567 - \c SEEK_SET The cursor is set to \a position. 568 - \c SEEK_CUR The \c position is added to the current position of the 569 cursor. 570 - \c SEEK_END The cursor is put at the end of the data, plus 571 \a position added to it. 572 573 \return The new position as an off_t. 574 575 \since BeOS R3 576*/ 577 578 579/*! 580 \fn off_t BMallocIO::Position() const 581 \brief Return the position of the cursor. 582 583 \since BeOS R3 584*/ 585 586 587/*! 588 \fn status_t BMallocIO::SetSize(off_t size) 589 \brief Change the size of the buffer. 590 591 This method changes the size of the current buffer. If \a size is smaller 592 than the current size, the data will be cleared. 593 594 \param size The new size of the buffer. 595 596 \return A status code. 597 \retval B_OK Resizing the data succeeded. 598 \retval B_NO_MEMORY Failed to allocate the necessary memory. 599 600 \since BeOS R3 601*/ 602 603 604/*! 605 \fn void BMallocIO::SetBlockSize(size_t blockSize) 606 \brief Change the block size to a certain value. 607 608 This class allocates memory in blocks. If you are in performance-critical 609 code you might want to tweak this setting to create a better performance in 610 case you know you are going to allocate more than the default block size of 611 256. 612 613 \param blockSize The new block size. 614 615 \since BeOS R3 616*/ 617 618 619/*! 620 \fn const void* BMallocIO::Buffer() const 621 \brief Return a pointer to the internal buffer. 622 623 As with any pointer to internal buffers the Haiku API exposes, 624 make sure you don't change anything since it doesn't belong to you. 625 626 \since BeOS R3 627*/ 628 629 630/*! 631 \fn size_t BMallocIO::BufferLength() const 632 \brief Return the number of bytes in the buffer. 633 634 This number doesn't have to be the same size as the buffer is. Because memory 635 is allocated in blocks the actual size of the buffer may be greater, but this 636 method only returns the number of bytes that are actually used. 637 638 \since BeOS R3 639*/ 640