1<!-- saved from url=(0022)http://internet.e-mail --> 2<HTML> 3<HEAD> 4<TITLE>BMallocIO Use Cases and Implementation Details</TITLE> 5</HEAD> 6 7<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF"> 8 9<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1"> 10 11<H1>BMallocIO Use Cases and Implementation Details:</H1> 12 13<P>This document describes the BMallocIO interface and some basics of how it is implemented. 14The document has the following sections:</P> 15 16<OL> 17<LI><A HREF="#interface">BMallocIO Interface</A></LI> 18<LI><A HREF="#usecases">BMallocIO Use Cases</A></LI> 19<LI><A HREF="#implement">BMallocIO Implementation</A></LI> 20</OL> 21 22<A NAME="interface"></A><H2>BMallocIO Interface:</H2> 23 24<P>The BMallocIO class represent a buffer of dynamically allocated memory. The buffer is 25automatically allocated by multiplies of a blocksize you can specify, so it will always be 26big enough to contain the data. The best source of information for the BMallocIO interface 27can be found 28<A HREF="file:///boot/beos/documentation/Be%20Book/The%20Support%20Kit/MemoryIO.html">here in the Be Book</A>. 29</P> 30 31<A NAME="usecases"></A><H2>BMallocIO Use Cases:</H2> 32 33<P>The following use cases cover the BMallocIO functionality:</P> 34 35<OL> 36 37<LI><P><B>Construction 1:</B> The BMallocIO constructor set the blocksize to 256.</P></LI> 38 39<LI><P><B>Destruction:</B> The BMallocIO destructor frees the allocated memory.</P></LI> 40 41<LI><P><B>Reading 1:</B> When ReadAt() is called, the BMallocIO returns the number of bytes read from the specified 42position. ReadAt() takes three arguments: the position where to begin the read operation, the buffer where to put the read data, 43and the number of bytes to read. This function does not read outside of the buffer. 44If the specified position is invalid (i.e. outside bounds) this function returns 0. If the read operation 45begins at a valid position, but the sum of position and bytes to read is bigger than the size of the buffer, BMallocIO 46returns just the available data.</P></LI> 47 48<LI><P><B>Reading 2.</B> BMallocIO inherits the Read() function from BPositionIO. This function read the specified amount 49of 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. 50This function behaves like the above. </P></LI> 51 52<LI><P><B>Writing 1:</B> When WriteAt() is called, BMallocIO returns the number of bytes written to the specified position. 53WriteAt() takes three arguments: the position where to begin the write operation, the buffer from which to read the data to write, and the 54number of bytes to write. 55If the write position is beyond the buffer length, BMallocIO enlarges the buffer to accomodate the data. If enlarging fails, the function 56returns B_NO_MEMORY. 57</P></LI> 58 59<LI><P><B>Writing 2.</B> BMallocIO inherits the Write() function from BPositionIO. This function write the specified amount 60of data to the current position of the BMallocIO object, reading from the specified buffer, then it moves the I/O index forward 61of the number of read bytes. 62This function behaves like the above. </P></LI> 63 64<LI><P><B>Size Changes:</B> The SetSize() member function enlarges or shrink the amount of data which can be read/write. 65Shrinking the buffer is always possible, and the function returns B_OK. Zero frees the memory, while negative values are 66not allowed, and the function returns B_ERROR. 67</P></LI> 68 69<LI><P><B>Seeking.</B> Seek() sets the position in the data buffer where the Read() and Write() functions (inherited from 70BPositionIO) begin reading and writing. How the position argument is understood depends on the mode flag. There are three possible modes: 71 <UL> 72 <LI><P> 73 SEEK_SET. The position passed is an offset from the beginning of allocated memory; in other 74 words, the current position is set to position. For this mode, position should be a positive 75 value. 76 </P></LI> 77 <LI><P> 78 SEEK_CUR. The position argument is an offset from the current position; the value of the 79 argument is added to the current position. </P></LI> 80 <LI><P> 81 SEEK_END. The position argument is an offset from the end of the buffer for a BMallocIO 82 object. Positive values seek beyond the end of the buffer or data; negative 83 values seek backwards into the data. </P></LI> 84 </UL> 85Seek() Always return the new position. 86</P></LI> 87 88<LI><P><B>Position:</B> The Position() call always return the current position.</P></LI> 89 90<LI><P><B>Setting the BlockSize:</B> The SetBlockSize() call let you specify 91the blocksize which BMallocIO uses to allocate memory.</P></LI> 92 93<LI><P><B>Getting the Buffer:</B> The Buffer() call returns the buffer used internally 94by BMallocIO.</P></LI> 95 96<LI><P><B>Getting the Buffer Lenght:</B> The BufferLength() call returns the length 97of the buffer.</P></LI> 98 99</OL> 100 101<A NAME="implement"></A><H2>BMallocIO Implementation:</H2> 102 103</BODY> 104</HTML>