home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / UPDATE.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  21KB  |  408 lines
  1. /* @(#)Z 1.4 com/src/cm/Update.h, odstorage, od96os2, odos29646d 96/11/15 15:27:39 (96/10/29 09:20:06) */
  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:         Update.h 
  31.  
  32.     Contains:    Container Manager Container Updating 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.          <3>     9/15/94    EL        #1182275 Add cmClosePastDataGap.
  43.          <2>     8/26/94    EL        #1182275 Extra parameter in
  44.                                                     cmGenerateUpdate, new function
  45.                                                     cmPastUpdateOnTouchList.
  46.          <1>      2/3/94    EL        first checked in
  47.          <2>    10/29/93    EL        Add extra parameter to cmDeleteTouchList
  48.                                                     and export cmDeleteObjeFromTouchedChain
  49.  
  50.     To Do:
  51. */
  52.  
  53. /*---------------------------------------------------------------------------*
  54.  |                                                                           |
  55.  |                             <<<  Update.h  >>>                            |
  56.  |                                                                           |
  57.  |             Container Manager Container Updating Interfaces               |
  58.  |                                                                           |
  59.  |                               Ira L. Ruben                                |
  60.  |                                  6/16/92                                  |
  61.  |                                                                           |
  62.  |                     Copyright Apple Computer, Inc. 1992-1994              |
  63.  |                           All rights reserved.                            |
  64.  |                                                                           |
  65.  *---------------------------------------------------------------------------*
  66.  
  67.  This file contains the interfaces to the "incremental update" processing routines when
  68.  one updating container updates its target container.  The routines defined here are
  69.  responsible for maintaining the "touched chain" and "touched lists". These are additional
  70.  data structures layered on to the main data structures (see TOCEntries.[hc]).  See
  71.   Update.c  for complete details.
  72. */
  73.  
  74.  
  75. #ifndef __UPDATING__
  76. #define __UPDATING__
  77.  
  78.  
  79. #ifndef __CMTYPES__
  80. #include "CMTypes.h"
  81. #endif
  82. #ifndef __CM_API_TYPES__
  83. #include "CMAPITyp.h"
  84. #endif
  85. #ifndef __LISTMGR__
  86. #include "ListMgr.h"
  87. #endif
  88.  
  89. struct Container;
  90. struct TOCObject;
  91. struct TOCProperty;
  92. struct TOCValueHdr;
  93.                                                                     
  94.                                                                     CM_CFUNCTIONS
  95.  
  96. /* The touched list is created for every updated object. The head of this list is in         */
  97. /* the touched TOCObject.  An entry is created the first time a value (header) is             */
  98. /* touched.  At that time the original object, property, and type IDs are recorded.            */
  99.  
  100. struct TouchedListEntry {                                        /* Layout of a touched list entry:                    */
  101.     ListLinks                                touchedListLinks;    /*        links to next/prev entry (must be 1st)*/
  102.     struct TOCValueHdr             *theValueHdr;            /*         ptr to value hdr that was touched            */
  103.     CMObjectID                             objectID;                    /*        value's original object ID                        */
  104.     CMObjectID                             propertyID;                /*          "        "     property ID                    */
  105.     CMObjectID                             typeID;                        /*          "        "     type ID                            */
  106.     unsigned short                     touchFlags;                /*        touched list entry flags                            */
  107.     struct TouchedListEntry *removedEntry;        /*        back ptr to "removed" entry                        */
  108. };
  109. typedef struct TouchedListEntry TouchedListEntry, *TouchedListEntryPtr;
  110.  
  111.  
  112. /* The following touchFlags indicate what was done to the value pointed to by the                */
  113. /* touched list entry...                                                                                                                                */
  114.  
  115. #define TouchedRemoved                    0x0001            /* touchFlags: 1 ==> value moved out                */
  116. #define TouchedInserted                    0x0002            /*                             ==> value moved in                    */
  117. #define TouchedDeletedValue            0x0004            /*                             ==> value was deleted            */
  118. #define TouchedDeletedProperty    0x0008            /*                             ==> property was deleted        */
  119. #define TouchedEdited                        0x0010            /*                             ==> editing                                */
  120. #define TouchedImmediate                0x0020            /*                              ==> immediate modified            */
  121. #define TouchedBaseType                    0x0040            /*                             ==> base type modified            */
  122. #define TouchedSetinfoed                0x0080            /*                              ==> set-infoed                            */
  123.  
  124. #define TouchedModified    (TouchedEdited         | /* These are the basic value modifications    */\
  125.                                                  TouchedSetinfoed |                                                                                             \
  126.                                                  TouchedImmediate    |                                                                                             \
  127.                                                  TouchedBaseType)
  128.  
  129. void cmDeleteObjFromTouchedChain(ContainerPtr container,
  130.                                                                                             TOCObjectPtr theObject,
  131.                                                                                             TOCObjectPtr thePrevObject);
  132.                                                                                             
  133. void cmAddObjToTouchedChain(struct Container *container, struct TOCObject *theObject);
  134.     /*
  135.     The TOCObject pointed to by theObject is "touched", i.e., it is put on the updating
  136.     container's singly linked chain of touched objects, the touchedChain.
  137.     
  138.     The container is passed because the touched list has to be attached to a "know fixed"
  139.     container.  The fixed container is usually the updatingContainer.  But this needs to be
  140.     "controlled" during open time because the updatingContainer is also used define the
  141.     "owner" of NEW objects read in during TOC loading.  The updatingContainer then is the
  142.     container doing the loading, NOT the original container the user opened.
  143.  
  144.     cmReadTOC(), who loads the TOC, calls this routine to add objects to the touched chain
  145.     that have the special "updates" property.  Such objects have associated updating
  146.     instructions (generated by generateValueUpdates() at close time). These must be chained
  147.     together until the TOC is fully read in.  This is because "inserted" (i.e., move)
  148.     updates could refer to objects not yet  read in.  The touched chain is a convenient
  149.     place!  So we use it and this routine to build the chain.  This chain is only temporary.
  150.     It is "fed" to cmApplyUpdates() who walks the chain to apply all the updates. The chain
  151.     is then immediately cleared ready to receive new updates in the "normal" way.
  152.     
  153.     Note, the object is placed on the touched chain only once.  This routine is, however,
  154.     called whenever we think we need to touch the object.  We worry about the multiple
  155.     touches here.
  156.     */
  157.     
  158.     
  159. void cmDeleteTouchedList(struct TOCObject *theObject, ContainerPtr container);
  160.     /*
  161.     This routine is only used when all TOC data structures are being freed.  For each object
  162.     passed, that object's entire touched list (if any) is freed.  Since all TOC entities are
  163.     being freed, there is no need to remove the object from the touched chain since the
  164.     objects on the chain will be freed.
  165.     
  166.     Note, that the object's passed are just objects picked up during the freeing of all the
  167.     objects.  Therefore the touched chain is not being followed in the context used here.
  168.     */
  169.     
  170.     
  171. CMBoolean cmTouchEditedValue(struct TOCValueHdr *theValueHdr);
  172.     /*
  173.     This routine defines a touched list entry for a value when it is edited.  A touched list
  174.     entry for the object "owning" the value is defined.  The parameter specifies the value
  175.     header being edited. The function returns true if everything went ok and false otherwise.
  176.     This can only fail because of an allocation error creating a touched list entry.
  177.     */
  178.     
  179.     
  180. CMBoolean cmTouchImmediateValue(struct TOCValueHdr *theValueHdr);
  181.     /*
  182.     This routine defines a touched list entry for an immediate value when it is edited.  A
  183.     touched list entry for the object "owning" the value is defined.  The parameter specifies
  184.     the value header of the immediate value being edited.  The function returns true if
  185.     everything went ok and false otherwise. This can only fail because of an allocation error
  186.     creating a touched list entry.
  187.     */
  188.  
  189.  
  190. CMBoolean cmTouchBaseType(struct TOCValueHdr *theValueHdr);
  191.     /*
  192.     This routine defines a touched list entry for an base type when it is changed.  A touched
  193.     list entry for the object "owning" the base type (value) is defined.  The parameter
  194.     specifies the value header of the base type value being changed.  The function returns
  195.     true if everything went ok and false otherwise.  This can only fail because of an
  196.     allocation error creating a touched list entry.
  197.     */
  198.  
  199.     
  200. CMBoolean cmTouchSetInfoedValue(struct TOCValueHdr *theValueHdr);
  201.     /*
  202.     This routine defines a touched list entry for an value when its type or generation number
  203.     is changed (i.e., it's "set-infoed").  A touched list entry for the object "owning" the
  204.     value is defined. The parameter specifies the value header of the value being set-infoed.
  205.     The function returns true if everything went ok and false otherwise.  This can only fail
  206.     because of an allocation error creating a touched list entry.
  207.  
  208.   Warning: The call to this routine MUST be done before any changes to the type because the
  209.                       touch list info is in terms of the original object, property, and type.
  210.     */
  211.  
  212.     
  213. CMBoolean cmTouchMovedValue(struct TOCValueHdr *theFromValueHdr,
  214.                                                       struct TOCObject *theFromObject,
  215.                                                         struct TOCObject *theToObject,
  216.                                                         CMObjectID toPropertyID);
  217.     /*
  218.     This routine defines touched list entries for a value move when a CMMoveValue() is done.
  219.     Touched lists entries for the "from" and "to" (source and destination) objects involved
  220.     in the moved value are defined.  The parameters specify the value header to be moved
  221.     (theFromValueHdr), the source ("from") TOCObject (theFromObject), the destination ("to")
  222.     TOCObject (theToObject), and destination property ID (toPropertyID).  The function
  223.     returns true if everything went ok and false otherwise.  This can only fail because of an
  224.     allocation error creating a touched list entry.
  225.  
  226.   Warning: The call to this routine MUST be done before the value is moved because the
  227.                       touch list info is in terms of the original object, property, and type.  The
  228.                      move will obviously change the object and/or property.
  229.     */
  230.  
  231.  
  232. CMBoolean cmTouchDeletedValue(struct TOCValueHdr *theValueHdr, struct TOCObject *theObject);
  233.     /*
  234.     This routine defines a touched list entry for a value when an explicit CMDeleteValue() is
  235.     done.  A touched list entry for the object "owning" a value that is (to be) deleted is
  236.     defined.  The parameters specify the value header to be deleted (theValueHdr) and the
  237.     value's TOCObject (theObject).  The function returns true if everything went ok and false
  238.     otherwise.  This can only fail because of an allocation error creating a touched list
  239.     entry.
  240.  
  241.     Values are deleted individually and explicitly via CMDeleteValue(), or implicitly by
  242.     implicit deletion of the value's property.  An implicit property deletion comes about
  243.     when all the values of a property are explicitly deleted or moved out, or if the object
  244.     itself is deleted.  Implicit value deletions are handled cmImplicitDeleteValueTouch() 
  245.     specially as descriped there.
  246.     */
  247.  
  248.  
  249. void cmImplicitDeleteValueTouch(struct TOCValueHdr *theValueHdr, struct TOCObject *theObject);
  250.     /*
  251.     This routine is called whenever a value is IMPLICITLY deleted because an object or a
  252.     property is deleted.  In that case, all the values for the object, or one of the object's
  253.     property's are deleted.  We also must delete the the corresponding touched list entry
  254.     if there is one for those values since there isn't going to be any value there.  However,
  255.     if a value was moved in from another object, then the "removed" entry in the original
  256.     value is flagged as "deleted value".
  257.     */
  258.  
  259.  
  260. CMBoolean cmTouchDeletedProperty(struct TOCProperty *theProperty,
  261.                                                              struct TOCObject *theObject);
  262.     /*
  263.     This routine defines a touched list entry for a property when the property is explicitly
  264.     deleted by CMDeleteObjectProperty().  A touched list entry for the object "owning" the
  265.     property that has been deleted is defined. The parameters specify the property of the
  266.     object to be deleted (theProperty) and the property's TOCObject (theObject). The function
  267.     returns true if everything went ok and false otherwise.  This can only fail because of an
  268.     allocation error creating a touched list entry.
  269.     
  270.     Note, this routine is slightly different from touches on values in that no value is
  271.     involved explicitly in the property delete.  They are, however, implicitly involved to 
  272.     the degree that all values are deleted from the property (and the value headers put on
  273.     the deleted values list).  The process of value deletion deletes all the touched list
  274.     entries for those values in the property's object.  Any values moved into this object
  275.     from other objects also have a "removed" touched list entry in the original object.
  276.     Deleting such values for the property has exactly the same effect as CMDeleteValue(),
  277.     i.e., the "removed" entry is changed to a "deleted value" entry.  See
  278.     cmTouchDeletedValue() for further details.
  279.     
  280.     Note, that values previous moved OUT of the object containing the property being deleted 
  281.     have "removed" entries of their own in this object.  Thus, there still could be "dangling"
  282.     "removed" entries on this object's touched list.  These must remain in the normal course
  283.     of move handling.  However, see what happens to these things when the entire object
  284.     is deleted!  Read cmTouchDeletedObject() for details.
  285.     */
  286.     
  287.     
  288. void cmTouchDeletedObject(struct TOCObject *theObject);
  289.     /*
  290.     This routine is called whenever an object is deleted. The object is placed on the touched
  291.     chain if it is not already there.  The object's touched chain, if any, is deleted EXCEPT
  292.     for "removed" entries for values previously moved out of this object.  
  293.     
  294.     The "removed" entries are kept because there are references to these entries from 
  295.     "inserted" entries in other object.  If a moved value is itself deleted after the object
  296.     it came from is deleted, then the back pointer in its "inserted" entry must be kept valid
  297.     so that the "removed" entry it points to can be changed to a "deleted value".  Although
  298.     this "deleted" value is on a touched list of a deleted object, it won't cause harm since
  299.     the final walks of the touched chain know to expect this.
  300.     
  301.     Deleted objects are moved to the deleted objects list and flagged as deleted.  This is
  302.     done to protect against the user reusing the refNum after the delete.  Thus an object on
  303.     the touched chain, but flagged as deleted, is enough to indicated to close-time
  304.     processing what is going on.  The remaining touched list "goes along for the ride".
  305.     
  306.     This routine MUST be called AFTER all objects and properties for the object have been
  307.     deleted.  By that time all touched list entries for values will have been processed
  308.     (using cmImplicitDeleteValueTouch()).   The reason it must be after is that if it were
  309.     before, we could have touched value headers pointing to touched list entries we free up
  310.     here.  Not too cool!  cmImplicitDeleteValueTouch() would have a hard time dealing with
  311.     that.
  312.     */
  313.  
  314. void cmPastUpdateOnTouchList(ContainerPtr container);
  315.     /*
  316.     Make sure that all the previous update are put on to the touch list so that they can be
  317.     included in the generation in the new update
  318.     */
  319.     
  320. CMBoolean cmGenerateUpdates(struct Container *container, struct Container *targetContainer);
  321.     /*
  322.     This is called at close time (CMCloseContainer()) to generate all the updating
  323.     instructions for all objects and their values touched during an updating session. True is
  324.     returned if successful and false otherwise (and the error reporter returns).
  325.     
  326.     The touched objects are on the touched chain pointed to brom the container control block.
  327.     Two passes are made over the touched chain:
  328.     
  329.          Pass 1: All touched values are processed.  The touched list for each non-deleted 
  330.                          object that is still on the touched chain (see pass 2) are processed for
  331.                          touched values.  Touched properties are skipped.  
  332.                          
  333.                          A special "updates" property is generated for each object involved which 
  334.                          contains a value whose data is all the value updates for that object.  Each
  335.                          processed touched value's touched list entry is deleted.
  336.                          
  337.                          The end of pass 1 leaves only deleted property touched list entries in 
  338.                          non-deleted objects on the touched chain and touched, but deleted, objects.
  339.                          
  340.          Pass 2: All touched deleted objects and deleted properties.  This is the remaining
  341.                          stuff on the touched chain and lists.  The data for this is attached to a
  342.                          special TOC #1 property.  The remaining touched list entries are deleted. 
  343.                          Thus, at the end of pass 2, all touched list space is freed up.
  344.     */
  345.     
  346.     
  347. CMBoolean cmApplyUpdates(struct Container *container);
  348.     /*
  349.     This is called at open time (openTargetContainer()) to apply (execute) all the updating
  350.     instructions for all objects and their values "touched" while loading in the non-private
  351.     portion of an updating container's TOC.  True is returned if successful and false
  352.     otherwise (and the error reporter returns).
  353.     
  354.     The touched objects are on the touched chain pointed to from the passed container control
  355.     block.  These were objects containing a special "updates" property.  Such a property has
  356.     a value whose value data is all the updating instructions dealing with that object.  The
  357.     reason they were chained was so that we could get at the objects with that property and
  358.     do it at a time when we know we have all the objects read in.  During the read there could
  359.     be references in the instructions for as-yet unread objects.
  360.     
  361.     To make it easire (and more efficient) to get at the "updates" property value for the
  362.     objects on the touched chain, such objects have had their refCon set with the refNum
  363.     (pointer) of the updating instruction value header.  That was done at the same time the
  364.     object was placed on the touched chain.  We'll clear it to NULL as we process those
  365.     objects.
  366.     
  367.     This routine is more-or-less the symmetric counterpart to cmGenerateUpdates() above,
  368.     which generated the instructions we're about to read here.  That generation is done in 
  369.     two passes to generate two groups of updates; first the value updates, and then the 
  370.     object/property deletions.  The value updates are the instructions attached to each
  371.     object and that is what caused the touched chain to be built that we are going to process
  372.     here.  The deletions are attached to a special TOC #1 "deletes" property.  We process
  373.     those AFTER the value updates are processed (more about this below).
  374.     
  375.     Thus, rather than two passes over the touched chain that we do in generating the updates,
  376.     we have two phases here:
  377.     
  378.          Phase 1: All updating instructions are processed for each object on the touched chain.
  379.                             This will update all the values appropriately.  Since the updating
  380.                             instructions are in terms of the original "OPT addresses" of the values we
  381.                             know how to find them.  Moves can be made.
  382.                             
  383.                             Each object processed is removed from the touched chain.  Thus at the end of
  384.                             phase 1, the touched chain is empty and ready to receive REAL update touches.
  385.                          
  386.          Phase 2: The "deletes" TOC #1 property is used to get the deletion updates list.  All
  387.                             object and property deletes are done at this time.  This must be done last
  388.                             in order for phase 1 to work correctly. The problem is with moves interacting
  389.                             with deletes.  If a value is moved from A to B, and then A (its original
  390.                             location) deleted, then the updates to that value would not have A to refer 
  391.                             to. We always need the ORIGINAL OPT addresses of the values.
  392.     */
  393.  
  394. void cmClosePastDataGap(ContainerPtr container, CM_ULONG offset, CM_ULONG size);
  395.  
  396. /*------------------------------------------------------------*
  397.  | cmClosePastDataGap - adjust the offset in the past history |
  398.  *------------------------------------------------------------*
  399.  
  400.     When we return free space from a embedded container to the parent container, the
  401.     offset of the values will be changed. This affects not only the offset on the TOC.
  402.     It also affects the offset in the update objects. So we need to be able to update
  403.     the offset in the past history to reflect the changes in the various offset.
  404. */
  405.  
  406.                                                           CM_END_CFUNCTIONS
  407. #endif
  408.