home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / opendc12.zip / od124os2.exe / od12osr1.exe / src / BufferIO.c < prev    next >
C/C++ Source or Header  |  1997-03-21  |  29KB  |  636 lines
  1. /* @(#)Z 1.4 com/src/cm/BufferIO.c, odstorage, od96os2, odos29712d 97/03/21 17:19:22 (96/10/29 09:15:41) */
  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.c
  31.  
  32.     Contains:    Container Manager Buffered Data I/O Routines
  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 BufferIO should use value's
  43.                                     container and not the updating container to
  44.                                     determine endian-ness.
  45.          <1>      2/3/94    EL        first checked in
  46.  
  47.     To Do:
  48. */
  49.  
  50. /*---------------------------------------------------------------------------*
  51.  |                                                                           |
  52.  |                            <<<  BufferIO.c  >>>                           |
  53.  |                                                                           |
  54.  |               Container Manager Buffered Data I/O Routines                |
  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 contains 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 container I/O 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 | NULL, 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 | NULL);
  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.  
  136. #include <stddef.h>
  137. #include <stdio.h>
  138. #include <string.h>
  139. #include <setjmp.h>
  140.  
  141. #ifndef __CMTYPES__
  142. #include "CMTypes.h"
  143. #endif
  144. #ifndef __CM_API_TYPES__
  145. #include "CMAPITyp.h"
  146. #endif
  147. #ifndef __CM_API__
  148. #include "CMAPI.h"
  149. #endif
  150. #ifndef __LISTMGR__
  151. #include "ListMgr.h"
  152. #endif
  153. #ifndef __TOCENTRIES__
  154. #include "TOCEnts.h"   
  155. #endif
  156. #ifndef __TOCOBJECTS__
  157. #include "TOCObjs.h"   
  158. #endif
  159. #ifndef __CONTAINEROPS__
  160. #include "Containr.h"  
  161. #endif
  162. #ifndef __HANDLERS__
  163. #include "Handlers.h"
  164. #endif
  165. #ifndef __SESSIONDATA__
  166. #include "Session.h"          
  167. #endif
  168. #ifndef __ERRORRPT__
  169. #include "ErrorRpt.h"      
  170. #endif
  171. #ifndef __UTILITYROUTINES__
  172. #include "Utility.h"        
  173. #endif
  174. #ifndef __BUFFEREDIO__
  175. #include "BufferIO.h"  
  176. #endif
  177.  
  178.                                                                     CM_CFUNCTIONS
  179.  
  180. /* The following generates a segment directive for Mac only due to 32K Jump Table             */
  181. /* Limitations.  If you don't know what I'm talking about don't worry about it.  The        */
  182. /* default is not to generate the pragma.  Theoritically unknown pragmas in ANSI won't    */
  183. /* choke compilers that don't recognize them.  Besides why would they be looked at if        */
  184. /* it's being conditionally skipped over anyway?  I know, famous last words!                        */
  185.  
  186. #if CM_MPW
  187. #pragma segment BufferedIO
  188. #endif
  189.  
  190.  
  191. /* All I/O buffers are linked together on a chain attached to a container. The buffers    */
  192. /* are actually part of an "I/O control block" defined below.  This information is only    */
  193. /* known to this file.  All callers to the routines here only know it as an anonymous        */
  194. /* "void *" pointer.                                                                                                                                        */
  195.  
  196. struct IOControl {                                                /* Layout of an I/O control block:                        */
  197.     ListLinks                 ioLinks;                                /*    in-use buffers links (must be first)        */
  198.     TOCValueHdrPtr    theValueHdr;                        /*        refNum whose value data to do I/O on        */
  199.     ContainerPtr         container;                            /*        (updating) container control block ptr    */
  200.     CM_LONG                     maxBufSize;                            /*        max size of the buffer                                    */
  201.     CM_LONG                  bufferPosition;                    /*        0-rel. next byte to use in updateBuffer    */
  202.     CM_LONG                     bufferReadOffset;                /*        offset to next buffer to read in value    */
  203.     CM_ULONG                 dataSize;                                /*        total size of data to be read                        */
  204.     CM_ULONG                 ioPos;                                    /*        current container I/O position                    */
  205.     union {                                                                    /*        setjmp environment for buffered I/O            */
  206.         jmp_buf                jmpBuf;                                    /*              *** PORTABILITY PROBLEM ***                */
  207.         CM_CHAR                firstByte;                            /*       Don't assume the layout of a jmp_buf    */
  208.     } bufferIOEnv;                                                    /*             firstByte used to memcpy to  jmp_buf    */
  209.     CM_CHAR                  dataBuffer[1];                    /*         the START of the data I/O buffer                */
  210. };
  211. typedef struct IOControl IOControl, *IOControlPtr;
  212.  
  213. /* CAUTION: I/O error "recovery" here is done by using a longjmp on a setjmp environment*/
  214. /*                     passed to cmUseIOBuffer() below.  In order to save that environment, a             */
  215. /*                    memcpy() is done to copy the cmUseIOBuffer() parameter to the above struct.    */
  216. /*                    No assumptions are made about the layout of a setjmp's jmp_buf!  For                 */
  217. /*                    example, it is never assumed to be an array.  Therefore, in order to                 */
  218. /*                     PORTABLY pass the jmp_buf address to a memcpy(), a union is done to the         */
  219. /*                     first byte of the jmp_buf to address it.  To some "picky" compilers (in            */
  220. /*                    particular, the Zortech MPW C/C++ compiler), addressing the first byte of a */
  221. /*                     jmp_buf which IS an array as "&foo" is treated as an error (it expects             */
  222. /*                    "&foo[0]" -- I always thought this was benign).  To avoid such problems,         */
  223. /*                     the above "kludge" is used.                                                                                                 */
  224.  
  225.  
  226. /*----------------------------------------*
  227.  | cmUseIOBuffer - allocate an I/O buffer |
  228.  *----------------------------------------*
  229.  
  230.  This is used to allocate an I/O buffer and its associated control information.  The
  231.  buffer is used to buffer data for input or output using cmReadBufferedData() and
  232.  cmWriteBufferedData() respectively.
  233.  
  234.  The I/O control block pointer allocated is returned as the function result as an
  235.  anonymous "void *" pointer.  The caller should view this as a "buffer pointer" to be
  236.  passed to all the other routines in this file.
  237.  
  238.  An error is reported for allocation errors.  If the error reporter returns, NULL is
  239.  returned as the function result.
  240.  
  241.  The maximum size of the buffer to be allocated is passed.  A set setjmp/longjmp
  242.  environment variable is also passed for read and write error reporting and recovery.  The
  243.  setjmp/longjmp is used rather than have to check for errors on each I/O call of the
  244.  buffered I/O routines.
  245.   
  246.  Note, if the longjmp is taken, it is the caller's responsibility (in the setjmp code) to
  247.  report the error message.  This is done because the buffered I/O is used in a number of
  248.  contexts and a more appopriate error message can be reported by the caller.
  249.  
  250.  The I/O buffer control block allocated is added to a chain whose header is in the
  251.  updating container associated with the specified container.  The buffer should be 
  252.  released when is't use is no longer needed by calling cmReleaseIOBuffer().
  253. */
  254.  
  255. void *cmUseIOBuffer(ContainerPtr container, long maxBufferSize, jmp_buf *ioEnv)
  256. {
  257.     IOControlPtr io;
  258.     
  259.     /* The actual buffer allocated is 4 greater than the size required. This is enough of */
  260.     /* a pad (actually we use sizeof(CM_ULONG)) to allow cmWriteBufferData to always have    */
  261.     /* room to write the data just added.                                                                                                    */
  262.     
  263.     if ((io = (IOControlPtr)CMmalloc(sizeof(IOControl) + maxBufferSize +  sizeof(CM_ULONG))) == NULL) {
  264.         ERROR1(CM_err_NoDataBuffer, CONTAINERNAME);
  265.         return (NULL);
  266.     }
  267.     
  268.     io->container             = container;                                        /* remember the container                        */
  269.     io->maxBufSize         = maxBufferSize;                                /* remember how big a buffer we got    */
  270.     memcpy(&io->bufferIOEnv.firstByte, ioEnv, sizeof(jmp_buf)); /* remember setjmp env.        */
  271.     
  272.     io->bufferPosition = 0;                                                        /* init buffer index for output            */
  273.     
  274.     return ((void *)cmAppendListCell(&io->container->updatingContainer->activeIOBuffers, io));
  275. }
  276.  
  277.  
  278. /*--------------------------------------------------*
  279.  | cmReleaseIOBuffer - release (free) an I/O buffer |
  280.  *--------------------------------------------------*
  281.  
  282.  This is called to free a buffer, ioBuffer,  allocated by cmUseIOBuffer(). If the caller
  283.  "forgets" to call this routine, then when the container is closed, cmFreeAllIOBuffers()
  284.  will be called to make sure all the buffers are free for that container.
  285. */
  286.  
  287. void cmReleaseIOBuffer(void *ioBuffer)
  288. {
  289.     ContainerPtr container;
  290.     
  291.     if (ioBuffer != NULL) {
  292.         container = ((IOControlPtr)ioBuffer)->container->updatingContainer;
  293.         CMfree(cmDeleteListCell(&container->activeIOBuffers, ioBuffer));/*unlink/free buffer*/
  294.     }
  295. }
  296.  
  297.  
  298. /*---------------------------------------------------------------------*
  299.  | cmFreeAllIOBuffers - free all I/O buffers allocated for a container |
  300.  *---------------------------------------------------------------------*
  301.  
  302.  This is called at container close time to make sure all buffers allocated for that
  303.  container are released (freed).
  304. */
  305.  
  306. void cmFreeAllIOBuffers(ContainerPtr container)
  307. {
  308.     IOControlPtr io, next;
  309.     
  310.     io = (IOControlPtr)cmGetListHead(&container->updatingContainer->activeIOBuffers);
  311.  
  312.     while (io) {                                                                    /* free all buffers still chained...        */
  313.         next = (IOControlPtr)cmGetNextListCell(io);
  314.         CMfree(io);
  315.         io = next;
  316.     }
  317. }
  318.  
  319.  
  320. /*------------------------------------------------------------*
  321.  | cmNewBufferedOutputData - initialize for buffered writing  |
  322.  *------------------------------------------------------------*
  323.  
  324.  This conditions the output buffer, ioBuffer, previously allocated by cmUseIOBuffer(), for
  325.  initial writing of the value data for theValueHdr.  If theValueHdr is NULL, the container
  326.  is written directly with the container's output handler.  This must be called once after
  327.  cmUseIOBuffer() and before any other calls.
  328. */
  329.  
  330. void cmNewBufferedOutputData(void *ioBuffer, TOCValueHdrPtr theValueHdr)
  331. {
  332.     IOControlPtr io = (IOControlPtr)ioBuffer;
  333.         
  334.     io->bufferPosition = 0;                                                        /* init buffer index for output            */
  335.     io->theValueHdr    = theValueHdr;                                    /* remember refNum (if any)                    */
  336.     io->ioPos             = (theValueHdr != NULL) ? 0UL     /* remember where we are                        */
  337.                                                                                          : (CM_ULONG)CMftell(io->container->updatingContainer);
  338. }
  339.  
  340.  
  341. /*----------------------------------------------------------*
  342.  | cmWriteBufferedData - write 1, 2, or 4 bytes to a buffer |
  343.  *----------------------------------------------------------*
  344.  
  345.  This is called to do buffered writes of 1, 2, or 4 byte data to a container. It is "glue"
  346.  code in the sense that it is the interface to the "format data" handler.  That handler
  347.  actually places the bytes in the buffer.  The buffer used is one returned from a previous
  348.  call to cmUseIOBuffer() and passed as the ioBuffer parameter.
  349.  
  350.  A CM_UCHAR, CM_USHORT, or CM_ULONG is passed in data4 which the handler is expected to
  351.  format into the buffer as 1, 2, or 4 byte quantities respectively.  This is done for
  352.  portability reasons since the architecture we're running this code on might map
  353.  differently into standard container entities.
  354.  
  355.  The expected output size, 1, 2, or 4, is passed, and the value to put into the buffer in
  356.  data4 (always passed as a CM_ULONG).  The buffer is written as value data for the value
  357.  "refNum" passed to cmNewBufferedOutputData() (theValueHdr passed to
  358.  cmNewBufferedOutputData()).  If there is no value data (theValudHdr is NULL), then the
  359.  container's output handler is called directly.  Thus two levels of I/O are available; a
  360.  "high level" through a value refNum, and a "low level" directly using the handler.
  361.  
  362. If the output size is negative, use its absolutely value. This is use to denote
  363. endian-ness netural data.
  364.     
  365.  This routine handles writing the buffer as it fills.  If an error is detected, a longjmp
  366.  on the setjmp environment passed to cmUseIOBuffer() is taken.  It is that setjmp code
  367.  which is responsible for reporting the error message.  This is done because the buffered
  368.  I/O routines can be used in a number of contexts.  The caller can report a more
  369.  appropriate error message rather than a more generic one we would have to report from
  370.  here.
  371.  
  372.  Note, for direct handler writes, no seeks are done here.  It is assumed that the output
  373.  is positioned to what is to be written.  If other code does seeks, then that code should
  374.  call cmBufferedIOftell() to reseek to the proper output position.
  375. */
  376.  
  377. void cmWriteBufferedData(void *ioBuffer, CM_LONG size, CM_ULONG data4)
  378. {
  379.     IOControlPtr     io                = (IOControlPtr)ioBuffer;
  380.     ContainerPtr     container = io->container;
  381.     CM_UCHAR             data1;
  382.     CM_USHORT             data2;
  383.     CMPrivateData d;
  384.     CM_LONG                realSize = size;
  385.     
  386.     if (realSize < 0)                                                            /* use the absolute value                                */
  387.         realSize = -realSize;
  388.     
  389.     /* As documented in the handlers, a pointer to the data to be placed in the buffer is    */
  390.     /* passed, and the handler can assume that pointer is pointing to a CM_UCHAR if size     */
  391.     /* is 1, CM_USHORT if size is 2, and CM_ULONG if size if 4.  So, not to be liers, we     */
  392.     /* set up a pointer to exactly that.                                                                                                    */
  393.     
  394.     if (realSize == 1) {                                                    /* 1 ==> pointer to CM_UCHAR                        */
  395.         data1 = (CM_UCHAR)data4;
  396.         d = (CMPrivateData)&data1;
  397.     } else if (realSize == 2) {                                        /* 2 ==> pointer to CM_USHORT                        */
  398.         data2 = (CM_USHORT)data4;
  399.         d = (CMPrivateData)&data2;
  400.     } else                                                                                /* 4 ==> pointer to CM_ULONG                        */
  401.         d = (CMPrivateData)&data4;
  402.     
  403.     /* Now we can put the data into the buffer using the handler...                                                */
  404.     
  405.     CMformatData(container, io->dataBuffer + io->bufferPosition, size, d);
  406.     
  407.     /* Bump the buffer offset. The max offset imposed on the buffer is actully at least 4    */
  408.     /* bytes less than the true maximum buffer size allocated because we had bumped up the*/
  409.     /* allocation by 4 bytes.  This means that the next free byte    could be passed                    */ 
  410.     /* maxBufSize without overruning the buffer.  At that point we write the buffer as         */
  411.     /* (value) data and reset the offset.  By doing this we never have to worry about not */
  412.     /* being able to write 2 or 4 bytes to the buffer.  We also document in the handler     */
  413.     /* that we always guarantee enough space in the buffer. The artifical limit does that.*/
  414.     
  415.     io->bufferPosition += realSize;                            /* update offset to the next free byte        */
  416.     
  417.     /* If the buffer needs flushing, now's the time to do it...                                                        */
  418.     
  419.     if (io->bufferPosition >= io->maxBufSize)        /* flush if full                                                     */
  420.         cmFlushOutputBuffer(ioBuffer);
  421. }
  422.  
  423.  
  424. /*----------------------------------------------*
  425.  | cmFlushOutputBuffer - flush an output buffer |
  426.  *----------------------------------------------*
  427.  
  428.  This routine is called to make sure that an output buffer (associated with the ioBuffer)
  429.  is flushed, i.e., fully written.  This completes the value data for the value specified
  430.  to cmNewBufferedOutputData(), or simply writes the remaining partial buffer directly if
  431.  the output handler is to be used directly (see cmNewBufferedOutputData() for further
  432.  details).
  433.  
  434.  Note, internally, this routine is also called from cmWriteBufferedData() when the buffer
  435.  fills.
  436. */
  437.  
  438. void cmFlushOutputBuffer(void *ioBuffer)
  439. {
  440.     IOControlPtr     io = (IOControlPtr)ioBuffer;
  441.     ContainerPtr     container = io->container->updatingContainer;
  442.  
  443.     if (io->bufferPosition > 0) {                                                /* flush if somthing to flush            */
  444.         if (io->theValueHdr != NULL) {                                        /* high or low level I/O ?                */
  445.             CMWriteValueData((CMValue)io->theValueHdr, (CMPtr)io->dataBuffer,
  446.                                              (CMCount)io->theValueHdr->size, (CMSize)io->bufferPosition);
  447.             io->ioPos += io->bufferPosition;                                /* update output position                    */
  448.         } else if (CMfwrite(container, io->dataBuffer, sizeof(CM_UCHAR), io->bufferPosition) == (CMSize)io->bufferPosition) {
  449.             io->ioPos = (CM_ULONG)CMftell(container);    /* get "true" container position    */
  450.             if (io->ioPos > container->physicalEOF)                 /* make sure of EOF settings...        */
  451.                 container->physicalEOF = io->ioPos;
  452.             SetLogicalEOF(container->physicalEOF);
  453.         } else                                                                                        /* take longjmp if output error        */
  454.             longjmp(io->bufferIOEnv.jmpBuf, 1);
  455.                 
  456.         io->bufferPosition = 0;                                                        /* the buffer is now empty                */
  457.     }
  458. }
  459.  
  460.  
  461. /*----------------------------------------------------------*
  462.  | cmNewBufferedInputData - initialize for buffered reading |
  463.  *----------------------------------------------------------*
  464.  
  465.  This conditions an input buffer, ioBuffer, previously allocated by cmUseIOBuffer(), for
  466.  initial reading up to dataSize bytes from the value data for theValueHdr.  If theValueHdr
  467.  is NULL, the container will be read directly with the container's input handler.  The
  468.  first call to cmReadBufferedData() after this call will cause cmReadBufferedData() to
  469.  reload its buffer with "new" data.  For each new value refNum, call this routine to read
  470.  its data.  If there is no value refNum, call it once after cmUseIOBuffer().  Either way,
  471.  call it before doing the first cmReadBufferedData() or cmBufferedIOftell().
  472. */
  473.  
  474. void cmNewBufferedInputData(void *ioBuffer, TOCValueHdrPtr theValueHdr,
  475.                                                         CM_ULONG dataSize)
  476. {
  477.     IOControlPtr io = (IOControlPtr)ioBuffer;
  478.     
  479.     io->bufferPosition   =  (io->maxBufSize);                    /* pretend we're at end of buffer        */
  480.     io->bufferReadOffset = -(io->maxBufSize);                    /* 1st refNum offset to will be 0        */        
  481.     io->theValueHdr        = theValueHdr;                                /* remember refNum (if any)                    */
  482.     io->dataSize                 = dataSize;                                    /* and max amount to read                        */
  483.     io->ioPos               = (theValueHdr != NULL) ? 0UL/* remember where we are                        */
  484.                                                                                          : (CM_ULONG)CMftell(io->container->updatingContainer);
  485. }
  486.  
  487.  
  488. /*----------------------------------------------------------*
  489.  | cmReadBufferedData - read 1, 2, or 4 bytes from a buffer |
  490.  *----------------------------------------------------------*
  491.  
  492.  This is called to do buffered reads of data from the container.  It is "glue" code in the
  493.  sense that it is the interface to the "extract data" handler.  That handler actually
  494.  copies the bytes from the buffer.  The buffer used is one returned from a previous
  495.  call to cmUseIOBuffer() and passed as the ioBuffer parameter.
  496.  
  497.  The handler is expected to extract 1, 2, or 4 byte quantities from the buffer and place
  498.  them in a CM_UCHAR, CM_USHORT, or CM_ULONG respectively.  This is done for portability
  499.  reasons since the architecture we're running this code on might map differently into 
  500.  standard container entities.
  501.  
  502.  The buffer is read as value data for the passed value "refNum" passed to the most recent
  503.  call to cmNewBufferedInputData().  The expected input size, 1, 2, or 4, is passed, and
  504.  the value returned as the function result (always as a CM_ULONG).
  505.  
  506.  The expected input size, 1, 2, or 4, is passed, and the value returned as the function
  507.  result (always as a CM_ULONG).  The buffer is read as value data for value "refNum" 
  508.  passed to cmNewBufferedInputData() (theValueHdr passed to cmNewBufferedInputData()).  If
  509.  there is no value data (theValueHdr is NULL), then the container's input handler is
  510.  called directly.  Thus two levels of I/O are available; a "high level" through a value
  511.  refNum, and a "low level" directly using the handler.
  512.  
  513.  If the input size is negative, use its absolutely value. This is use to denote
  514.  endian-ness netural data.
  515.     
  516.  This routine handles reading the buffer as all its data is extracted.  If an error is
  517.  detected, a longjmp on the setjmp environment passed to cmUseIOBuffer() is taken.  It is
  518.  that setjmp code which is responsible for reporting the error message.  This is done
  519.  because the buffered I/O routines can be used in a number of contexts.  The caller can
  520.  report a more appropriate error message rather than a more generic one we would have to
  521.  report from here.
  522.  
  523.  Note, the caller MUST call cmNewBufferedInputData() prior to the first call of
  524.  cmReadBufferedData() to cause the buffer to be loaded the first time and to get the
  525.  value refNum.  cmNewBufferedInputData() should be used any time a new value refNum is to
  526.  be used to read new data. 
  527.  
  528.  Also note, for direct handler reads, no seeks are done here.  It is assumed that the
  529.  input is positioned to what is to be read.  If other code does seeks, then that code
  530.  should call cmBufferedIOftell() to reseek to the proper input position.
  531. */
  532.  
  533. CM_ULONG cmReadBufferedData(void *ioBuffer, CM_LONG size)
  534. {
  535.     IOControlPtr     io                = (IOControlPtr)ioBuffer;
  536.     ContainerPtr     container = io->container;
  537.     CM_UCHAR             data1;
  538.     CM_USHORT             data2;
  539.     CM_ULONG             data4;
  540.     CMPrivateData d;
  541.     CMSize                 bufSize, amountRead;
  542.     CM_LONG             nextPos, remaining;
  543.     CM_LONG                realSize = size;
  544.     
  545.     if (realSize < 0)                                                            /* use the absolute value                                */
  546.         realSize = -realSize;
  547.     
  548.     /* Compute the buffer offset of the NEXT byte we will read AFTER the 1, 2, or 4 bytes    */
  549.     /* we are about to read.  Knowing this tells us whether all the bytes we need are in     */
  550.     /* buffer.  If they are not the buffer must be reloaded.                                                            */
  551.     
  552.     nextPos = io->bufferPosition + realSize;                /* next byte to read after this one        */
  553.     
  554.     if (nextPos > io->maxBufSize) {                                    /* reload if all bytes not available    */
  555.         io->bufferReadOffset += io->bufferPosition;        /* next value offset                                    */
  556.         remaining = io->dataSize - io->bufferReadOffset;    /* data left to read                            */
  557.         bufSize     = (remaining > io->maxBufSize) ? (CMSize)io->maxBufSize : (CMSize)remaining;
  558.         
  559.         if (io->theValueHdr != NULL)
  560.             amountRead = CMReadValueData((CMValue)io->theValueHdr, (CMPtr)io->dataBuffer,
  561.                                                                      (CMCount)io->bufferReadOffset, bufSize);
  562.         else {
  563.             io->ioPos += io->bufferPosition;                        /* we will reread unprocessed stuff        */
  564.             CMfseek(container->updatingContainer, io->ioPos, kCMSeekSet);
  565.             amountRead = CMfread(container->updatingContainer, io->dataBuffer, sizeof(CM_UCHAR), bufSize);
  566.         }
  567.         
  568.         if (amountRead != bufSize || amountRead == 0) {
  569.             io->bufferReadOffset = io->dataSize;                 /* safety                                                            */
  570.             longjmp(io->bufferIOEnv.jmpBuf, 2);
  571.         }
  572.         
  573.         io->ioPos += amountRead;                                            /* update input position                            */
  574.         io->bufferPosition = 0;                                                /* reset the buffer offset                        */
  575.         nextPos = (CM_LONG)realSize;                                    /* reset the next offset after that        */
  576.     }
  577.     
  578.     /* As documented in the handlers, a pointer to the data to be extracted from the             */
  579.     /* buffer is passed, and the handler can assume that pointer is pointing to a CM_UCHAR*/
  580.     /* if size is 1, CM_USHORT if size is 2, and CM_ULONG if size if 4.  It is also             */
  581.     /* documented that the handler need not worry that all the bytes are available in the    */
  582.     /* buffer.  We took care of that problem above.                                                                                */
  583.  
  584.     if (realSize == 1)                                                             /* 1 ==> pointer to CM_UCHAR                    */
  585.         d = (CMPrivateData)&data1;    
  586.     else if (realSize == 2)                                                    /* 2 ==> pointer to CM_USHORT                    */
  587.         d = (CMPrivateData)&data2;
  588.     else                                                                                        /* 4 ==> pointer to CM_ULONG                    */
  589.         d = (CMPrivateData)&data4;
  590.     
  591.     /* Now we can extract the data from the buffer using the handler...                                        */
  592.         
  593.     CMextractData(container, io->dataBuffer + io->bufferPosition, size, d);
  594.     
  595.     /* The data is always returned as the function result as a CM_ULONG.  Thus, for size     */
  596.     /* 1 and 2, we must up-convert the value...                                                                                        */
  597.     
  598.     if (realSize == 1)
  599.         data4 = (CM_ULONG)data1;
  600.     else if (realSize == 2)
  601.         data4 = (CM_ULONG)data2;
  602.     
  603.     /* Set the offset to the next byte to read in the buffer and return the value...            */
  604.     
  605.     io->bufferPosition = nextPos;                                        /* offset to next byte to read                */
  606.     
  607.     return (data4);                                                                    /* give caller back data as a CM_ULONG*/
  608. }
  609.  
  610.  
  611. /*-------------------------------------------------*
  612.  | cmBufferedIOftell - return current I/O position |
  613.  *-------------------------------------------------*
  614.  
  615.  This returns the current I/O position from the time cmNewBufferedOutputData() or 
  616.  cmNewBufferedInputData() was called.  For I/O to value data, the position is a value
  617.  data offset (initially always 0).  For direct handler I/O, the position is a container
  618.  offset.  This was set at the time cmNewBufferedOutputData() or cmNewBufferedInputData()
  619.  was called.  The position is updated as buffers fill and are written or reloaded when
  620.  reading.
  621.  
  622.  This routine is needed when only when there is the possibility that other code might be
  623.  doing "seeks" to the same container behind the buffered I/O routine's back!  Code doing
  624.  such seeks must be able to reseek the container position according to the value returned
  625.  here.  For value refNums, this usually is not necessary, since everything is in terms of
  626.  the value data offset rather than a container offset. But this routine, for completeness,
  627.  will return the appropriate offset position the I/O wants to use.
  628. */
  629.  
  630. CM_ULONG cmBufferedIOftell(void *ioBuffer)
  631. {
  632.     return (((IOControlPtr)ioBuffer)->ioPos);
  633. }
  634.  
  635.                                                             CM_END_CFUNCTIONS
  636.