http://www.be.com/documentation/be_book/support/MemIO.html (Amiga Plus Extra No. 5/97, 05/1997)
Derived from: public BPositionIO
Declared in: <support/DataIO.h>
BMallocIO and BMemoryIO objects represent a buffer of dynamically allocated memory. You assign the buffer to a BMemoryIO object on construction, but a BMallocIO object allocates the buffer when you first call Write() or WriteAt(). On subsequent calls, it makes sure that enough memory is allocated to hold all the data you intend to write, reallocating it if necessary. Memory is allocated in multiples of a block size that you can set.
Both classes implement the BPositionIO protocol. They inherit the Read() and Write() functions that BPositionIO implements.
BMemoryIO(void *buffer size_t numBytes)
BMemoryIO(const void *buffer size_t numBytes)
BMallocIO(void)
The BMemoryIO constructor assigns the object a buffer with at least numBytes of available memory. If the buffer is declared const, the object is read-only; calls to Write() and WriteAt() will fail. Otherwise, the buffer can be both read and written. In either case, the caller retains responsibility for the buffer; the BMemoryIO object won't free it.
The BMallocIO constructor makes sure that the new object is empty and sets the default block size to 256 bytes. The constructor doesn't allocate any memory; memory is allocated when you first write to the object or when you call SetSize() to set the amount of memory.
See also: SetBlockSize(), WriteAt(), SetSize()
virtual ~BMemoryIO(void)
virtual ~BMallocIO(void)
The BMemoryIO destructor does nothing; the BMallocIO destructor frees all memory that was allocated by the object.
const void *Buffer(void) const
size_t BufferLength(void) const
Buffer() returns a pointer to the memory that the BMallocIO object has allocated, or NULL if it hasn't yet had occasion to allocate any memory. BufferLength() returns the number of data bytes in the buffer (not necessarily the full number of bytes that were allocated).
virtual ssize_t ReadAt(off_t position, void *buffer, size_t numBytes)
Copies up to numBytes bytes of data from the object to the buffer and returns the actual number of bytes placed in the buffer. The data is read beginning at the position offset.
This function doesn't read beyond the end of the data. If there are fewer than numBytes of data available at the position offset, it reads only through the last data byte and returns a smaller number than numBytes. If position is out of range, it returns 0.
Both classes define essentially the same ReadAt() function.
See also: WriteAt()
virtual off_t Seek(off_t position, int32 mode)
virtual off_t Position(void) const
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 BMemoryIO object and an offset from the end of the data for a BMallocIO object (not necessarily from the end of allocated memory). Positive values seek beyond the end of the buffer or data; negative values seek backwards into the data. |
For BMallocIO, attempts to seek beyond the end of the data and the end of allocated memory are successful. When Write() is subsequently called, the object updates its conception of where the data ends to bring the current position within range. If necessary, enough memory will be allocated to accommodate any data added at the current position. However, Write() will fail for a BMemoryIO object if the current position is beyond the end of assigned memory.
Both Seek() and Position() return the current position as an offset in bytes from the beginning of allocated memory.
See also: WriteAt()
void SetBlockSize(size_t blockSize)
Sets the size of the memory blocks that the BMallocIO object deals with. The object allocates memory in multiples of the block size. The default is 256 bytes.
See also: WriteAt()
virtual status_t SetSize(off_t numBytes)
Sets the amount of memory allocated for the object so there at least numBytes bytes in the buffer. If numBytes is less than the amount of data currently in the buffer, the BMallocIO object conveniently forgets about any of it beyond the number of bytes specified. If numBytes is more than the amount of memory currently allocated, it reallocates enough blocks of memory to hold the required number of bytes.
If unsuccessful in reallocating the buffer, this function returns B_NO_MEMORY. Otherwise, it returns B_OK.
The BMemoryIO class inherits the BPositionIO version of SetSize(), which always fails and returns B_ERROR.
See also: WriteAt()
virtual ssize_t WriteAt(off_t position, const void *buffer, size_t numBytes)
Takes numBytes bytes of data from the buffer, copies it to allocated memory beginning at position, and returns the number of bytes written.
For BMallocIO, the return value should always be the same as numBytes. If there isn't enough room to hold numBytes bytes of additional data beginning at position, WriteAt() reallocates the buffer so there is enough. Memory is allocated in multiples of the block size. If the reallocation fails, this function returns B_NO_MEMORY.
However, the BMemoryIO version of WriteAt() won't write outside the memory buffer. If position is beyond the end of the buffer, it returns 0. If the object is read-only, it returns B_NOT_ALLOWED.
See also: SetBlockSize(), ReadAt()
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 30, 1997.