docs/user/support/BufferIO.dox

   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 */