This document describes the BMallocIO interface and some basics of how it is implemented. The document has the following sections:
The BMallocIO class represent a buffer of dynamically allocated memory. The buffer is automatically allocated by multiplies of a blocksize you can specify, so it will always be big enough to contain the data. The best source of information for the BMallocIO interface can be found here in the Be Book.
The following use cases cover the BMallocIO functionality:
Construction 1: The BMallocIO constructor set the blocksize to 256.
Destruction: The BMallocIO destructor frees the allocated memory.
Reading 1: When ReadAt() is called, the BMallocIO returns the number of bytes read from the specified position. ReadAt() takes three arguments: the position where to begin the read operation, the buffer where to put the read data, and the number of bytes to read. This function does not read outside of the buffer. If the specified position is invalid (i.e. outside bounds) this function returns 0. If the read operation begins at a valid position, but the sum of position and bytes to read is bigger than the size of the buffer, BMallocIO returns just the available data.
Reading 2. BMallocIO inherits the Read() function from BPositionIO. This function read the specified amount of data from the current position, and put it into the specified buffer, then it moves the I/O index forward of the number of read bytes. This function behaves like the above.
Writing 1: When WriteAt() is called, BMallocIO returns the number of bytes written to the specified position. WriteAt() takes three arguments: the position where to begin the write operation, the buffer from which to read the data to write, and the number of bytes to write. If the write position is beyond the buffer length, BMallocIO enlarges the buffer to accomodate the data. If enlarging fails, the function returns B_NO_MEMORY.
Writing 2. BMallocIO inherits the Write() function from BPositionIO. This function write the specified amount of data to the current position of the BMallocIO object, reading from the specified buffer, then it moves the I/O index forward of the number of read bytes. This function behaves like the above.
Size Changes: The SetSize() member function enlarges or shrink the amount of data which can be read/write. Shrinking the buffer is always possible, and the function returns B_OK. Zero frees the memory, while negative values are not allowed, and the function returns B_ERROR.
Seeking. Seek() sets the position in the data buffer where the Read() and Write() functions (inherited from BPositionIO) begin reading and writing. How the position argument is understood depends on the mode flag. There are three possible modes:
SEEK_SET. The position passed is an offset from the beginning of allocated memory; 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 buffer for a BMallocIO object. Positive values seek beyond the end of the buffer or data; negative values seek backwards into the data.
Position: The Position() call always return the current position.
Setting the BlockSize: The SetBlockSize() call let you specify the blocksize which BMallocIO uses to allocate memory.
Getting the Buffer: The Buffer() call returns the buffer used internally by BMallocIO.
Getting the Buffer Lenght: The BufferLength() call returns the length of the buffer.