BDataIO and BPositionIO

Derived from: BDataIO:

Declared in: be/support/DataIO.h

Library: libbe.so

Summary

BDataIO and BPositionIO are abstract classes defining protocols for performing input/output operations. Classes derived from them represent the various objects that can be treated as sources of input data or as repositories for output data. For example, the BFile class, defined in the Storage Kit, represents a file. BMallocIO and BMemoryIO, also defined in the Support Kit, represent dynamically allocated memory buffers.

BDataIO declares only the basic I/O functions Read() and Write(). BPositionIO declares an additional set of functions (ReadAt(), WriteAt(), Seek(), and Position()) for objects that can keep track of the current position in the I/O buffer; it implements Read() and Write() in terms of these other functions.

Neither class declares any data members, nor do they implement the functions in the protocols they declare. It's up to derived classes to implement them based on the properties of the particular kinds of data sources/repositories they represent.

Constructor and Destructor

BDataIO() , BPositionIO()

	BDataIO(void) BPositionIO(void)

These constructors have nothing to do. Constructors in derived classes should initialize the object to default values—for example, set the current position to the beginning of the data.

~BDataIO() , ~BPositionIO()

	virtual ~BDataIO() virtual ~BPositionIO()

These destructors do nothing.

Member Functions

Position() see Seek()

Read() , ReadAt()

	virtual ssize_t Read(void *buffer, size_t numBytes) = 0 virtual ssize_t Read(void *buffer, size_t numBytes) virtual ssize_t ReadAt(off_t position, void *buffer, size_t numBytes) = 0

Read() is implemented by derived classes to copy numBytes bytes of data from the object to the buffer. It should return the number of bytes actually read, which may be 0, or an error code if something goes wrong.

Similarly, ReadAt() is implemented by derived classes to read numBytes bytes of data beginning at position in the data source, and to place them in the buffer. Like Read(), it should return the number of bytes actually read, or an error code if something goes wrong.

The BPositionIO class implements Read() in terms of ReadAt(), Seek(), and Position()—so that it will always read starting at the current position and move the current position beyond the data it has read. However, it leaves these latter functions for derived classes to implement.

Seek() , Position()

	virtual off_t Seek(off_t position, int32 mode) = 0 virtual off_t Position(void) const = 0

Seek() is implemented by derived classes to modify the current position maintained by the object. The current position is an offset in bytes from the beginning of the object's data. How the position argument is interpreted will depend on the mode flag. Three possible modes should be supported:

• SEEK_SET. The position passed is an offset from the beginning of allocated memory; in other words, the current position should be set to position.

• SEEK_CUR. The position argument is an offset from the current position; the current position should be incremented by position.

• SEEK_END. The position argument is an offset from the end of the data; the current position should be the sum of position plus the number of bytes in the data.

For the SEEK_SET mode, position should be a positive value. The other modes permit negative offsets.

Seek() should return the new current position, as should Position().

SetSize()

	virtual status_t SetSize(off_t numBytes)

Returns B_ERROR to indicate that, in general, BPositionIO objects can't set the amount of memory in the repositories they represent. However, the BMallocIO class in this kit and BFile in the Storage Kit implement SetSize() functions that override this default.

See also: BFile::SetSize(), BMallocIO::SetSize()

Write() , WriteAt()

	virtual ssize_t Write(const void *buffer, size_t numBytes) = 0 virtual ssize_t Write(const void *buffer, size_t numBytes) virtual ssize_t WriteAt(off_t position, const void *buffer, size_t numBytes) = 0

Write() is implemented by derived classes to copy numBytes bytes of data from the buffer to the object. It should return the number of bytes actually written, which may be 0, or an error code if the operation fails.

Similarly, WriteAt() is implemented by derived classes to copy numBytes bytes of data from the buffer to the position offset in the object's data repository. Like Write() it should return the number of bytes it succeeds in writing, or an error code.

The BPositionIO class implements Write() in terms of WriteAt(), Seek(), and Position()—so that it always writes to the current position and moves the position marker past the data it has written.