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/BufferIO.h rev 38225 12 * src/kits/support/BufferIO.cpp rev 44862 13 */ 14 15 16/*! 17 \file BufferIO.h 18 \ingroup support 19 \ingroup libbe 20 \brief Provides the BBufferIO class. 21*/ 22 23 24/*! 25 \class BBufferIO 26 \ingroup support 27 \ingroup libbe 28 \brief A buffered adapter for BPositionIO objects. 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 \since Haiku R1 58*/ 59 60 61/*! 62 \fn BBufferIO::BBufferIO(BPositionIO* stream, size_t bufferSize, 63 bool ownsStream) 64 \brief Initialize a BBufferIO object. 65 66 The constructor will create a buffer of the given size 67 and associate the object with the given BPositionIO stream. 68 69 \param stream A pointer to a BPositionIO object. 70 \param bufferSize The size of the buffer that the object will allocate and 71 use. 72 \param ownsStream Specifies if the object will delete the stream on 73 destruction. 74 75 \since Haiku R1 76*/ 77 78 79/*! 80 \fn BBufferIO::~BBufferIO() 81 \brief Free the resources allocated by the object 82 83 Flush pending changes to the stream and free the allocated memory. 84 If the \c owns_stream property is \c true, the destructor also 85 deletes the stream associated with the BBufferIO object. 86 87 \since Haiku R1 88*/ 89 90 91/*! 92 \fn ssize_t BBufferIO::ReadAt(off_t pos, void* buffer, size_t size) 93 \brief Read the specified amount of bytes at the given position. 94 95 \param pos The offset into the stream where to read. 96 \param buffer A pointer to a buffer where to copy the read data. 97 \param size The amount of bytes to read. 98 99 \return The amount of bytes actually read, or an error code. 100 \retval B_NO_INIT The object is not associated with a valid BPositionIO 101 stream. 102 \retval B_BAD_VALUE The \c buffer parameter is not valid. 103 104 \since Haiku R1 105*/ 106 107 108/*! 109 \fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size) 110 \brief Write the specified amount of bytes at the given position. 111 112 \param pos The offset into the stream where to write. 113 \param buffer A pointer to a buffer which contains the data to write. 114 \param size The amount of bytes to write. 115 116 \return The amount of bytes actually written, or an error code. 117 \retval B_NO_INIT The object is not associated with a valid BPositionIO 118 stream. 119 \retval B_BAD_VALUE The \c buffer parameter is not valid. 120 121 \since Haiku R1 122*/ 123 124 125/*! 126 \fn off_t BBufferIO::Seek(off_t position, uint32 seekMode) 127 \brief Set the position in the stream. 128 129 Set the position in the stream where the Read() and Write() functions 130 (inherited from BPositionIO) begin reading and writing. 131 How the position argument is understood depends on the seek_mode flag. 132 133 \param position The position where you want to seek. 134 \param seekMode Can have three values: 135 - \c SEEK_SET The position passed is an offset from the beginning 136 of the stream; in other words, the current position is set to 137 position. For this mode, position should be a positive value. 138 - \c SEEK_CUR The position argument is an offset from the current 139 position; the value of the argument is added to the current 140 position. 141 - \c SEEK_END. The position argument is an offset from the end of 142 the stream. In this mode the position argument should be negative 143 (or zero). 144 145 \return The current position as an offset in bytes from the beginning of 146 the stream. 147 \retval B_NO_INIT The object is not associated with a valid BPositionIO 148 stream. 149 150 \since Haiku R1 151*/ 152 153 154/*! 155 \fn off_t BBufferIO::Position() const 156 \brief Return the current position in the stream. 157 158 \return The current position as an offset in bytes 159 from the beginning of the stream. 160 \retval B_NO_INIT The object is not associated with a valid BPositionIO 161 stream. 162 163 \since Haiku R1 164*/ 165 166 167/*! 168 \fn status_t BBufferIO::SetSize(off_t size) 169 \brief Call the SetSize() function of the assigned BPositionIO stream. 170 171 \param size The new size of the BPositionIO object. 172 173 \returns A status code. 174 \retval B_OK The stream is resized. 175 \retval B_NO_INIT The object is not associated with a valid BPositionIO 176 stream. 177 178 \since Haiku R1 179*/ 180 181 182/*! 183 \fn status_t BBufferIO::Flush() 184 \brief Write pending modifications to the stream. 185 186 \return The amount of bytes written, or if it failed it will return an 187 error code. 188 189 \since Haiku R1 190*/ 191 192 193/*! 194 \fn BPositionIO* BBufferIO::Stream() const 195 \brief Return a pointer to the stream specified on construction. 196 197 \return A pointer to the BPositionIO stream specified on construction. 198 199 \since Haiku R1 200*/ 201 202 203/*! 204 \fn size_t BBufferIO::BufferSize() const 205 \brief Return the size of the internal buffer. 206 207 \return The size of the buffer allocated by the object. 208 209 \since Haiku R1 210*/ 211 212 213/*! 214 \fn bool BBufferIO::OwnsStream() const 215 \brief Return whether or not the BBufferIO object "owns" the stream. 216 217 \return Whether or not the BBufferIO object "owns" the stream. 218 \retval true The object "owns" the stream and will destroy it upon 219 destruction. 220 \retval false The object does not own the stream. 221 222 \see SetOwnsStream() 223 224 \since Haiku R1 225*/ 226 227 228/*! 229 \fn void BBufferIO::SetOwnsStream(bool owns_stream) 230 \brief Set the \c owns_stream property of the object. 231 232 \param owns_stream If you pass \c true, the object will delete the stream 233 upon destruction, if you pass \c false it will not. 234 235 \since Haiku R1 236*/ 237 238 239/*! 240 \fn void BBufferIO::PrintToStream() const 241 \brief Print the object to standard output. 242 243 \since Haiku R1 244*/ 245