home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / CONTAINR.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  15KB  |  315 lines
  1. /* @(#)Z 1.5 com/src/cm/Containr.h, odstorage, od96os2, odos29646d 96/11/15 15:27:03 (96/10/29 09:17: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:         Containr.h 
  31.  
  32.     Contains:    Container Manager Containers Interfaces
  33.  
  34.     Written by:    Ira L. Ruben
  35.  
  36.     Owned by:    Ed Lai
  37.  
  38.     Copyright:    ⌐ 1991-1994 by Apple Computer, Inc., all rights reserved.
  39.  
  40.     Change History (most recent first):
  41.  
  42.          <3>     9/30/94    EL        #1182275 rename mergeCandidate to
  43.                                     updateMergeCandidate.
  44.          <2>     8/26/94    EL        #1182275 Add new field mergeCandidate to
  45.                                                     the container struct.
  46.          <4>      5/5/94    EL        Minor version one for new data format not
  47.                                                     supported in 2.0.
  48.          <3>     3/31/94    EL        Add field mergeInSize to container.
  49.                                                     #1150214
  50.          <2>     3/17/94    EL        Add support in container data structure for
  51.                                                     delete garbage and truncate back to
  52.                                                     original size.
  53.          <1>      2/3/94    EL        first checked in
  54.          <2>     1/19/94    EL        Add tmpFreeList to container.
  55.  
  56.     To Do:
  57. */
  58.  
  59. /*---------------------------------------------------------------------------*
  60.  |                                                                           |
  61.  |                            <<<  Containr.h  >>>                           |
  62.  |                                                                           |
  63.  |                  Container Manager Containers Interfaces                  |
  64.  |                                                                           |
  65.  |                               Ira L. Ruben                                |
  66.  |                                 12/02/91                                  |
  67.  |                                                                           |
  68.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  69.  |                           All rights reserved.                            |
  70.  |                                                                           |
  71.  *---------------------------------------------------------------------------*
  72.  
  73.  This header defines the container control block and some common info about the container
  74.  label.  Everyone includes this thing since it acts as the "global variable" data space
  75.  tied to each individual opened or embedded container.
  76. */
  77.  
  78. #ifndef __CONTAINEROPS__
  79. #define __CONTAINEROPS__
  80.  
  81. #include <setjmp.h>
  82.  
  83. /*------------------------------------------------------------------------------------*
  84.  | W A R N I N G - - -> this header as well as  TOCObjs.h   and  TOCEnts.h   all have |
  85.  |                      mutual references.  The include order is NOT arbitrary.  It's |
  86.  |                      the only one that works!  Even with it we have to do some     |
  87.  |                      forward struct pointer references of the form "struct foo *p" |
  88.  *------------------------------------------------------------------------------------*/
  89.  
  90. #ifndef __CMTYPES__
  91. #include "CMTypes.h"
  92. #endif
  93. #ifndef __CM_API_TYPES__
  94. #include "CMAPITyp.h"
  95. #endif
  96. #ifndef __LISTMGR__
  97. #include "ListMgr.h"
  98. #endif
  99. #ifndef __HANDLERS__
  100. #include "Handlers.h"
  101. #endif
  102. #ifndef __SESSIONDATA__
  103. #include "Session.h"          
  104. #endif
  105. #ifndef __TOCENTRIES__
  106. #include "TOCEnts.h"   
  107. #endif
  108. #ifndef __TOCOBJECTS__
  109. #include "TOCObjs.h"   
  110. #endif
  111.  
  112.                                    CM_CFUNCTIONS
  113.  
  114. struct SessionGlobalData;
  115. struct Container;
  116. struct TOCObject;
  117. struct TOCValueHdr;
  118. struct TOCValue;
  119. struct EmbeddedContainer;
  120. struct GlobalName;
  121.  
  122.  
  123. #define MagicByteSequence "\xA4""CM""\xA5""Hdr""\xD7"        /* Must be 8 characters                    */
  124.  
  125. #define MajorVersion            2                                                            /* major format version number    */
  126. #define MinMinorVersion        0                                                            /* min minor format version       */
  127. #define MinorVersion            1                                                            /* minor format version number    */
  128.  
  129. #define MinStdObjectID        CM_StdObjID_MinGeneralID            /* min standard object id                */
  130. #define MinUserObjectID        0x00010000UL                                    /* min user object id                        */
  131.  
  132. #define IsStdObject(id)        (((id) & 0xFFFF0000UL) == 0)     /* tests for ID type                        */
  133. #define IsUserObject(id)     (((id) & 0xFFFF0000UL) != 0)
  134.  
  135. /* the default and the minimum acceptable generation number is 1                                                */            
  136. #define kCMDefaultGeneration    1                                                    /* the default generation             */
  137.  
  138. /* The following is used to test for updating modes that use one container to update         */
  139. /* another...                                                                                                                                                        */
  140.  
  141. #define UPDATING(updatingContainer) (((updatingContainer)->useFlags & (kCMUpdateTarget | kCMUpdateByAppend)) != 0)
  142.  
  143. /* The following macro is used to see if touched records are to be generated...                    */
  144.  
  145. #define TouchIt(updatingContainer, container) (updatingContainer->touchTheValue     && \
  146.                                                                                              (updatingContainer) != (container) && \
  147.                                                                                              UPDATING(updatingContainer))
  148.  
  149.  
  150.                                                 /*-------------------------------*
  151.                                                  | The "Container Control Block" |
  152.                                                  *-------------------------------*/
  153.  
  154. struct Container {                                                /* Layout for a "Container Control Block":        */
  155.     ListLinks                        containerLinks;            /*    in-use Containers links (must be first)    */
  156.     struct Container        *thisContainer;            /*         validation check on the container ptr        */
  157.     
  158.     struct SessionGlobalData *sessionData;    /*         pointer of session (task) global data        */
  159.     
  160.     struct Container        *updatingContainer;    /*        ptr to container recording new updates    */
  161.     CM_USHORT                        depth;                            /*        target container "depth"                                */
  162.     CMBoolean                        openingTarget;            /*        true ==> updater is opening target            */
  163.     CMBoolean                        updateMergeCandidate;    /*        true ==> container may be merged            */
  164.     
  165.     struct Container        *targetContainer;        /*        ptr to container being updated or used    */
  166.     CMValue                            pointingValue;            /*        refNum of container's pointing value        */
  167.     
  168.     HandlerOps                     handler;                        /*         handler basic operations vector                    */
  169.     MetaHandlerPtr             metaHandlerProc;        /*        ptr to type and "metahandler" proc            */
  170.     CMRefCon                          refCon;                            /*         handler's refCon                                                */
  171.     
  172.     unsigned char                magicBytes[10];            /*        magic byte sequence                                            */
  173.     CM_USHORT                        majorVersion;                /*         major format version                                        */
  174.     CM_USHORT                        minorVersion;                /*        minor format version                                        */
  175.     
  176.     CM_USHORT                         containerFlags;            /*        container ("label") flags                                */
  177.     CM_ULONG                        generation;                    /*        generation number                                                */
  178.     CM_ULONG                        tocBufSize;                    /*        actual TOC buffer size (lbl value*1024)    */
  179.     
  180.     void                                 *toc;                                /*        ptr to TOC (this container's or target)    */
  181.     void                                 *privateTOC;                /*        ptr to this container's private TOC            */
  182.     CM_ULONG                        tocOffset;                    /*        offset to the start of the TOC                    */
  183.     CM_ULONG                        tocSize;                        /*        total size of the TOC in the container    */
  184.     CMBoolean                        tocFullyReadIn;            /*        true ==> an "old" TOC is fully loaded        */
  185.     CMBoolean                        usingTargetTOC;            /*        true ==> currently using target's TOC        */
  186.     CM_ULONG                        tocInputOffset;            /*        current TOC input offset                                */
  187.     void                                *ioBuffer;                    /*        current buffered TOC I/O buffer                    */
  188.     void                                *tocIOCtl;                    /*        current TOC I/O control block pointer        */
  189.     
  190.     struct TOCValue            *tocIDSeedValue;        /*        ptr to TOC ID seed value       (not hdr)*/
  191.     struct TOCValue            *tocIDMinSeedValue;    /*        ptr to TOC ID min seed value   (not hdr)*/
  192.     struct TOCValue            *tocObjValue;                /*        ptr to TOC object value        (not hdr)*/
  193.     struct TOCValue            *tocContainerValue;    /*        ptr to TOC container value     (not hdr)*/
  194.     struct TOCValue         *spaceDeletedValue;    /*        ptr to TOC space deleted value (not hdr)*/
  195.     struct TOCValue         *tocNewValuesValue;    /*        ptr to TOC new values TOC             (not hdr)*/
  196.     struct TOCValueHdr    *freeSpaceValueHdr;    /*        ptr to TOC free list (this IS value hdr)*/
  197.     struct TOCValueHdr    *deletesValueHdr;        /*        ptr to TOC deletes list (also value hdr)*/
  198.     ListHdr                            tmpList;                        /*        free space available at close time            */
  199.         
  200.     void                                *globalNameTable;        /*         ptr to global name tbl (or target)            */
  201.     void                                *privateGlobals;        /*         ptr to this container's global name tbl    */
  202.     CMBoolean                        usingTargetGlobals;    /*        true ==> currently using target's glbls    */
  203.     CMBoolean                        deleteGarbage;            /*        garbage collect before closing                    */
  204.  
  205.     CM_ULONG                        nextStdObjectID;        /*        next available std object id number            */
  206.     CM_ULONG                        nextUserObjectID;        /*        next available user object id number        */
  207.     
  208.     CM_USHORT                        useFlags;                        /*        container use flags                                            */
  209.     CM_ULONG                        physicalEOF;                /*        next free byte in the container                    */
  210.     CM_ULONG                        logicalEOF;                    /*        offset to highest byte written + 1            */
  211.     CM_ULONG                        maxValueOffset;            /*        max+1 allowed for value definitions            */
  212.     CM_ULONG                        originalEOF;                /*        size before update begins                                */
  213.  
  214.     CM_ULONG                        mergeInSize;                /*        the size of previous container merged in*/
  215.         
  216.     ListHdr                         deletedValues;             /*         list of all deleted values (headers)        */
  217.     
  218.     ListHdr                         embeddedContainers; /*         list of containers embedded in this one    */
  219.     struct TOCValueHdr    *embeddedValue;            /*        ptr to valueHdr for embedded container    */
  220.     struct EmbeddedContainer *parentListEntry;/*    back ptr to parent's list entry                    */
  221.     
  222.     void                                 *tocActions;                /*        ptr to TOC walk through (private) data    */
  223.     
  224.     CM_SHORT                        getBaseValueOk;            /*        >0 ==> CMGetBaseValue() allowed                    */
  225.     struct TOCValueHdr    *dynamicBaseValueHdr;/*        CMReleaseValue() dynamic value base            */
  226.     CM_LONG                            nbrOfDynValues;            /*        count of dynamic values in container        */
  227.     
  228.     CMProperty                    dynValueProperty;        /*        property refNum for dynamic values            */
  229.     CMProperty                    baseTypesProperty;    /*        property refNum for base types                    */
  230.     
  231.     CMBoolean                        trackFreeSpace;            /*        true ==> allows tracking of freed space    */
  232.     CMBoolean                        touchTheValue;            /*        true ==> appropriately record the touch    */
  233.  
  234.     ListHdr                         activeIOBuffers;        /*         list of active buffered I/O users                */
  235.     
  236.     struct TOCObject        *touchedChain;            /*         chain of objects touched during updating*/
  237. };
  238. typedef struct Container Container, *ContainerPtr;
  239.  
  240. /* NOTE: there is a mutual reference here between Container and TOCObject.  They refer    */
  241. /* to each other!  Thus we must do the weird "struct TOCObject" to define the list            */
  242. /* pointers above.  Sorry about that!                                                                                                        */
  243.  
  244. /* To make it easier and more self-documentating for using the "seeds" the following         */
  245. /* macros are provided.  These both assume the current container pointer is the variable*/
  246. /* "container".                                                                                                                                                    */
  247.  
  248. #define Seed        (container->tocIDSeedValue->value.imm.ulongValue)
  249. #define MinSeed (container->tocIDMinSeedValue->value.imm.ulongValue)
  250.  
  251. /* Similarly, we define the following macros to get at the updating TOC limits of non-    */
  252. /* private objects...                                                                                                                                        */
  253.  
  254. #define TOCNewValuesTOCOffset    (container->tocNewValuesValue->value.notImm.value)
  255. #define TOCNewValuesTOCSize        (container->tocNewValuesValue->value.notImm.valueLen)
  256.  
  257. /* The following defines the layout for list entries of a list of containers directly        */
  258. /* embedded in another container.  A container sort of is like a "super class" with its    */
  259. /* embedded containers being "subclasses".  There can be any number of embedded                 */
  260. /* containers open simultaneously (memory permitting). Each of these, in turn, can have    */
  261. /* embedded containers of their own!                                                                                                        */
  262.  
  263. struct EmbeddedContainer {                                /* Layout of a embedded container list entry:    */
  264.     ListLinks                      siblingsLinks;                /*    sibling Container links (must be first)    */
  265.     ContainerPtr             container;                        /*        ptr to the embedded container                        */
  266. };                                                                                /*        note, theValueHdr gives us father contnr*/
  267. typedef struct EmbeddedContainer EmbeddedContainer, *EmbeddedContainerPtr;
  268.  
  269.  
  270. /* Whenever we write to the container, we keep track of what we think is the EOF (last     */
  271. /* written byte + 1). We refer to this as the "logical EOF" since it may or may not be     */
  272. /* equal to the true container EOF.  For normal writing it probably is always the same.    */
  273. /* But for reusing free space we could be reusing free list space and the logical EOF     */
  274. /* may end up less than the physical EOF.                                                                                                */
  275.  
  276. /* The reason we want to know this is mainly because the standard ANSI C stream I/O*/
  277. /* has no support for cutting back a file!  This is portable code and we must assume         */
  278. /* that, at a minimum, the I/O handlers are using stream I/O.  We thus must take into     */
  279. /* account the possible extra space that could result from space reuse when the updates */
  280. /* use less space than what was originally there.                                                                                */
  281.  
  282. #define SetLogicalEOF(eof)    if ((eof) > container->logicalEOF) \
  283.                                                             container->logicalEOF = (eof)
  284.  
  285.  
  286.                                                 /*---------------------------------------*
  287.                                                  | Defined Layout of the Container Label |
  288.                                                  *---------------------------------------*
  289.  
  290. As defined by the API documentation, a container label is always placed at the END of the
  291. container and has the following layout:
  292.  
  293.              0                       8     10    12    14    16          20          24
  294.             +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
  295.             |      Magic Bytes      |flags|bufsz|major|minor|TOC offset |  TOC size |
  296.             +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
  297.                                     8              2     2     2     2        4           4
  298.  
  299. These are defined as "hard-coded" constants since the format is, by definition, platform
  300. independent.     The actual formatting and I/O for the container label is done by a handler
  301. because of this.                                                                                                                                                */
  302.  
  303. #define LBLmagicBytes            0                                /* 8 bytes: the magic byte identifier                    */
  304. #define LBLflags                    8                                /* 2                the label flags                                        */
  305. #define LBLbufSize             10                                /* 2                TOC buffer size / 1024                        */
  306. #define LBLmajorVersion     12                                /* 2                major format version number                */
  307. #define LBLminorVersion     14                                /* 2                minor format version number                */
  308. #define LBLtocOffset         16                                /* 4                offset to start of TOC                        */
  309. #define LBLtocSize             20                                /* 4                total byte size of the TOC                */
  310.  
  311. #define LBLsize                     24                                /* defined size of the container label                */
  312.  
  313.                                                          CM_END_CFUNCTIONS
  314. #endif
  315.