BBufferIO Class Reference

A buffered adapter for BPositionIO objects. More...

Inherits BPositionIO.

Public Member Functions
	BBufferIO (BPositionIO *stream, size_t bufferSize=65536L, bool ownsStream=true)
	Initialize a BBufferIO object.
virtual	~BBufferIO ()
	Free the resources allocated by the object.
size_t	BufferSize () const
	Return the size of the internal buffer.
virtual status_t	Flush ()
	Write pending modifications to the stream.
bool	OwnsStream () const
	Return whether or not the BBufferIO object "owns" the stream.
virtual off_t	Position () const
	Return the current position in the stream.
void	PrintToStream () const
	Print the object to standard output.
virtual ssize_t	ReadAt (off_t pos, void *buffer, size_t size)
	Read the specified amount of bytes at the given position.
virtual off_t	Seek (off_t position, uint32 seekMode)
	Set the position in the stream.
void	SetOwnsStream (bool ownsStream)
	Set the owns_stream property of the object.
virtual status_t	SetSize (off_t size)
	Call the SetSize() function of the assigned BPositionIO stream.
BPositionIO *	Stream () const
	Return a pointer to the stream specified on construction.
virtual ssize_t	WriteAt (off_t pos, const void *buffer, size_t size)
	Write the specified amount of bytes at the given position.
Public Member Functions inherited from BPositionIO
	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

A buffered adapter for BPositionIO objects.

This class differs from other classes derived from BPositionIO in a sense that it does not actually provide an actual entity to be read or written to, but rather acts like a "frontend" to a stream. This class especially comes in handy when working with files that are constantly written and rewritten and where you want do this writing buffered so that the hard disk or the network will not have to be accessed so frequently.

This class works as follows. After constructing a BBufferIO object that you want to be buffered, you can create this object. The constructor takes a stream parameter that points to the object to be buffered.

You then use this object as a proxy to the resource you want to read of or write to. As soon as you use ReadAt(), the buffer will be initialized to the contents of the original stream, and subsequent calls to the positions within the buffer will not be routed to the original stream. In the same way WriteAt() will change the data in the buffer, but not in the actual stream. In order to flush the changes to the original stream, use the Flush() method. Deleting the object when you are done with it will also flush the stream and update the original stream.

Note

This class is not meant to be used in cases where the original stream requires to be in a consistent state. Neither should this class be used as a way to perform 'atomic' writes, because the object might need to do partial writes if it needs to 'move' the buffer. This happens for instance if the original stream is bigger than the buffer.

Since

Haiku R1

Constructor & Destructor Documentation

BBufferIO()

BBufferIO::BBufferIO	(	BPositionIO *	stream,
		size_t	bufferSize = 65536L,
		bool	ownsStream = true
	)

Initialize a BBufferIO object.

The constructor will create a buffer of the given size and associate the object with the given BPositionIO stream.

Parameters

stream	A pointer to a BPositionIO object.
bufferSize	The size of the buffer that the object will allocate and use.
ownsStream	Specifies if the object will delete the stream on destruction.

Since

Haiku R1

~BBufferIO()

BBufferIO::~BBufferIO ( )

virtual

Free the resources allocated by the object.

Flush pending changes to the stream and free the allocated memory. If the owns_stream property is true, the destructor also deletes the stream associated with the BBufferIO object.

Since

Haiku R1

Member Function Documentation

BufferSize()

size_t BBufferIO::BufferSize

(

)

const

Return the size of the internal buffer.

Returns

The size of the buffer allocated by the object.

Since

Haiku R1

Flush()

status_t BBufferIO::Flush ( )

virtual

Write pending modifications to the stream.

Returns

The amount of bytes written, or if it failed it will return an error code.

Since

Haiku R1

Reimplemented from BDataIO.

OwnsStream()

bool BBufferIO::OwnsStream

(

)

const

Return whether or not the BBufferIO object "owns" the stream.

Returns

Whether or not the BBufferIO object "owns" the stream.

Return values

true	The object "owns" the stream and will destroy it upon destruction.
false	The object does not own the stream.

See also

SetOwnsStream()

Since

Haiku R1

Position()

off_t BBufferIO::Position ( ) const

virtual

Return the current position in the stream.

Returns

The current position as an offset in bytes from the beginning of the stream.

Return values

B_NO_INIT

The object is not associated with a valid BPositionIO stream.

Since

Haiku R1

Implements BPositionIO.

PrintToStream()

void BBufferIO::PrintToStream

(

)

const

Print the object to standard output.

Since

Haiku R1

ReadAt()

ssize_t BBufferIO::ReadAt ( off_t  pos, void *  buffer, size_t  size  )

virtual

Read the specified amount of bytes at the given position.

Parameters

pos	The offset into the stream where to read.
buffer	A pointer to a buffer where to copy the read data.
size	The amount of bytes to read.

Returns

The amount of bytes actually read, or an error code.

Return values

B_NO_INIT	The object is not associated with a valid BPositionIO stream.
B_BAD_VALUE	The buffer parameter is not valid.

Since

Haiku R1

Implements BPositionIO.

Seek()

off_t BBufferIO::Seek ( off_t  position, uint32  seekMode  )

virtual

Set the position in the stream.

Set the position in the stream where the Read() and Write() functions (inherited from BPositionIO) begin reading and writing. How the position argument is understood depends on the seek_mode flag.

Parameters

position

The position where you want to seek.

seekMode

Can have three values: SEEK_SET The position passed is an offset from the beginning of the stream; in other words, the current position is set to position. For this mode, position should be a positive value. SEEK_CUR The position argument is an offset from the current position; the value of the argument is added to the current position. SEEK_END. The position argument is an offset from the end of the stream. In this mode the position argument should be negative (or zero).

Returns

The current position as an offset in bytes from the beginning of the stream.

Return values

B_NO_INIT

The object is not associated with a valid BPositionIO stream.

Since

Haiku R1

Implements BPositionIO.

SetOwnsStream()

void BBufferIO::SetOwnsStream

(

bool

owns_stream

)

Set the owns_stream property of the object.

Parameters

owns_stream

If you pass true, the object will delete the stream upon destruction, if you pass false it will not.

Since

Haiku R1

SetSize()

status_t BBufferIO::SetSize ( off_t  size )

virtual

Call the SetSize() function of the assigned BPositionIO stream.

Parameters

size	The new size of the BPositionIO object.

Returns

A status code.

Return values

B_OK	The stream is resized.
B_NO_INIT	The object is not associated with a valid BPositionIO stream.

Since

Haiku R1

Reimplemented from BPositionIO.

Stream()

BPositionIO * BBufferIO::Stream

(

)

const

Return a pointer to the stream specified on construction.

Returns

A pointer to the BPositionIO stream specified on construction.

Since

Haiku R1

WriteAt()

ssize_t BBufferIO::WriteAt ( off_t  pos, const void *  buffer, size_t  size  )

virtual

Write the specified amount of bytes at the given position.

Parameters

pos	The offset into the stream where to write.
buffer	A pointer to a buffer which contains the data to write.
size	The amount of bytes to write.

Returns

The amount of bytes actually written, or an error code.

Return values

B_NO_INIT	The object is not associated with a valid BPositionIO stream.
B_BAD_VALUE	The buffer parameter is not valid.

Since

Haiku R1

Implements BPositionIO.