home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / opendc12.zip / od124os2.exe / od12osr1.exe / src / BufferIO.h < prev    next >
C/C++ Source or Header  |  1997-03-21  |  16KB  |  347 lines
  1. /* @(#)Z 1.4 com/src/cm/BufferIO.h, odstorage, od96os2, odos29712d 97/03/21 17:19:22 (96/10/29 09:15:46) */
  2. /*====START_GENERATED_PROLOG======================================
  3.  */
  4. /*
  5.  *   COMPONENT_NAME: odstorage
  6.  *
  7.  *   CLASSES: none
  8.  *
  9.  *   ORIGINS: 82,27
  10.  *
  11.  *
  12.  *   (C) COPYRIGHT International Business Machines Corp. 1995,1996
  13.  *   All Rights Reserved
  14.  *   Licensed Materials - Property of IBM
  15.  *   US Government Users Restricted Rights - Use, duplication or
  16.  *   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  17.  *       
  18.  *   IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  19.  *   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20.  *   PURPOSE. IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  21.  *   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  22.  *   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  23.  *   OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
  24.  *   OR PERFORMANCE OF THIS SOFTWARE.
  25.  */
  26. /*====END_GENERATED_PROLOG========================================
  27.  */
  28.  
  29. /*
  30.     File:        BufferIO.h
  31.  
  32.     Contains:    Container Manager Buffered Data I/O Interfaces
  33.  
  34.     Written by:    Ira L. Ruben
  35.  
  36.     Owned by:    Ed Lai
  37.  
  38.     Copyright:    ⌐ 1992-1994 by Apple Computer, Inc., all rights reserved.
  39.  
  40.     Change History (most recent first):
  41.  
  42.          <2>     8/26/94    EL        #1182308 Add new macro for format/extract
  43.                                     without byte swapping.
  44.          <2>      5/9/94    MB        #1162181 Changes necessary to install MMM.
  45.          <1>      2/3/94    EL        first checked in
  46.  
  47.     To Do:
  48. */
  49.  
  50. /*---------------------------------------------------------------------------*
  51.  |                                                                           |
  52.  |                            <<<  BufferIO.h  >>>                           |
  53.  |                                                                           |
  54.  |              Container Manager Buffered Data I/O Interfaces               |
  55.  |                                                                           |
  56.  |                               Ira L. Ruben                                |
  57.  |                                  8/3/92                                   |
  58.  |                                                                           |
  59.  |                     Copyright Apple Computer, Inc. 1992-1994              |
  60.  |                           All rights reserved.                            |
  61.  |                                                                           |
  62.  *---------------------------------------------------------------------------*
  63.  
  64.  This file defines the routines to allocate and free I/O buffers used for buffered reading
  65.  and writing special data in "chunks" of 1, 2, and 4 byte quantities.  This is NOT a
  66.  generalized I/O package that handles arbitrary sized data.  It is intended as an interface
  67.  to the 1, 2, and 4 byte formatting and extraction handlers for portably and efficiently
  68.  handling internal information written to the container.  This includes, for example,
  69.  updating instructions and TOC entries.  
  70.  
  71.  The main use of these I/O routines is to buffer this internal data as value data for
  72.  some value.  Thus in the case of updating instructions, the updating information is
  73.  buffered as value data for an object's special "updating" property.
  74.  
  75.  Although the main use is to write value data for a value, the buffering routines also
  76.  support I/O directly to and from the container's I/O handlers.  The buffering algorithms
  77.  are basically the same.  The only difference is that in this case a value refNum is not
  78.  supplied.  An example of such a direct handler use would be TOC I/O.
  79.  
  80.  Multiple buffers of different sizes can be set up simultaneously for multiple values.  The
  81.  routines in this file take care of buffering and deblocking as necessary.  Obviously, if
  82.  the I/O handlers are being called directly, there can only be one such buffered use of
  83.  these handlers, unless care is taken to properly protect the file position (seek) 
  84.  pointer(s).
  85.  
  86.  The use of the routines in this package follow a specific protocol as follows ("|" here
  87.  means "or" as an alternative):
  88.  
  89.  For input:
  90.  
  91.              if (setjmp(setJmpEnv)) {
  92.                 cmReleaseIOBuffer(ioBuffer);
  93.                 ERRORx(...)
  94.                 return (failure);
  95.             }
  96.             
  97.             ioBuffer = cmUseIOBuffer(container, bufferSize, &setJmpEnv);
  98.             
  99.             cmNewBufferedInputData(ioBuffer, [valueRefNum], totalAmountToRead);
  100.             cmReadBufferedData(ioBuffer, 1 | 2 | 4);
  101.                        - - -
  102.             
  103.             cmReleaseIOBuffer(ioBuffer);
  104.  
  105.  For output:
  106.   
  107.              if (setjmp(setJmpEnv)) {
  108.                 cmReleaseIOBuffer(ioBuffer);
  109.                 ERRORx(...)
  110.                 return (failure);
  111.             }
  112.  
  113.             ioBuffer = cmUseIOBuffer(container, bufferSize, &setJmpEnv);
  114.             cmNewBufferedOutputData(ioBuffer, [valueRefNum]);
  115.             
  116.             cmWriteBufferedData(ioBuffer, 1 | 2 | 4);
  117.                        - - -
  118.             
  119.             cmFlushOutputBuffer(ioBuffer);
  120.             cmReleaseIOBuffer(ioBuffer);
  121.  
  122.  A setjmp/longjmp environment is defined for both input and output.  The I/O routines
  123.  use this technique rather than having to check for errors on each I/O call.  All I/O is
  124.  beacketed between a cmUseIOBuffer() and cmReleaseIOBuffer().  cmNewBufferedInputData() is
  125.  called for each new value to read to define that value and the total amount to read.
  126.  cmNewBufferedOutputData() just defines the value for output.  cmReadBufferedData() is 
  127.  used to read 1, 2, and 4 byte quantities while cmWriteBufferedData() is used to write
  128.  those quantities.  The write also requires a cmFlushOutputBuffer() at the end to make
  129.  sure the last buffer is written.
  130.  
  131.  There are a few other special calls defined here.  But the above protocal must be 
  132.  followed to do the I/O properly.
  133. */
  134.  
  135. #ifndef __BUFFEREDIO__
  136. #define __BUFFEREDIO__
  137.  
  138. #include <setjmp.h>
  139.  
  140. #ifndef __CMTYPES__
  141. #include "CMTypes.h"
  142. #endif
  143. #ifndef __CM_API_TYPES__
  144. #include "CMAPITyp.h"
  145. #endif
  146.  
  147. struct Container;
  148. struct TOCValueHdr;
  149.  
  150.  
  151.                                                                     CM_CFUNCTIONS
  152.  
  153. void *cmUseIOBuffer(struct Container *container, long maxBufferSize, jmp_buf *ioEnv);
  154.     /*
  155.     This is used to allocate an I/O buffer and its associated control information.  The
  156.     buffer is used to buffer data for input or output using cmReadBufferedData() and
  157.     cmWriteBufferedData() respectively.
  158.     
  159.     The I/O control block pointer allocated is returned as the function result as an
  160.     anonymous "void *" pointer.  The caller should view this as a "buffer pointer" to be
  161.     passed to all the other routines in this file.
  162.     
  163.     An error is reported for allocation errors.  If the error reporter returns, NULL is
  164.     returned as the function result.
  165.     
  166.     The maximum size of the buffer to be allocated is passed.  A set setjmp/longjmp
  167.     environment variable is also passed for read and write error reporting and recovery.  The
  168.     setjmp/longjmp is used rather than have to check for errors on each I/O call of the
  169.     buffered I/O routines.
  170.      
  171.     Note, if the longjmp is taken, it is the caller's responsibility (in the setjmp code) to
  172.     report the error message.  This is done because the buffered I/O is used in a number of
  173.     contexts and a more appopriate error message can be reported by the caller.
  174.     
  175.     The I/O buffer control block allocated is added to a chain whose header is in the
  176.     updating container associated with the specified container.  The buffer should be 
  177.     released when is't use is no longer needed by calling cmReleaseIOBuffer().
  178.     */
  179.     
  180.     
  181. void cmReleaseIOBuffer(void *ioBuffer);
  182.     /*
  183.     This is called to free a buffer, ioBuffer,  allocated by cmUseIOBuffer(). If the caller
  184.     "forgets" to call this routine, then when the container is closed, cmFreeAllIOBuffers()
  185.     will be called to make sure all the buffers are free for that container.
  186.     */
  187.     
  188.  
  189. void cmFreeAllIOBuffers(struct Container *container);
  190.     /*
  191.   This is called at container close time to make sure all buffers allocated for that
  192.   container are released (freed).
  193.     */
  194.  
  195.  
  196. void cmNewBufferedOutputData(void *ioBuffer, struct TOCValueHdr *theValueHdr);
  197.     /*
  198.     This conditions the output buffer, ioBuffer, previously allocated by cmUseIOBuffer(), for
  199.     initial writing of the value data for theValueHdr.  If theValueHdr is NULL, the container
  200.     is written directly with the container's output handler.  This must be called once after
  201.     cmUseIOBuffer() and before any other calls.
  202.     */
  203.     
  204.  
  205. void cmWriteBufferedData(void *ioBuffer, CM_LONG size, CM_ULONG data4);
  206.     /*
  207.     This is called to do buffered writes of 1, 2, or 4 byte data to a container. It is "glue"
  208.     code in the sense that it is the interface to the "format data" handler.  That handler
  209.     actually places the bytes in the buffer.  The buffer used is one returned from a previous
  210.     call to cmUseIOBuffer() and passed as the ioBuffer parameter.
  211.     
  212.     A CM_UCHAR, CM_USHORT, or CM_ULONG is passed in data4 which the handler is expected to
  213.     format into the buffer as 1, 2, or 4 byte quantities respectively.  This is done for
  214.     portability reasons since the architecture we're running this code on might map
  215.     differently into standard container entities.
  216.     
  217.     The expected output size, 1, 2, or 4, is passed, and the value to put into the buffer in
  218.     data4 (always passed as a CM_ULONG).  The buffer is written as value data for the value
  219.     "refNum" passed to cmNewBufferedOutputData() (theValueHdr passed to
  220.     cmNewBufferedOutputData()).  If there is no value data (theValudHdr is NULL), then the
  221.     container's output handler is called directly.  Thus two levels of I/O are available; a
  222.     "high level" through a value refNum, and a "low level" directly using the handler.
  223.     
  224.     If the output size is negative, use its absolutely value. This is use to denote
  225.     endian-ness netural data.
  226.     
  227.     This routine handles writing the buffer as it fills.  If an error is detected, a longjmp
  228.     on the setjmp environment passed to cmUseIOBuffer() is taken.  It is that setjmp code
  229.     which is responsible for reporting the error message.  This is done because the buffered
  230.     I/O routines can be used in a number of contexts.  The caller can report a more
  231.     appropriate error message rather than a more generic one we would have to report from
  232.     here.
  233.  
  234.     Note, for direct handler writes, no seeks are done here.  It is assumed that the output
  235.     is positioned to what is to be written.  If other code does seeks, then that code should
  236.     call cmBufferedIOftell() to reseek to the proper output position.
  237.     */
  238.  
  239.  
  240. #define PUT1(data, io)     cmWriteBufferedData(io, 1, (CM_ULONG)(data))
  241. #define PUT2(data, io)     cmWriteBufferedData(io, 2, (CM_ULONG)(data))
  242. #define PUT4(data, io)     cmWriteBufferedData(io, 4, (CM_ULONG)(data))
  243. #define PUT4Direct(data, io)     cmWriteBufferedData(io, -4, (CM_ULONG)(data))
  244.     /*
  245.     cmWriteBufferedData() is never explicitly called. Rather, these macros are provided to
  246.     expand to cmWriteBufferedData() calls.
  247.     */
  248.     
  249.     
  250. void cmFlushOutputBuffer(void *ioBuffer);
  251.     /*
  252.     This routine is called to make sure that an output buffer (associated with the ioBuffer)
  253.     is flushed, i.e., fully written.  This completes the value data for the value specified
  254.     to cmNewBufferedOutputData(), or simply writes the remaining partial buffer directly if
  255.     the output handler is to be used directly (see cmNewBufferedOutputData() for further
  256.     details).
  257.     */
  258.     
  259.  
  260. void cmNewBufferedInputData(void *ioBuffer, struct TOCValueHdr *theValueHdr,
  261.                                                         CM_ULONG dataSize);
  262.     /*
  263.     This conditions an input buffer, ioBuffer, previously allocated by cmUseIOBuffer(), for
  264.     initial reading up to dataSize bytes from the value data for theValueHdr.  If theValueHdr
  265.     is NULL, the container will be read directly with the container's input handler.  The
  266.     first call to cmReadBufferedData() after this call will cause cmReadBufferedData() to
  267.     reload its buffer with "new" data.  For each new value refNum, call this routine to read
  268.     its data.  If there is no value refNum, call it once after cmUseIOBuffer().  Either way,
  269.     call it before doing the first cmReadBufferedData() or cmBufferedIOftell().
  270.     */
  271.  
  272.     
  273. CM_ULONG cmReadBufferedData(void *ioBuffer, CM_LONG size);
  274.     /*
  275.     This is called to do buffered reads of data from the container.  It is "glue" code in the
  276.     sense that it is the interface to the "extract data" handler.  That handler actually
  277.     copies the bytes from the buffer.  The buffer used is one returned from a previous
  278.     call to cmUseIOBuffer() and passed as the ioBuffer parameter.
  279.     
  280.     The handler is expected to extract 1, 2, or 4 byte quantities from the buffer and place
  281.     them in a CM_UCHAR, CM_USHORT, or CM_ULONG respectively.  This is done for portability
  282.     reasons since the architecture we're running this code on might map differently into 
  283.     standard container entities.
  284.     
  285.     The buffer is read as value data for the passed value "refNum" passed to the most recent
  286.     call to cmNewBufferedInputData().  The expected input size, 1, 2, or 4, is passed, and
  287.     the value returned as the function result (always as a CM_ULONG).
  288.  
  289.     The expected input size, 1, 2, or 4, is passed, and the value returned as the function
  290.     result (always as a CM_ULONG).  The buffer is read as value data for value "refNum" 
  291.     passed to cmNewBufferedInputData() (theValueHdr passed to cmNewBufferedInputData()).  If
  292.     there is no value data (theValueHdr is NULL), then the container's input handler is
  293.     called directly.  Thus two levels of I/O are available; a "high level" through a value
  294.     refNum, and a "low level" directly using the handler.
  295.     
  296.     If the input size is negative, use its absolutely value. This is use to denote
  297.     endian-ness netural data.
  298.     
  299.     This routine handles reading the buffer as all its data is extracted.  If an error is
  300.     detected, a longjmp on the setjmp environment passed to cmUseIOBuffer() is taken.  It is
  301.     that setjmp code which is responsible for reporting the error message.  This is done
  302.     because the buffered I/O routines can be used in a number of contexts.  The caller can
  303.     report a more appropriate error message rather than a more generic one we would have to
  304.     report from here.
  305.     
  306.     Note, the caller MUST call cmNewBufferedInputData() prior to the first call of
  307.     cmReadBufferedData() to cause the buffer to be loaded the first time and to get the
  308.     value refNum.  cmNewBufferedInputData() should be used any time a new value refNum is to
  309.     be used to read new data. 
  310.     
  311.     Also note, for direct handler reads, no seeks are done here.  It is assumed that the
  312.     input is positioned to what is to be read.  If other code does seeks, then that code
  313.     should call cmBufferedIOftell() to reseek to the proper input position.
  314.     */
  315.     
  316.     
  317. #define GET1(io) ((CM_UCHAR)cmReadBufferedData(io,  1))
  318. #define GET2(io) ((CM_USHORT)cmReadBufferedData(io, 2))
  319. #define GET4(io) ((CM_ULONG)cmReadBufferedData(io,  4))
  320. #define GET4Direct(io) ((CM_ULONG)cmReadBufferedData(io,  -4))
  321.     /*
  322.     cmReadBufferedData() is never explicitly called.  Rather, these macros are provided to
  323.     expand to cmReadBufferedData() calls.
  324.     */
  325.     
  326.     
  327. CM_ULONG cmBufferedIOftell(void *ioBuffer);
  328.     /*
  329.     This returns the current I/O position from the time cmNewBufferedOutputData() or 
  330.     cmNewBufferedInputData() was called.  For I/O to value data, the position is a value
  331.     data offset (initially always 0).  For direct handler I/O, the position is a container
  332.     offset.  This was set at the time cmNewBufferedOutputData() or cmNewBufferedInputData()
  333.     was called.  The position is updated as buffers fill and are written or reloaded when
  334.     reading.
  335.     
  336.     This routine is needed when only when there is the possibility that other code might be
  337.     doing "seeks" to the same container behind the buffered I/O routine's back!  Code doing
  338.     such seeks must be able to reseek the container position according to the value returned
  339.     here.  For value refNums, this usually is not necessary, since everything is in terms of
  340.     the value data offset rather than a container offset.  But this routine, for completeness,
  341.     will return the appropriate offset position the I/O wants to use.
  342.     */
  343.  
  344.  
  345.                                                           CM_END_CFUNCTIONS
  346. #endif
  347.