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