Update Support Kit docs, add \since
Also add preliminary documentation for BObjectList.
This commit is contained in:
John Scipione
+158
-56
@@ -5,10 +5,11 @@
|
||||
* Authors:
|
||||
* Stefano Ceccherini, [email protected]
|
||||
* Niels Sascha Reedijk, [email protected]
|
||||
* John Scipione, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/support/DataIO.h rev 38226
|
||||
* src/kits/support/DataIO.cpp rev 42177
|
||||
* headers/os/support/DataIO.h hrev47418
|
||||
* src/kits/support/DataIO.cpp hrev47418
|
||||
*/
|
||||
|
||||
|
||||
@@ -16,13 +17,14 @@
|
||||
\file DataIO.h
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
|
||||
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO
|
||||
and BMemoryIO classes.
|
||||
|
||||
Pure virtual BDataIO and BPositioIO classes provide
|
||||
the protocol for Read()/Write()/Seek().
|
||||
Pure virtual BDataIO and BPositioIO classes provide the protocol for
|
||||
Read(), Write(), and Seek().
|
||||
|
||||
BMallocIO and BMemoryIO classes implement the protocol,
|
||||
as does BFile in the Storage Kit.
|
||||
BMallocIO and BMemoryIO classes implement the protocol, as does BFile in
|
||||
the Storage Kit.
|
||||
*/
|
||||
|
||||
|
||||
@@ -34,7 +36,7 @@
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface for objects that provide read and write access to
|
||||
data.
|
||||
data.
|
||||
|
||||
The interface provided by this class applies to objects or data that are
|
||||
limited to reading and writing data. Classes derived from this class should
|
||||
@@ -46,23 +48,29 @@
|
||||
Objects and data that support more advanced operations like seeking or
|
||||
reading at writing at defined positions should derive their classes from
|
||||
BPositionIO, which inherits this class.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDataIO::BDataIO()
|
||||
\brief This constructor does nothing.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDataIO::~BDataIO()
|
||||
\brief This destructor does nothing.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size)
|
||||
\fn virtual ssize_t BDataIO::Read(void* buffer, size_t size)
|
||||
\brief Reads data from the object into a buffer.
|
||||
|
||||
Your implementation should copy data into \c buffer, with the maximum size
|
||||
@@ -71,26 +79,31 @@
|
||||
The default implementation is a no-op returning \c B_NOT_SUPPORTED.
|
||||
|
||||
\return You should return the amount of bytes actually read, or an error
|
||||
code in case of failure.
|
||||
code in case of failure.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size)
|
||||
\fn virtual ssize_t BDataIO::Write(const void* buffer, size_t size)
|
||||
\brief Writes data from a buffer to the object.
|
||||
|
||||
Your implementation should copy data from \c buffer, with the maximum size
|
||||
of \c size.
|
||||
of \c size.
|
||||
|
||||
The default implementation is a no-op returning \c B_NOT_SUPPORTED.
|
||||
|
||||
\return You should return the amount of bytes actually written, or an error
|
||||
code in case of failure.
|
||||
\return You should return the amount of bytes actually written, or an error
|
||||
code in case of failure.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size, size_t* _bytesRead)
|
||||
\fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size,
|
||||
size_t* _bytesRead)
|
||||
\brief Reads an exact amount of data from the object into a buffer.
|
||||
|
||||
This is a convenience wrapper method for Read() for code that expects the
|
||||
@@ -99,21 +112,25 @@
|
||||
read any more data (i.e. returns 0).
|
||||
|
||||
\param buffer Pointer to pre-allocated storage of at least \a size bytes
|
||||
into which the data shall be read. Won't be dereferenced, when \a size
|
||||
is 0.
|
||||
into which the data shall be read. Won't be dereferenced, when
|
||||
\a size is 0.
|
||||
\param size The number of bytes to be read.
|
||||
\param _bytesRead Optional pointer to a pre-allocated size_t into which the
|
||||
number of bytes actually read will be written. When the method returns
|
||||
\c B_OK this will always be \a size. Can be \c NULL.
|
||||
\return An error code indicated whether the method succeeded.
|
||||
number of bytes actually read will be written. When the method
|
||||
returns \c B_OK this will always be \a size. Can be \c NULL.
|
||||
|
||||
\return An error code indicating whether or not the method succeeded.
|
||||
\retval B_OK All data have been read.
|
||||
\retval B_PARTIAL_READ Read() didn't fail, but couldn't provide as many
|
||||
bytes as requested.
|
||||
bytes as requested.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size, size_t* _bytesWritten)
|
||||
\fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size,
|
||||
size_t* _bytesWritten)
|
||||
\brief Writes an exact amount of data from a buffer to the object.
|
||||
|
||||
This is a convenience wrapper method for Write() for code that expects the
|
||||
@@ -122,15 +139,18 @@
|
||||
write any more data (i.e. returns 0).
|
||||
|
||||
\param buffer Pointer to a buffer of at least \a size bytes containing the
|
||||
data to be written. Won't be dereferenced, when \a size is 0.
|
||||
data to be written. Won't be dereferenced, when \a size is 0.
|
||||
\param size The number of bytes to be written.
|
||||
\param _bytesWritten Optional pointer to a pre-allocated size_t into which
|
||||
the number of bytes actually written will be written. When the method
|
||||
returns \c B_OK this will always be \a size. Can be \c NULL.
|
||||
the number of bytes actually written will be written. When the
|
||||
method returns \c B_OK this will always be \a size. Can be \c NULL.
|
||||
|
||||
\return An error code indicated whether the method succeeded.
|
||||
\retval B_OK All data have been written.
|
||||
\retval B_PARTIAL_READ Write() didn't fail, but couldn't write as many
|
||||
bytes as provided.
|
||||
bytes as provided.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
@@ -142,7 +162,7 @@
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface that provides advanced read, write and seek access
|
||||
to data.
|
||||
to data.
|
||||
|
||||
The interface of this object applies to objects or data that allows
|
||||
position-aware reading and writing of data. Classes that derive from this
|
||||
@@ -158,29 +178,37 @@
|
||||
default implementation is to read or write the data at the current
|
||||
position indicated by Position(). Re-implement the methods if you require
|
||||
a different behavior.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BPositionIO::BPositionIO()
|
||||
\brief This constructor does nothing.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual BPositionIO::~BPositionIO()
|
||||
\brief This destructor does nothing.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
|
||||
\fn virtual ssize_t BPositionIO::Read(void* buffer, size_t size)
|
||||
\brief Read data from current position.
|
||||
|
||||
This method is derived from BDataIO. The default implementation reads data
|
||||
from the current position of the cursor, pointed at by Position(). If you
|
||||
require different behaviour, please look at BDataIO::Read() for what is
|
||||
expected of this method.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -192,28 +220,36 @@
|
||||
to the current position of the cursor, pointed at by Position(). If you
|
||||
require different behaviour, please look at BDataIO::Write() for what is
|
||||
expected of this method.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
|
||||
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void* buffer,
|
||||
size_t size) = 0
|
||||
\brief Pure virtual to read data from a certain position.
|
||||
|
||||
Your implementation should copy data from the position indicated by
|
||||
\a position into the \a buffer with the maximum size of \a size.
|
||||
|
||||
\return The amount of bytes actually read, or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
|
||||
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer,
|
||||
size_t size) = 0
|
||||
\brief Pure virtual to write data to a certain position.
|
||||
|
||||
Your implementation should copy data from \a buffer to the position indicated
|
||||
by \a buffer with the maximum size of \a size.
|
||||
|
||||
\return The amount of bytes actually written, or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -226,11 +262,15 @@
|
||||
|
||||
\param position An integer that defines a position.
|
||||
\param seekMode You will get one of the following values:
|
||||
- \c SEEK_SET Set the cursor to the position indicated by \c position.
|
||||
- \c SEEK_END Set the cursor to the end of the buffer, and go
|
||||
\c position beyond that.
|
||||
- \c SEEK_CUR Set the cursor the the current position plus \c position.
|
||||
- \c SEEK_SET Set the cursor to the position indicated by
|
||||
\c position.
|
||||
- \c SEEK_END Set the cursor to the end of the buffer, and go
|
||||
\c position beyond that.
|
||||
- \c SEEK_CUR Set the cursor the the current position plus
|
||||
\c position.
|
||||
\return The new position.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -239,6 +279,8 @@
|
||||
\brief Pure virtual to return the current position of the cursor.
|
||||
|
||||
\return Your implementation should return the current position of the cursor.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -250,7 +292,9 @@
|
||||
the size to be changed, reimplement this method.
|
||||
|
||||
\return Return \c B_OK if everything succeeded, else return the appropriate
|
||||
error code.
|
||||
error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -266,8 +310,13 @@
|
||||
your class.
|
||||
|
||||
\param[out] size The size of the object is put into this parameter.
|
||||
|
||||
\return This method returns \c B_OK on success or an error code on error.
|
||||
|
||||
\see SetSize()
|
||||
\see Seek()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -291,6 +340,8 @@
|
||||
|
||||
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
|
||||
Position() interface from BPositionIO.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -300,8 +351,11 @@
|
||||
|
||||
\param data A pointer to the buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
|
||||
\see BMemoryIO(const void *buffer, size_t length) for a read-only
|
||||
implementation.
|
||||
implementation.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -311,13 +365,18 @@
|
||||
|
||||
\param buffer A pointer to the \c const (read-only) buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
|
||||
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMemoryIO::~BMemoryIO()
|
||||
\brief The destructor does nothing.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -328,9 +387,12 @@
|
||||
\param[in] pos The offset where to start reading data.
|
||||
\param[out] buffer The buffer to copy the read bytes into.
|
||||
\param[in] size The size of the \a buffer.
|
||||
|
||||
\return The amount of read bytes or an error code.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
construction is invalid.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -341,10 +403,13 @@
|
||||
\param pos The offset to write to.
|
||||
\param buffer The buffer to copy the bytes from.
|
||||
\param size The number of bytes to write.
|
||||
|
||||
\return The amount of bytes written or an error code.
|
||||
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
construction is invalid.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -353,20 +418,27 @@
|
||||
\brief Move the cursor to a given position.
|
||||
|
||||
\param position The position to move the cursor to.
|
||||
\param seek_mode The mode determines where the cursor is placed.
|
||||
Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \a position is added to the current position of the
|
||||
cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
\param seek_mode The mode determines where the cursor is placed.
|
||||
Possibilities include:
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \a position is added to the current position of
|
||||
the cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
|
||||
\return The new position.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn off_t BMemoryIO::Position() const
|
||||
\brief Return the current position.
|
||||
|
||||
\return The current position as an off_t.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -387,6 +459,8 @@
|
||||
\retval B_OK The buffer is resized.
|
||||
\retval B_NOT_ALLOWED The buffer is read-only.
|
||||
\retval B_ERROR The \c size is larger than the size of the buffer.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -415,19 +489,26 @@
|
||||
|
||||
If you require a BPositionIO derived object that works on buffers you
|
||||
provide, have a look at BMemoryIO.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMallocIO::BMallocIO()
|
||||
\brief Create a new memory buffer with block size 256.
|
||||
|
||||
\see SetBlockSize()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BMallocIO::~BMallocIO()
|
||||
\brief Destroy the object and free the internal buffer.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -438,8 +519,11 @@
|
||||
\param[in] pos Offset into the data where to read from.
|
||||
\param[out] buffer The buffer to copy the read bytes in.
|
||||
\param [in] size Size of the buffer.
|
||||
|
||||
\return The number of read bytes, or \c B_BAD_VALUE if
|
||||
the provided \a buffer is invalid.
|
||||
the provided \a buffer is invalid.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -450,8 +534,11 @@
|
||||
\param pos Offset into the data where to write to.
|
||||
\param buffer The buffer to copy from.
|
||||
\param size The size of the buffer.
|
||||
|
||||
\return The number of bytes written or \c B_BAD_VALUE if the provided.
|
||||
\a buffer is invalid.
|
||||
\a buffer is invalid.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -461,18 +548,23 @@
|
||||
|
||||
\param position The position to move the cursor to.
|
||||
\param seekMode The mode determines where the cursor is placed. Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \c position is added to the current position of the
|
||||
cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
\return The new position.
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \c position is added to the current position of the
|
||||
cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
|
||||
\return The new position as an off_t.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn off_t BMallocIO::Position() const
|
||||
\brief Return the position of the cursor.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -484,8 +576,12 @@
|
||||
than the current size, the data will be cleared.
|
||||
|
||||
\param size The new size of the buffer.
|
||||
|
||||
\return A status code.
|
||||
\retval B_OK Resizing the data succeeded.
|
||||
\retval B_NO_MEMORY Failed to allocate the necessary memory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -493,21 +589,25 @@
|
||||
\fn void BMallocIO::SetBlockSize(size_t blockSize)
|
||||
\brief Change the block size to a certain value.
|
||||
|
||||
This class allocates memory in blocks. If you are in performance-critical
|
||||
This class allocates memory in blocks. If you are in performance-critical
|
||||
code you might want to tweak this setting to create a better performance in
|
||||
case you know you are going to allocate more than the default blocksize of
|
||||
case you know you are going to allocate more than the default block size of
|
||||
256.
|
||||
|
||||
\param blockSize The new block size.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn const void *BMallocIO::Buffer() const
|
||||
\fn const void* BMallocIO::Buffer() const
|
||||
\brief Return a pointer to the internal buffer.
|
||||
|
||||
As with any pointer to internal buffers the Haiku API exposes,
|
||||
make sure you don't change anything since it doesn't belong to you.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -518,4 +618,6 @@
|
||||
This number doesn't have to be the same size as the buffer is. Because memory
|
||||
is allocated in blocks the actual size of the buffer may be greater, but this
|
||||
method only returns the number of bytes that are actually used.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user