1/* 2 * Copyright 2007,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/BufferIO.h rev 19972 11 * src/kits/support/BufferIO.cpp rev 20510 12 */ 13 14 15/*! 16 \file BufferIO.h 17 \ingroup support 18 \ingroup libbe 19 \brief Provides the BBufferIO class. 20*/ 21 22 23/*! 24 \class BBufferIO 25 \ingroup support 26 \ingroup libbe 27 \brief A buffered adapter for BPositionIO objects. 28 \author Stefano Ceccherini \<burton666@freemail.it\> 29 30 This class differs from other classes derived from BPositionIO in a sense 31 that it does not actually provide an actual entity to be read or written 32 to, but rather acts like a "frontend" to a stream. This class especially 33 comes in handy when working with files that are constantly written and 34 rewritten and where you want do this writing buffered so that the hard 35 disk or the network will not have to be accessed so frequently. 36 37 This class works as follows. After constructing a BBufferIO object that 38 you want to be buffered, you can create this object. The constructor 39 takes a \a stream parameter that points to the object to be buffered. 40 41 You then use this object as a proxy to the resource you want to read 42 of or write to. As soon as you use ReadAt(), the buffer will be 43 initialized to the contents of the original stream, and subsequent calls 44 to the positions within the buffer will not be routed to the original 45 stream. In the same way WriteAt() will change the data in the buffer, 46 but not in the actual stream. In order to flush the changes to the 47 original stream, use the Flush() method. Deleting the object when you are 48 done with it will also flush the stream and update the original stream. 49 50 \note This class is not meant to be used in cases where the 51 original stream requires to be in a consistent state. Neither should 52 this class be used as a way to perform 'atomic' writes, because the 53 object might need to do partial writes if it needs to 'move' the 54 buffer. This happens for instance if the original stream is bigger 55 than the buffer. 56*/ 57 58/*! 59 \fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, 60 bool ownsStream) 61 \brief Initialize a BBufferIO object. 62 63 The constructor will create a buffer of the given size 64 and associate the object with the given BPositionIO stream. 65 66 \param stream A pointer to a BPositionIO object. 67 \param bufferSize The size of the buffer that the object will allocate and 68 use. 69 \param ownsStream Specifies if the object will delete the stream on 70 destruction. 71*/ 72 73/*! 74 \fn BBufferIO::~BBufferIO() 75 \brief Free the resources allocated by the object 76 77 Flush pending changes to the stream and free the allocated memory. 78 If the \c owns_stream property is \c true, the destructor also 79 deletes the stream associated with the BBufferIO object. 80*/ 81 82 83/*! 84 \fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size) 85 \brief Read the specified amount of bytes at the given position. 86 87 \param pos The offset into the stream where to read. 88 \param buffer A pointer to a buffer where to copy the read data. 89 \param size The amount of bytes to read. 90 91 \return The amount of bytes actually read, or an error code. 92 \retval B_NO_INIT The object is not associated with a valid BPositionIO 93 stream. 94 \retval B_BAD_VALUE The \c buffer parameter is not valid. 95*/ 96 97/*! 98 \fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size) 99 \brief Write the specified amount of bytes at the given position. 100 101 \param pos The offset into the stream where to write. 102 \param buffer A pointer to a buffer which contains the data to write. 103 \param size The amount of bytes to write. 104 105 \return The amount of bytes actually written, or an error code. 106 \retval B_NO_INIT The object is not associated with a valid BPositionIO 107 stream. 108 \retval B_BAD_VALUE The \c buffer parameter is not valid. 109*/ 110 111/*! 112 \fn off_t BBufferIO::Seek(off_t position, uint32 seekMode) 113 \brief Set the position in the stream. 114 115 Set the position in the stream where the Read() and Write() functions 116 (inherited from BPositionIO) begin reading and writing. 117 How the position argument is understood depends on the seek_mode flag. 118 119 \param position The position where you want to seek. 120 \param seekMode Can have three values: 121 - \c SEEK_SET The position passed is an offset from the beginning of 122 the stream; in other words, the current position is set to 123 position. For this mode, position should be a positive value. 124 - \c SEEK_CUR The position argument is an offset from the current 125 position; the value of the argument is added to the current 126 position. 127 - \c SEEK_END. The position argument is an offset from the end of the 128 stream. In this mode the position argument should be negative 129 (or zero). 130 131 \return The current position as an offset in bytes from the beginning of 132 the stream. 133 \retval B_NO_INIT The object is not associated with a valid BPositionIO 134 stream. 135*/ 136 137/*! 138 \fn off_t BBufferIO::Position() const 139 \brief Return the current position in the stream. 140 141 \return The current position as an offset in bytes 142 from the beginning of the stream. 143 \retval B_NO_INIT The object is not associated with a valid BPositionIO 144 stream. 145*/ 146 147/*! 148 \fn status_t BBufferIO::SetSize(off_t size) 149 \brief Call the SetSize() function of the assigned BPositionIO stream. 150 151 \param size The new size of the BPositionIO object. 152 153 \returns A status code. 154 \retval B_OK The stream is resized. 155 \retval B_NO_INIT The object is not associated with a valid BPositionIO 156 stream. 157*/ 158 159/*! 160 \fn status_t BBufferIO::Flush() 161 \brief Write pending modifications to the stream. 162 163 \return The amount of bytes written, or if it failed it will return an error 164 code. 165*/ 166 167 168/*! 169 \fn BPositionIO *BBufferIO::Stream() const 170 \brief Return a pointer to the stream specified on construction. 171 172 \return A pointer to the BPositionIO stream specified on construction. 173*/ 174 175 176/*! 177 \fn size_t BBufferIO::BufferSize() const 178 \brief Return the size of the internal buffer. 179 180 \return The size of the buffer allocated by the object. 181*/ 182 183 184/*! 185 \fn bool BBufferIO::OwnsStream() const 186 \brief Tell if the BBufferIO object "owns" the specified stream. 187 188 \retval true The object "owns" the stream and will destroy it upon 189 destruction. 190 \retval false The object does not own the stream. 191 192 \see SetOwnsStream() 193*/ 194 195 196/*! 197 \fn void BBufferIO::SetOwnsStream(bool owns_stream) 198 \brief Set the \c owns_stream property of the object. 199 200 \param owns_stream If you pass \c true, the object will delete the stream 201 upon destruction, if you pass \c false it will not. 202*/ 203 204 205/*! 206 \fn void BBufferIO::PrintToStream() const 207 \brief Print the object to stdout. 208*/ 209