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

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

Public Member Functions
	BPositionIO ()
	This constructor does nothing.

virtual	~BPositionIO ()
	This destructor does nothing.

virtual status_t	GetSize (off_t *size) const
	Get the size of the object or data.

virtual off_t	Position () const =0
	Pure virtual to return the current position of the cursor.

virtual ssize_t	Read (void *buffer, size_t size)
	Read data from current position.

virtual ssize_t	ReadAt (off_t position, void *buffer, size_t size)=0
	Pure virtual to read data from a certain position.

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.

virtual off_t	Seek (off_t position, uint32 seekMode)=0
	Pure virtual to move the cursor to a certain position.

virtual status_t	SetSize (off_t size)
	Set the size of the object or data.

virtual ssize_t	Write (const void *buffer, size_t size)
	Write data to the current position.

virtual ssize_t	WriteAt (off_t position, const void *buffer, size_t size)=0
	Pure virtual to write data to a certain position.

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.

Public Member Functions inherited from BDataIO
	BDataIO ()
	This constructor does nothing.

virtual	~BDataIO ()
	This destructor does nothing.

virtual status_t	Flush ()
	Writes pending data to underlying storage.

virtual ssize_t	Read (void *buffer, size_t size)
	Reads data from the object into a buffer.

status_t	ReadExactly (void buffer, size_t size, size_t _bytesRead=NULL)
	Reads an exact amount of data from the object into a buffer.

virtual ssize_t	Write (const void *buffer, size_t size)
	Writes data from a buffer to the object.

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.

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] size The 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 BFile, BBufferIO, BMemoryIO, BMallocIO, and BBitmapStream.

◆ 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 BFile, BBitmapStream, BBufferIO, BMemoryIO, and BMallocIO.

◆ 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

position	The object position at which to read the data.
buffer	Pointer to pre-allocated storage of at least size bytes into which the data shall be read. Won't be dereferenced, when size is 0.
size	The number of bytes to be read.
_bytesRead	Optional 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_OK	All data have been read.
B_PARTIAL_READ	ReadAt() 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

position	An integer that defines a position.
seekMode	You 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 BFile, BBufferIO, BMemoryIO, BMallocIO, and BBitmapStream.

◆ 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 BFile, BBufferIO, BMemoryIO, BMallocIO, and BBitmapStream.

◆ 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 BFile, BBitmapStream, BBufferIO, BMemoryIO, and BMallocIO.

◆ 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

position	The object position at which to write the data.
buffer	Pointer to a buffer of at least size bytes containing the data to be written. Won't be dereferenced, when size is 0.
size	The number of bytes to be written.
_bytesWritten	Optional 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_OK	All data have been written.
B_PARTIAL_READ	WriteAt() didn't fail, but couldn't write as many bytes as provided.

Since: Haiku R1

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BPositionIO()

◆ ~BPositionIO()

Member Function Documentation

◆ GetSize()

◆ Position()

◆ Read()

◆ ReadAt()

◆ ReadAtExactly()

◆ Seek()

◆ SetSize()

◆ Write()

◆ WriteAt()

◆ WriteAtExactly()