Public Member Functions | List of all members
BPositionIO Class Referenceabstract

Abstract interface that provides advanced read, write and seek access to data. More...

Inherits BDataIO.

Inherited by BBitmapStream, BBufferIO, BFile, BMallocIO, and BMemoryIO.

Public Member Functions

 BPositionIO ()
 This constructor does nothing. More...
 
virtual ~BPositionIO ()
 This destructor does nothing. More...
 
virtual status_t GetSize (off_t *size) const
 Get the size of the object or data. More...
 
virtual off_t Position () const =0
 Pure virtual to return the current position of the cursor. More...
 
virtual ssize_t Read (void *buffer, size_t size)
 Read data from current position. More...
 
virtual ssize_t ReadAt (off_t position, void *buffer, size_t size)=0
 Pure virtual to read data from a certain position. More...
 
status_t ReadAtExactly (off_t position, void *buffer, size_t size, size_t *_bytesRead=NULL)
 Reads an exact amount of data from the object at the specified position into a buffer. More...
 
virtual off_t Seek (off_t position, uint32 seekMode)=0
 Pure virtual to move the cursor to a certain position. More...
 
virtual status_t SetSize (off_t size)
 Set the size of the object or data. More...
 
virtual ssize_t Write (const void *buffer, size_t size)
 Write data to the current position. More...
 
virtual ssize_t WriteAt (off_t position, const void *buffer, size_t size)=0
 Pure virtual to write data to a certain position. More...
 
status_t WriteAtExactly (off_t position, const void *buffer, size_t size, size_t *_bytesWritten=NULL)
 Writes an exact amount of data from a buffer to the object at the specified position. More...
 
- Public Member Functions inherited from BDataIO
 BDataIO ()
 This constructor does nothing. More...
 
virtual ~BDataIO ()
 This destructor does nothing. More...
 
virtual status_t Flush ()
 Writes pending data to underlying storage. More...
 
status_t ReadExactly (void *buffer, size_t size, size_t *_bytesRead=NULL)
 Reads an exact amount of data from the object into a buffer. More...
 
status_t WriteExactly (const void *buffer, size_t size, size_t *_bytesWritten=NULL)
 Writes an exact amount of data from a buffer to the object. More...
 

Detailed Description

Abstract interface that provides advanced read, write and seek access 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 class should at least re-implement ReadAt(), WriteAt(), Seek(), Position(), SetSize() and GetSize() methods.

A good example of a form of data that can derive from this object, are files. The BFile class derives from BPositionIO and provides this interface to files. If your object or data only supports linear reading and writing, consider deriving from the base-class BDataIO.

A final note, from BDataIO this class inherits Read() and Write(). The 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

Constructor & Destructor Documentation

◆ BPositionIO()

BPositionIO::BPositionIO ( )

This constructor does nothing.

Since
Haiku R1

◆ ~BPositionIO()

BPositionIO::~BPositionIO ( )
virtual

This destructor does nothing.

Since
Haiku R1

Member Function Documentation

◆ GetSize()

status_t BPositionIO::GetSize ( off_t *  size) const
virtual

Get the size of the object or data.

The default implementation uses Seek() with the SEEK_END flag to determine the size of the buffer. If your data or object has a different way of determining size, reimplement this method.

Please check that NULL is not passed into size if you reimplement it in your class.

Parameters
[out]sizeThe size of the object is put into this parameter.
Returns
This method returns B_OK on success or an error code on error.
See also
SetSize()
Seek()
Since
BeOS R3

Reimplemented in BFile.

◆ Position()

off_t BPositionIO::Position ( ) const
pure virtual

Pure virtual to return the current position of the cursor.

Returns
Your implementation should return the current position of the cursor.
Since
BeOS R3

Implemented in BMallocIO, BMemoryIO, BFile, BBitmapStream, and BBufferIO.

◆ Read()

ssize_t BPositionIO::Read ( void *  buffer,
size_t  size 
)
virtual

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

Reimplemented from BDataIO.

Reimplemented in BFile.

◆ ReadAt()

ssize_t BPositionIO::ReadAt ( off_t  position,
void *  buffer,
size_t  size 
)
pure virtual

Pure virtual to read data from a certain position.

Your implementation should copy data from the position indicated by position into the buffer with the maximum size of size.

Returns
The amount of bytes actually read, or an error code.
Since
BeOS R3

Implemented in BMallocIO, BMemoryIO, BFile, BBitmapStream, and BBufferIO.

◆ ReadAtExactly()

status_t BPositionIO::ReadAtExactly ( off_t  position,
void *  buffer,
size_t  size,
size_t *  _bytesRead = NULL 
)

Reads an exact amount of data from the object at the specified position into a buffer.

This is a convenience wrapper method for ReadAt() for code that expects the exact number of bytes requested to be read. This method calls ReadAt() in a loop to read the data. It fails when ReadAt() returns an error or fails to read any more data (i.e. returns 0).

Parameters
positionThe object position at which to read the data.
bufferPointer to pre-allocated storage of at least size bytes into which the data shall be read. Won't be dereferenced, when size is 0.
sizeThe number of bytes to be read.
_bytesReadOptional pointer to a pre-allocated size_t into which the number of bytes actually read will be written. When the method returns B_OK this will always be size. Can be NULL.
Returns
An error code indicating whether or not the method succeeded.
Return values
B_OKAll data have been read.
B_PARTIAL_READReadAt() didn't fail, but couldn't provide as many bytes as requested.
Since
Haiku R1

◆ Seek()

off_t BPositionIO::Seek ( off_t  position,
uint32  seekMode 
)
pure virtual

Pure virtual to move the cursor to a certain position.

Your implementation should move the position of the cursor to the provided point. What this actually means, depends on your object or data.

Parameters
positionAn integer that defines a position.
seekModeYou will get one of the following values:
  • SEEK_SET Set the cursor to the position indicated by position.
  • SEEK_END Set the cursor to the end of the buffer, and go position beyond that.
  • SEEK_CUR Set the cursor the the current position plus position.
Returns
The new position.
Since
BeOS R3

Implemented in BMallocIO, BMemoryIO, BFile, BBitmapStream, and BBufferIO.

◆ SetSize()

status_t BPositionIO::SetSize ( off_t  size)
virtual

Set the size of the object or data.

The default implementation returns B_ERROR. If your object or data allows the size to be changed, reimplement this method.

Returns
Return B_OK if everything succeeded, else return the appropriate error code.
Since
BeOS R3

Reimplemented in BMallocIO, BMemoryIO, BFile, BBitmapStream, and BBufferIO.

◆ Write()

ssize_t BPositionIO::Write ( const void *  buffer,
size_t  size 
)
virtual

Write data to the current position.

This method is derived from BDataIO. The default implementation writes data 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

Reimplemented from BDataIO.

Reimplemented in BFile.

◆ WriteAt()

ssize_t BPositionIO::WriteAt ( off_t  position,
const void *  buffer,
size_t  size 
)
pure virtual

Pure virtual to write data to a certain position.

Your implementation should copy data from buffer to the position indicated by buffer with the maximum size of size.

Returns
The amount of bytes actually written, or an error code.
Since
BeOS R3

Implemented in BMallocIO, BMemoryIO, BFile, BBitmapStream, and BBufferIO.

◆ WriteAtExactly()

status_t BPositionIO::WriteAtExactly ( off_t  position,
const void *  buffer,
size_t  size,
size_t *  _bytesWritten = NULL 
)

Writes an exact amount of data from a buffer to the object at the specified position.

This is a convenience wrapper method for WriteAt() for code that expects the exact number of bytes given to be written. This method calls WriteAt() in a loop to write the data. It fails when WriteAt() returns an error or fails to write any more data (i.e. returns 0).

Parameters
positionThe object position at which to write the data.
bufferPointer to a buffer of at least size bytes containing the data to be written. Won't be dereferenced, when size is 0.
sizeThe number of bytes to be written.
_bytesWrittenOptional pointer to a pre-allocated size_t into which the number of bytes actually written will be written. When the method returns B_OK this will always be size. Can be NULL.
Returns
An error code indicated whether the method succeeded.
Return values
B_OKAll data have been written.
B_PARTIAL_READWriteAt() didn't fail, but couldn't write as many bytes as provided.
Since
Haiku R1