All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | List of all members
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.
 
BPositionIOStream () 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
streamA pointer to a BPositionIO object.
bufferSizeThe size of the buffer that the object will allocate and use.
ownsStreamSpecifies 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
trueThe object "owns" the stream and will destroy it upon destruction.
falseThe 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_INITThe 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
posThe offset into the stream where to read.
bufferA pointer to a buffer where to copy the read data.
sizeThe amount of bytes to read.
Returns
The amount of bytes actually read, or an error code.
Return values
B_NO_INITThe object is not associated with a valid BPositionIO stream.
B_BAD_VALUEThe 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
positionThe position where you want to seek.
seekModeCan 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_INITThe 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_streamIf 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
sizeThe new size of the BPositionIO object.
Returns
A status code.
Return values
B_OKThe stream is resized.
B_NO_INITThe 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
posThe offset into the stream where to write.
bufferA pointer to a buffer which contains the data to write.
sizeThe amount of bytes to write.
Returns
The amount of bytes actually written, or an error code.
Return values
B_NO_INITThe object is not associated with a valid BPositionIO stream.
B_BAD_VALUEThe buffer parameter is not valid.
Since
Haiku R1

Implements BPositionIO.