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