docs/develop/support/usecases/BMallocIOUseCases.html

   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.
  14 The 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
  25 automatically allocated by multiplies of a blocksize you can specify, so it will always be
  26 big enough to contain the data. The best source of information for the BMallocIO interface
  27 can 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
  42 position. ReadAt() takes three arguments: the position where to begin the read operation, the buffer where to put the read data,
  43 and the number of bytes to read. This function does not read outside of the buffer.
  44 If the specified position is invalid (i.e. outside bounds) this function returns 0. If the read operation
  45 begins at a valid position, but the sum of position and bytes to read is bigger than the size of the buffer, BMallocIO
  46 returns 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
  49 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.
  50 This 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.
  53 WriteAt() takes three arguments: the position where to begin the write operation, the buffer from which to read the data to write, and the
  54 number of bytes to write.
  55 If the write position is beyond the buffer length, BMallocIO enlarges the buffer to accomodate the data. If enlarging fails, the function
  56 returns 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
  60 of data to the current position of the BMallocIO object, reading from the specified buffer, then it moves the I/O index forward
  61 of the number of read bytes.
  62 This 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.
  65 Shrinking the buffer is always possible, and the function returns B_OK. Zero frees the memory, while negative values are
  66 not 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
  70 BPositionIO) 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>
  85 Seek() 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
  91 the 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
  94 by BMallocIO.</P></LI>
  95
  96 <LI><P><B>Getting the Buffer Lenght:</B> The BufferLength() call returns the length
  97 of the buffer.</P></LI>
  98
  99 </OL>
 100
 101 <A NAME="implement"></A><H2>BMallocIO Implementation:</H2>
 102
 103 </BODY>
 104 </HTML>