1<!-- saved from url=(0022)http://internet.e-mail --> 2<HTML> 3<HEAD> 4<TITLE>BMemoryIO 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>BMemoryIO Use Cases and Implementation Details:</H1> 12 13<P>This document describes the BMemoryIO interface and some basics of how it is implemented. 14The document has the following sections:</P> 15 16<OL> 17<LI><A HREF="#interface">BMemoryIO Interface</A></LI> 18<LI><A HREF="#usecases">BMemoryIO Use Cases</A></LI> 19<LI><A HREF="#implement">BMemoryIO Implementation</A></LI> 20</OL> 21 22<A NAME="interface"></A><H2>BMemoryIO Interface:</H2> 23 24<P>The BMemoryIO class represent a buffer of dynamically allocated memory. You assign the 25buffer to a BMemoryIO object on construction. The best source of information for the BMemoryIO interface 26can be found 27<A HREF="file:///boot/beos/documentation/Be%20Book/The%20Support%20Kit/MemoryIO.html">here in the Be Book</A>. 28</P> 29 30<A NAME="usecases"></A><H2>BMemoryIO Use Cases:</H2> 31 32<P>The following use cases cover the BMemoryIO functionality:</P> 33 34<OL> 35 36<LI><P><B>Construction 1:</B> A BMemoryIO can be created by specifying a void pointer 37and a ssize_t option. These options are used to determine the buffer to assign to the BMemoryIO object and its 38size. No check is done to determine if the buffer is valid or if it contains at least the number of byte specified.</P></LI> 39 40<LI><P><B>Construction 2:</B> As the one above, but the buffer is specified with a const void pointer. 41The BMemoryIO object becomes read only, and every subsequent Write(), WriteAt() and SetSize() calls will 42return B_NOT_ALLOWED.</P></LI> 43 44<LI><P><B>Destruction:</B> The BMemoryIO destructor does nothing. It's up to the caller the responsibility 45to free the buffer assigned on construction.</P></LI> 46 47<LI><P><B>Reading 1:</B> When ReadAt() is called, the BMemoryIO returns the number of bytes read from the specified 48position. ReadAt() takes three arguments: the position where to begin the read operation, the buffer where to put the read data, 49and the number of bytes to read. This function does not read outside of the buffer. 50If the specified position is invalid (i.e. outside bounds) this function returns 0. If the read operation 51begins at a valid position, but the sum of position and bytes to read is bigger than the max size (specified on construction), BMemoryIO 52returns just the available data.</P></LI> 53 54<LI><P><B>Reading 2.</B> BMemoryIO inherits the Read() function from BPositionIO. This function read the specified amount 55of 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. 56This function behaves like the above. </P></LI> 57 58<LI><P><B>Writing 1:</B> When WriteAt() is called, BMemoryIO returns the number of bytes written to the specified position. 59WriteAt() takes three arguments: the position where to begin the write operation, the buffer from which to read the data to write, and the 60number of bytes to write. If the BMemoryIO object was constructed with the const constructor, this function returns B_NOT_ALLOWED. 61This function does not write outside of the buffer bounds. If the specified position is invalid (i.e. outside bounds) this function returns 0. If the write operation begins at a valid position, but the sum of position and bytes to write is bigger than the max size (specified on construction), BMemoryIO 62returns just the amount of data which can be written. 63If the BMemoryIO object has been shrunk (see the Size Change case), and the write operation is outside the current bounds (but inside the 64bounds specified on construction) this function re-enlarge it to accomodate the data.</P></LI> 65 66<LI><P><B>Writing 2.</B> BMemoryIO inherits the Write() function from BPositionIO. This function write the specified amount 67of data to the current position of the BMemoryIO object, reading from the specified buffer, then it moves the I/O index forward 68of the number of read bytes. 69This function behaves like the above. </P></LI> 70 71<LI><P><B>Size Changes:</B> The SetSize() member function enlarges or shrink the amount of data which can be read/write. 72If the BMemoryIO object was constructed with the const constructor, this function always returns B_NOT_ALLOWED. 73Any SetSize call with a size parameter bigger than the size specified on construction will fail and return B_ERROR. Shrinking the buffer 74is always possible, and the function returns B_OK. Negative values are not allowed, and the function returns B_ERROR. 75</P></LI> 76 77<LI><P><B>Seeking.</B> Seek() sets the position in the data buffer where the Read() and Write() functions (inherited from 78BPositionIO) begin reading and writing. How the position argument is understood depends on the mode flag. There are three possible modes: 79 <UL> 80 <LI><P> 81 SEEK_SET. The position passed is an offset from the beginning of allocated memory; in other 82 words, the current position is set to position. For this mode, position should be a positive 83 value. 84 </P></LI> 85 <LI><P> 86 SEEK_CUR. The position argument is an offset from the current position; the value of the 87 argument is added to the current position. </P></LI> 88 <LI><P> 89 SEEK_END. The position argument is an offset from the end of the buffer for a BMemoryIO 90 object. Positive values seek beyond the end of the buffer or data; negative 91 values seek backwards into the data. </P></LI> 92 </UL> 93Seek() Always return the new position. 94</P></LI> 95 96<LI><P><B>Position:</B> The Position() call always return the current position.</P></LI> 97 98</OL> 99 100<A NAME="implement"></A><H2>BMemoryIO Implementation:</H2> 101 102<P>The implementation of the BMemoryIO is simple. It consist in implementing memory read/write on a buffer 103with an index.</P> 104 105</BODY> 106</HTML>