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 * 9 * Corresponds to: 10 * headers/os/support/DataIO.h rev 38226 11 * src/kits/support/DataIO.cpp rev 42177 12 */ 13 14 15/*! 16 \file DataIO.h 17 \ingroup support 18 \ingroup libbe 19 \brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes. 20 21 Pure virtual BDataIO and BPositioIO classes provide 22 the protocol for Read()/Write()/Seek(). 23 24 BMallocIO and BMemoryIO classes implement the protocol, 25 as does BFile in the Storage Kit. 26*/ 27 28 29///// BDataIO ///// 30 31 32/*! 33 \class BDataIO 34 \ingroup support 35 \ingroup libbe 36 \brief Abstract interface for objects that provide read and write access to 37 data. 38 39 The interface provided by this class applies to objects or data that are 40 limited to reading and writing data. Classes derived from this class should 41 re-implement the Read() or the Write() method from this class or both. 42 43 Candidates of types of data or objects that should be derived from this class 44 are probably broadcasting media streams (which don't support reading at a 45 certain point in the data) or network streams that output data continuously. 46 Objects and data that support more advanced operations like seeking or 47 reading at writing at defined positions should derive their classes from 48 BPositionIO, which inherits this class. 49*/ 50 51 52/*! 53 \fn BDataIO::BDataIO() 54 \brief This constructor does nothing. 55*/ 56 57 58/*! 59 \fn BDataIO::~BDataIO() 60 \brief This destructor does nothing. 61*/ 62 63 64/*! 65 \fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) 66 \brief Reads data from the object into a buffer. 67 68 Your implementation should copy data into \c buffer, with the maximum size 69 of \c size. 70 71 The default implementation is a no-op returning \c B_NOT_SUPPORTED. 72 73 \return You should return the amount of bytes actually read, or an error 74 code in case of failure. 75*/ 76 77 78/*! 79 \fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) 80 \brief Writes data from a buffer to the object. 81 82 Your implementation should copy data from \c buffer, with the maximum size 83 of \c size. 84 85 The default implementation is a no-op returning \c B_NOT_SUPPORTED. 86 87 \return You should return the amount of bytes actually written, or an error 88 code in case of failure. 89*/ 90 91 92//////////// BPositionIO 93 94 95/*! 96 \class BPositionIO 97 \ingroup support 98 \ingroup libbe 99 \brief Abstract interface that provides advanced read, write and seek access 100 to data. 101 102 The interface of this object applies to objects or data that allows 103 position-aware reading and writing of data. Classes that derive from this 104 class should at least re-implement ReadAt(), WriteAt(), Seek(), 105 Position(), SetSize() and GetSize() methods. 106 107 A good example of a form of data that can derive from this object, are 108 files. The BFile class derives from BPositionIO and provides this 109 interface to files. If your object or data only supports linear reading 110 and writing, consider deriving from the base-class BDataIO. 111 112 A final note, from BDataIO this class inherits Read() and Write(). The 113 default implementation is to read or write the data at the current 114 position indicated by Position(). Re-implement the methods if you require 115 a different behavior. 116*/ 117 118 119/*! 120 \fn BPositionIO::BPositionIO() 121 \brief This constructor does nothing. 122*/ 123 124 125/*! 126 \fn virtual BPositionIO::~BPositionIO() 127 \brief This destructor does nothing. 128*/ 129 130 131/*! 132 \fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size) 133 \brief Read data from current position. 134 135 This method is derived from BDataIO. The default implementation reads data 136 from the current position of the cursor, pointed at by Position(). If you 137 require different behaviour, please look at BDataIO::Read() for what is 138 expected of this method. 139*/ 140 141 142/*! 143 \fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size) 144 \brief Write data to the current position. 145 146 This method is derived from BDataIO. The default implementation writes data 147 to the current position of the cursor, pointed at by Position(). If you 148 require different behaviour, please look at BDataIO::Write() for what is 149 expected of this method. 150*/ 151 152 153/*! 154 \fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0 155 \brief Pure virtual to read data from a certain position. 156 157 Your implementation should copy data from the position indicated by 158 \a position into the \a buffer with the maximum size of \a size. 159 160 \return The amount of bytes actually read, or an error code. 161*/ 162 163 164/*! 165 \fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0 166 \brief Pure virtual to write data to a certain position. 167 168 Your implementation should copy data from \a buffer to the position indicated 169 by \a buffer with the maximum size of \a size. 170 171 \return The amount of bytes actually written, or an error code. 172*/ 173 174 175/*! 176 \fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0 177 \brief Pure virtual to move the cursor to a certain position. 178 179 Your implementation should move the position of the cursor to the provided 180 point. What this actually means, depends on your object or data. 181 182 \param position An integer that defines a position. 183 \param seekMode You will get one of the following values: 184 - \c SEEK_SET Set the cursor to the position indicated by \c position. 185 - \c SEEK_END Set the cursor to the end of the buffer, and go 186 \c position beyond that. 187 - \c SEEK_CUR Set the cursor the the current position plus \c position. 188 \return The new position. 189*/ 190 191 192/*! 193 \fn virtual off_t BPositionIO::Position() const = 0 194 \brief Pure virtual to return the current position of the cursor. 195 196 \return Your implementation should return the current position of the cursor. 197*/ 198 199 200/*! 201 \fn virtual status_t BPositionIO::SetSize(off_t size) 202 \brief Set the size of the object or data. 203 204 The default implementation returns \c B_ERROR. If your object or data allows 205 the size to be changed, reimplement this method. 206 207 \return Return \c B_OK if everything succeeded, else return the appropriate 208 error code. 209*/ 210 211 212/*! 213 \fn virtual status_t BPositionIO::GetSize(off_t* size) const 214 \brief Get the size of the object or data. 215 216 The default implementation uses Seek() with the \c SEEK_END flag to 217 determine the size of the buffer. If your data or object has a different way 218 of determining size, reimplement this method. 219 220 Please check that NULL is not passed into \c size if you reimplement it in 221 your class. 222 223 \param[out] size The size of the object is put into this parameter. 224 \return This method returns \c B_OK on success or an error code on error. 225 \see Seek() 226*/ 227 228 229//////////// BMemoryIO 230 231 232/*! 233 \class BMemoryIO 234 \ingroup support 235 \ingroup libbe 236 \brief A BPositionIO derived class that works on memory buffers. 237 238 This class is used if you require access that confirms to the BPositionIO 239 interface on memory buffers that you created. If you would like to use that 240 interface on new buffers, have a look at BMallocIO. 241 242 This class is particularly useful if you would like to use a class or method 243 that are written to make use of the BPositionIO interface. It might also 244 be used for 'secure' reading and writing from buffers, since this class 245 automatically checks the bounds of anything you might want to do. 246 247 This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and 248 Position() interface from BPositionIO. 249*/ 250 251 252/*! 253 \fn BMemoryIO::BMemoryIO(void *data, size_t length) 254 \brief Create a read/write object. 255 256 \param data A pointer to the buffer to adopt. 257 \param length The size of the buffer. 258 \see BMemoryIO(const void *buffer, size_t length) for a read-only 259 implementation. 260*/ 261 262 263/*! 264 \fn BMemoryIO::BMemoryIO(const void *buffer, size_t length) 265 \brief Create a read-only object. 266 267 \param buffer A pointer to the \c const (read-only) buffer to adopt. 268 \param length The size of the buffer. 269 \see BMemoryIO(void *buffer, size_t length) for a read-write implementation. 270*/ 271 272 273/*! 274 \fn BMemoryIO::~BMemoryIO() 275 \brief The destructor does nothing. 276*/ 277 278 279/*! 280 \fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size) 281 \brief Read from a given position. 282 283 \param[in] pos The offset where to start reading data. 284 \param[out] buffer The buffer to copy the read bytes into. 285 \param[in] size The size of the \a buffer. 286 \return The amount of read bytes or an error code. 287 \retval B_BAD_VALUE The position is less than zero or the buffer given on 288 construction is invalid. 289*/ 290 291 292/*! 293 \fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size) 294 \brief Write at a given position. 295 296 \param pos The offset to write to. 297 \param buffer The buffer to copy the bytes from. 298 \param size The number of bytes to write. 299 \return The amount of bytes written or an error code. 300 \retval B_NOT_ALLOWED The object is constructed as a read-only object. 301 \retval B_BAD_VALUE The position is less than zero or the buffer given on 302 construction is invalid. 303*/ 304 305 306/*! 307 \fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode) 308 \brief Move the cursor to a given position. 309 310 \param position The position to move the cursor to. 311 \param seek_mode The mode determines where the cursor is placed. 312 Possibilities: 313 - \c SEEK_SET The cursor is set to \a position. 314 - \c SEEK_CUR The \a position is added to the current position of the 315 cursor. 316 - \c SEEK_END The cursor is put at the end of the data, plus 317 \a position added to it. 318 \return The new position. 319*/ 320 321 322/*! 323 \fn off_t BMemoryIO::Position() const 324 \brief Return the current position. 325*/ 326 327 328/*! 329 \fn status_t BMemoryIO::SetSize(off_t size) 330 \brief Resize the buffer. 331 332 This method does not actually resize the buffer. If the new size is greater 333 than the size of the buffer, resizing will fail. It will only succeed if the 334 new size is less than the size of the buffer. The buffer itself will not be 335 resized though. 336 337 This method might be useful in some cases. If the buffer is larger than the 338 data it holds, changing the size will enable you to use the Seek() method 339 with the flag \c SEEK_END and not get an error if you read or write from 340 that position, since you actually have a buffer at the end. 341 342 \retval B_OK The buffer is resized. 343 \retval B_NOT_ALLOWED The buffer is read-only. 344 \retval B_ERROR The \c size is larger than the size of the buffer. 345*/ 346 347 348//////////// BMallocIO 349 350 351/*! 352 \class BMallocIO 353 \ingroup support 354 \ingroup libbe 355 \brief A BPositionIO derived class that creates a memory buffer. 356 357 This class creates a memory buffer and provides a BPositionIO interface to 358 work on it. The memory buffer grows and shrinks automatically. 359 This is especially useful if you want to use a method or function that 360 works on an object derived from BPositionIO and you want to do something with 361 the resulting data, or it could be useful if you want to read and write to 362 memory in a safe way, since this class has boundary checking. 363 364 BMallocIO allocates a buffer based on a certain block size. This provides a 365 mechanism that will prevent it from needing to allocate new memory too often. 366 The default block size is 256 bytes, you can change it with SetBlockSize(). If 367 you are sure you are going to use a bigger buffer, change the block size so 368 that you won't have to allocate more memory too often, especially if you use 369 this class in performance-critical code. 370 371 If you require a BPositionIO derived object that works on buffers you 372 provide, have a look at BMemoryIO. 373*/ 374 375 376/*! 377 \fn BMallocIO::BMallocIO() 378 \brief Create a new memory buffer with block size 256. 379 \see SetBlockSize() 380*/ 381 382 383/*! 384 \fn BMallocIO::~BMallocIO() 385 \brief Destroy the object and free the internal buffer. 386*/ 387 388 389/*! 390 \fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size) 391 \brief Read data at a certain position. 392 393 \param[in] pos Offset into the data where to read from. 394 \param[out] buffer The buffer to copy the read bytes in. 395 \param [in] size Size of the buffer. 396 \return The number of read bytes, or \c B_BAD_VALUE if 397 the provided \a buffer is invalid. 398*/ 399 400 401/*! 402 \fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size) 403 \brief Write data to a certain position. 404 405 \param pos Offset into the data where to write to. 406 \param buffer The buffer to copy from. 407 \param size The size of the buffer. 408 \return The number of bytes written or \c B_BAD_VALUE if the provided. 409 \a buffer is invalid. 410*/ 411 412 413/*! 414 \fn off_t BMallocIO::Seek(off_t position, uint32 seekMode) 415 \brief Move the cursor to a given position. 416 417 \param position The position to move the cursor to. 418 \param seekMode The mode determines where the cursor is placed. Possibilities: 419 - \c SEEK_SET The cursor is set to \a position. 420 - \c SEEK_CUR The \c position is added to the current position of the 421 cursor. 422 - \c SEEK_END The cursor is put at the end of the data, plus 423 \a position added to it. 424 \return The new position. 425*/ 426 427 428/*! 429 \fn off_t BMallocIO::Position() const 430 \brief Return the position of the cursor. 431*/ 432 433 434/*! 435 \fn status_t BMallocIO::SetSize(off_t size) 436 \brief Change the size of the buffer. 437 438 This method changes the size of the current buffer. If \a size is smaller 439 than the current size, the data will be cleared. 440 441 \param size The new size of the buffer. 442 \retval B_OK Resizing the data succeeded. 443 \retval B_NO_MEMORY Failed to allocate the necessary memory. 444*/ 445 446 447/*! 448 \fn void BMallocIO::SetBlockSize(size_t blockSize) 449 \brief Change the block size to a certain value. 450 451 This class allocates memory in blocks. If you are in performance-critical 452 code you might want to tweak this setting to create a better performance in 453 case you know you are going to allocate more than the default blocksize of 454 256. 455 456 \param blockSize The new block size. 457*/ 458 459 460/*! 461 \fn const void *BMallocIO::Buffer() const 462 \brief Return a pointer to the internal buffer. 463 464 As with any pointer to internal buffers the Haiku API exposes, 465 make sure you don't change anything since it doesn't belong to you. 466*/ 467 468 469/*! 470 \fn size_t BMallocIO::BufferLength() const 471 \brief Return the number of bytes in the buffer. 472 473 This number doesn't have to be the same size as the buffer is. Because memory 474 is allocated in blocks the actual size of the buffer may be greater, but this 475 method only returns the number of bytes that are actually used. 476*/ 477