home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / TOCOBJS.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  24KB  |  466 lines
  1. /* @(#)Z 1.4 com/src/cm/TOCObjs.h, odstorage, od96os2, odos29646d 96/11/15 15:27:32 (96/10/29 09:19:54) */
  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:         TOCObjs.h  
  31.  
  32.     Contains:    Container Manager TOC Objects 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.          <2>     8/26/94    EL        #1182275 Add constants EditedRecently and
  43.                                     DeletedRecently to be used for merging.
  44.          <2>     3/31/94    EL        Add cmPutObjectInTOC call. #1150214
  45.          <1>      2/3/94    EL        first checked in
  46.          <4>      2/2/94    EL        cmFreeLastDeletedObject no longer needed,
  47.                                                     use refNumHandling to control freeing.
  48.          <3>    10/29/93    EL        Add new call cmFreeLastDeletedObject so we
  49.                                                     can free the reference associated with
  50.                                                     value
  51.          <2>     10/4/93    EL        Add cmGetMasterListTail call.
  52.  
  53.     To Do:
  54. */
  55.  
  56. /*---------------------------------------------------------------------------*
  57.  |                                                                           |
  58.  |                           <<<  TOCObjs.h   >>>                            |
  59.  |                                                                           |
  60.  |                  Container Manager TOC Objects Interfaces                 |
  61.  |                                                                           |
  62.  |                               Ira L. Ruben                                |
  63.  |                                 11/20/91                                  |
  64.  |                                                                           |
  65.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  66.  |                           All rights reserved.                            |
  67.  |                                                                           |
  68.  *---------------------------------------------------------------------------*
  69.  
  70.  All TOC object manipulation routines are contained in this file. Only manipulations down
  71.  to the object level are done here.  The objects themselves contain pointers off to lower
  72.  level structures which are maintained by TOCEntries.c. The split is done this way to keep
  73.  the accessing of objects separate from the stuff represented by those objects.
  74.  
  75.  TOC objects are based on their ID's.  The ID's do not lend themselves well to the 
  76.  standard binary-tree mechanism we use elsewhere so another scheme is used here.
  77.  
  78.  TOC objects are access through a set of index tables.  The tables correspond to "powers"
  79.  of a chosen index table size.  For example, if the size was 100 and we had ID 1234567 we
  80.  would have 4 indices: 01, 23, 45, 67.  Four index tables would exist each corresponding
  81.  to the indices 00 to 99.  The first table would have its 01'th entry pointing to the next
  82.  table.  That next table would have its 23rd entry pointing to the third table.  The 
  83.  third table would have its 45th entry pointing to the last table.  The 67th entry in the
  84.  last table would point to the actual object with ID 1234567.
  85.  
  86.  The actual number of tables is dependent on the table size and the max ID value supported
  87.  (which is 0xFFFFFFFF).  Small ids are padded with 00 as the higher order indices.
  88.  
  89.  The number of tables is dependent on the table size and the sparseness of the ID's
  90.  presented.  This scheme represents a comprimise between speed, space, and the fact that
  91.  we want to always have the ID's in sorted order.  We get the sorted order by walking the
  92.  index tables in the appropriate way.
  93.  
  94.  The support for this scheme has been generalized to allow any size index table. 
  95.  
  96.  Multiple TOC's are supported.  Each TOC is tied to a anonymous reference number from
  97.  the outside caller's point of view.  In here it is a pointer to a control block that
  98.  contains the root pointer to the TOC index tables and the control variables to access
  99.  through the index tables mentioned above.
  100.  
  101.  Each TOC is independent.  Since the control variables are tied to the TOC, it is allowed
  102.  to have different size index tables for different TOC.  It's not clear this has any
  103.  benefit, but it's allowed.
  104.  
  105.  The TOC routines only know the final TOC entries down to the level of "objects".  The
  106.  objects themselves contain fields maintained by other routines outside the scope of this
  107.  file.  In particular the object is mainly a "head cell" for a list of entries chained
  108.  off of it.  The  ListMgr package is used to maintain the lists by the caller by using the
  109.  object.  Other fields are provided as well which are also maintained by the caller.  The
  110.  only exception is the object ID number which is known to this file.
  111. */
  112.  
  113. #ifndef __TOCOBJECTS__
  114. #define __TOCOBJECTS__
  115.  
  116.  
  117. #include <setjmp.h>
  118.  
  119. /*------------------------------------------------------------------------------------*
  120.  | W A R N I N G - - -> this header as well as  TOCObjs.h   and  TOCEnts.h   all have |
  121.  |                      mutual references.  The include order is NOT arbitrary.  It's |
  122.  |                      the only one that works!  Even with it we have to do some     |
  123.  |                      forward struct pointer references of the form "struct foo *p" |
  124.  *------------------------------------------------------------------------------------*/
  125.  
  126. #ifndef __CMTYPES__
  127. #include "CMTypes.h"
  128. #endif
  129. #ifndef __CM_API_TYPES__
  130. #include "CMAPITyp.h"
  131. #endif
  132. #ifndef __CONTAINEROPS__
  133. #include "Containr.h"  
  134. #endif
  135. #ifndef __LISTMGR__
  136. #include "ListMgr.h"
  137. #endif
  138.  
  139. struct Container;
  140. struct TOCObject;
  141.  
  142.                                                                     CM_CFUNCTIONS
  143.  
  144.  
  145. /* All in-memory objects have the following layout. There objects are accessed by their    */
  146. /* object ID.                                                                                                                                                     */
  147.  
  148. struct TOCObject {                                        /* Layout of a TOC object:                                                */
  149.     CMObjectID             objectID;                    /*        the object's ID     (keep first for debugging) */
  150.     ListHdr                     propertyList;            /*         list of object property entries                            */
  151.     struct Container *container;                /*        ptr to "owning" container control block            */
  152.     struct TOCObject *nextObject;                /*         chain to next object by increasing ID                */
  153.     struct TOCObject *prevObject;                /*         chain to previous object by decreasing ID        */
  154.     struct TOCObject *nextTypeProperty;    /*         chain of next type/property by increasing ID*/
  155.     struct TOCObject *prevTypeProperty;    /*         chain of previous type/property by decr. ID    */
  156.     CM_USHORT                  objectFlags;                /*        info flags about the object                                    */
  157.     CMRefCon                  objectRefCon;            /*        user's object refCon                                                */
  158.     CM_ULONG               useCount;                    /*        count of nbr of times "used"                                */
  159.     struct TOCObject *nextTouchedObject;/*        link to next touched object                                    */
  160.     ListHdr                     touchedList;                /*         values/properties touched IN this object        */
  161. };
  162. typedef struct TOCObject TOCObject, *TOCObjectPtr;
  163.  
  164. /* NOTE: there is a mutual reference here between Container and TOCObject.  They refer    */
  165. /* to each other!  Thus we must do the weird "struct Container" to define the container    */
  166. /* pointer above.  Sorry about that!                                                                                                        */
  167.  
  168. #define UndefinedObject         0x0001U        /* objectFlags: 1 ==> object created but undefined*/
  169. #define ObjectObject                 0x0002U        /*                                 ==> object is a base object            */
  170. #define PropertyObject             0x0004U        /*                                ==> object is a property                */
  171. #define TypeObject                     0x0008U        /*                               ==> object is a type                        */
  172. #define DeletedObject                0x0010U        /*                                 ==> object has been deleted            */
  173. #define DeletedRecently            0x0200U        /*                                ==> object prop deleted recently*/
  174. #define EditedRecently            0x0400U        /*                                ==> object edited recently            */
  175. #define DynamicValuesObject    0x0800U        /*                                ==> object "owns" dynamic values*/
  176. #define TouchedObject                0x1000U        /*                                ==> object has been "touched"        */
  177. #define ProtectedObject            0x2000U        /*                                ==> object is locked/protected    */
  178. #define LinkedObject                0x4000U        /*                                ==> object linked to master lsts*/
  179. #define UndefObjectCounted     0x8000U        /*                                ==> object counted as undefined    */
  180.  
  181. #define DefaultIndexTableSize    256            /* "recommended" index table size                                    */
  182. #define MinIndexTableSize            16            /* minimum index table size                                                */
  183. #define MaxIndexTableSize            1024        /* maximum index table size                                                */
  184.  
  185. #define ALLOBJECTS            0x0000000UL        /* starting ID for cmForEachObject() for all objs    */
  186. #define MAXUSERID                0xFFFFFFFFUL    /* ending ID to scan objects to the highes user ID*/
  187.  
  188. /* The following is used to increment object ID counters. The counter is set to 0 if it    */
  189. /* wraps.  Any attempt to use the counter after that to define an object will result in    */
  190. /* an error.                                                                                                                                                        */
  191.  
  192. #define IncrementObjectID(id) (id = ((id) == MAXUSERID) ? 0x00000000UL : ++(id))
  193.  
  194.  
  195. void *cmCreateTOC(CM_ULONG tableSize, const struct Container *container);
  196.     /*
  197.     This routine MUST be called before any other TOC routine is called. It is used to set up
  198.     the data needed by the other TOC routines.  A "reference number" is returned to the
  199.     caller who must pass it to ALL the other TOC routines.  Any number of TOC can be 
  200.     created.  By passing the returned "reference number" to the other routines they will
  201.     operate on the corresponding TOC.
  202.  
  203.     Note, a TOC is "owned" by a container in the sense that each TOC is associated with a
  204.     particular container.  Container "objects" need to be able to get back at the container
  205.     control block that is associated with the TOC containing the object.  Thus the container
  206.     control block is passed here so that we may save it and store it into all created 
  207.     objects.
  208.     
  209.     Internally, i.e., in this file, the "reference number" is actually a pointer to a control
  210.     block containing the root pointer to the TOC index tables (set to NULL here) and the set
  211.     of variables needed to convert an object ID value into a set of indices which are used
  212.     to index into the index tables that lead to the actual TOC object corresponding to the
  213.     ID.  There is also a use count.  The use count is explained in cmUseTOC().
  214.     
  215.     The single parameter is the index table size.  See TOC.c on exactly how this is used.
  216.     But for purposes of description here, the tableSize determines how many index tables
  217.     we indirect through to get at an object and the size of each table (each entry in a
  218.     table is a pointer).  There is a trade-off between space and time here.  So that's why
  219.     the tableSize is a parameter.
  220.     
  221.     This function returns the pointer if we can allocate the control block. NULL is returned
  222.     if the allocation fails.
  223.     */
  224.  
  225.  
  226. void *cmUseTOC(void *toc, struct Container *container);
  227.     /*
  228.     This allows multiple users of the same TOC for the specified container.  This can come
  229.     about due to updating containers which want to use the TOC of their target.  They call
  230.     this routine to register the additional use of the specified TOC.  It is returned as the
  231.     function result but with the owning container of the TOC changed to the one specified.
  232.     Here we register the additional use by incrementing a use count of the TOC.  When
  233.     cmDestroyTOC() is called to remove the TOC it will decrement the use count.  Only when 
  234.     the count goes to 0 is the TOC actually destroyed.
  235.     
  236.     Since the owning container of the TOC is being changed, it is assumed the caller knows
  237.     what s/he is doing!  In particular we only do this for a container updating a target
  238.     and after the updates are applied, we want to use the target's TOC, but associate it with
  239.     the updating container.  This will allow new updates to be recorded in the updating
  240.     container, but in a TOC common to both the updater and the target.
  241.     */
  242.  
  243.  
  244. TOCObjectPtr cmCreateObject(const void *toc, const CMObjectID objectID, 
  245.                                                         CM_USHORT objectFlags, CMBoolean *dup);
  246.     /*
  247.     This routine is called to create a new object in the specified TOC for the specified ID.
  248.     A "raw" object is created and the function returns a pointer to where it was placed in
  249.     the TOC. If there is already an object with that ID the TOC, a pointer to it is returned
  250.     and dup set to true. The function returns NULL if there is an allocation failure so that
  251.     we couldn't create the object.
  252.     
  253.     Note that the object created is "raw" in the sense that all info in it is NULLed out.
  254.     This is the lowest level routine whose sole goal in life is object creation.  The caller 
  255.     is responsible for maintaining the objects.  Life is simpler this way (not to mention
  256.     more maintainable)!
  257.     */
  258.  
  259.  
  260. void cmUncreateObject(const void *toc, const CMObjectID id, CMRefCon refCon,
  261.                                           void (*freeAction)(TOCObjectPtr object, CMRefCon refCon));
  262.     /*
  263.     This routine is the inverse (more-or-less) of cmCreateObject().  It removes an object
  264.     with the specified ID from the specified TOC.  The space for the object is freed.  The
  265.     lowest level index table entry pointing to the object is made NULL to indicate it is
  266.     undefined.  However, the higher level tables leading to the lowest table are not changed.
  267.     This doesn't hurt except to take up space if the object being deleted is the only one in
  268.     the tables leading to it.  But it's not worth all the extra work!
  269.     
  270.     As discussed in cmCreateObject() we simply create a "raw" object and return.  The caller
  271.     builds upon the object with lower level link structures. Unfortunately here, we have to 
  272.     allow the caller to handle his or her stuff BEFORE we delete the object.  Thus a
  273.     freeAction routine may be passed which is called prior to the freeing of the object. A
  274.     "refCon" is also provided which the caller can use as a communication facility to convey
  275.     additional info to the freeAction routine.
  276.  
  277.   Note, the freeAction may be passed as NULL, in which case only the object is deleted and
  278.   it is assumed averything linked to it must have already been deleted.
  279.     */
  280.  
  281.  
  282.  
  283. void cmDelete1Object(const void *toc, const CMObjectID id, CMRefCon refCon,
  284.                                        void (*deleteAction)(TOCObjectPtr object, CMRefCon refCon));
  285.     /*
  286.     This routine is the inverse (more-or-less) of cmCreateObject().  It removes an object
  287.     with the specified ID from the the specified TOC.  Unlike cmUncreateObject() however,
  288.     the space for the object is NOT freed.  Rather the object is RELINKED on to a singly
  289.     linked list of deleted objects pointed to by deletedObjects (a global).  This is done
  290.     to prevent dangling pointers that the API user may have as object "refNum"s (we give 
  291.     the API user these pointers as CMObject's).
  292.     
  293.     Since the object is removed from the TOC it will never be seen by us here using the TOC
  294.     index tables.  Just as in cmUncreateObject() the lowest level index table entry pointing
  295.     to the object is made NULL to indicate it is undefined in the TOC.
  296.     
  297.     Also as in cmUncreateObject() we allow the caller to do something with the object before
  298.     it is deleted from the TOC and before we link it on to the deletedObjects list.  The
  299.     calling conventions are the same and NULL may be passed to indicate no action is to be
  300.     performed.
  301.     
  302.     Caution: the deletedObjects list utilizes the nextObject field of an object to link its
  303.     objects.  That field is also a link field for active objects.  Thus the object must be
  304.     unlinked from the active object chain BEFORE calling this routine. 
  305.     */
  306.     
  307.  
  308. TOCObjectPtr cmFindObject(const void *toc, const CMObjectID id);
  309.     /*
  310.      Given an object ID in a TOC, this function returns a pointer to the corrsponding object
  311.      or NULL if the object does not exist.
  312.     */
  313.  
  314.  
  315. int cmForEachObject(const void *toc, CMObjectID startingID, CMObjectID endingID, 
  316.                                       CMRefCon refCon, void (*action)(TOCObjectPtr object, CMRefCon refCon));
  317.     /*
  318.     Do (call) the specified action for each object in the specified TOC with object ID's
  319.     greater than or equal to the startingID and less than or equal to endingID.  The pointer
  320.     to each TOC object is passed to the action routine along with a "refCon" which the caller
  321.     can use as a communication facility to convey additional info to the action routine.  0
  322.     is returned to indicate successful completion.  Use the AbortForEachObject(x) (a macro)
  323.     in the action routine to abort the interator.  The "x" should be a positive integer which
  324.     is returned from cmForEachObject() and it should not be 0.
  325.     */
  326.  
  327.  
  328. #define AbortForEachObject(x) longjmp(SESSION->cmForEachObjectEnv, x)
  329.     /*
  330.     Use this in routines passed to cmForEachObject() to abort the interator. The value of x
  331.     is returned from cmForEachObject(). It should be positive and nonzero, since 0 is the
  332.     "success" return value for cmForEachObject(). It is assumed that the variable "container"
  333.     is the current container pointer.
  334.     */
  335.  
  336.  
  337. void cmDestroyTOC(void **toc, CMRefCon refCon,  CMBoolean objectToo,
  338.                                     void (*deleteAction)(TOCObjectPtr object, CMRefCon refCon));
  339.     /*
  340.     This routine is called to remove wipe a TOC out of existence.  All existing objects in
  341.     the TOC, supporting index tables, and deleted objects on the deletedObjects list are
  342.     freed.  The "reference number" must not be used beyond this point.  The TOC pointer is
  343.     NULLed out prior to return to prevent further use.
  344.     
  345.     Note, that anything "below" an object entry is NOT handled here, i.e., all stuff that 
  346.     the object might be pointing to.  The caller MUST provide a way of deleting that stuff.
  347.     To this end, the caller should provide a "deleteAction" routine.  It is called just
  348.     prior to deleting each object.  The pointer to each object is passed to the deleteAction
  349.     routine along with a "refCon" which the caller can use as a communication facility to
  350.     convey additional info to the deleteAction routine.
  351.     
  352.     The objectToo flag permits you to destroy the toc without deleting the objects.
  353.  
  354.     The deleteAction value may be passed as NULL.  If that is the case, then (obviously) no
  355.     call is done and the object is simply deleted.  It's not clear anyone will do such a
  356.     thing, but it's provided anyway!
  357.     
  358.     Since multiple users of the same TOC are permitted (because of updating), a use count is
  359.     maintained of the number of users of the TOC.  Additional users call cmUseTOC() to 
  360.     increment the useCount.  It is decremented here.  Only when the count goes to 0 do is
  361.     the TOC actually destroyed.
  362.     */
  363.  
  364.  
  365. TOCObjectPtr cmLinkObject(const void *toc, TOCObjectPtr theObject, 
  366.                                                     TOCObjectPtr afterThisObject);
  367.     /*
  368.     This routine is (doubly) links an object (theObject) into the master object chains whose
  369.     head and tail pointers are contained in the specified TOC.  The objects is inserted in
  370.     the object chain following afterThisObject. If afterThisObject is NULL the object is
  371.     appended to the end of its list(s).  The function returns the input object pointer as its
  372.     result.
  373.     
  374.     There are three master chains:
  375.     
  376.          (1).  A chain of property objects.
  377.          (2).  A chain of type objects.
  378.          (3).  A chain of ALL objects no matter what their type.  It may be neither a type or
  379.                      property.
  380.                      
  381.     Chain (3) is always built. The decision on whether to do (1) or (2) is a function of the
  382.     objectFlags field contained in the object itself.  So the caller must have set these
  383.     prior to calling this routine.
  384.     */
  385.     
  386.  
  387. TOCObjectPtr cmUnlinkObject(const void *toc, TOCObjectPtr theObject);
  388.     /*
  389.   This routine is the inverse to cmLinkObject().  It unlinks the specified object from the
  390.   master object chains whose head and tail pointers are contained in the specified TOC.
  391.   The function returns the input object pointer as its result.
  392.     
  393.     The object is always deleted from the chain of all objects.  It is also deleted from the
  394.     property or type chain if the objectFlags field contained in the object itself indicates
  395.     it is a property or type (see cmLinkObject() above for further details about the chains).
  396.     */
  397.  
  398.  
  399. TOCObjectPtr cmGetMasterListHead(const void *toc, CM_USHORT objectKindFlag);
  400.     /*
  401.     This routine returns the head of one of the master chain lists in a TOC depending on 
  402.     the objectKindFlag.  This flag should be one of the standard object flags; ObjectObject,
  403.     PropertyObject, or TypeObject.  The respective chain head will be returned as the function
  404.     result.
  405.     
  406.     These chain heads are used by the CMGetNextObject(), CMGetNextProperty(), and
  407.     CMGetNextType() routines to start them off.
  408.     */
  409.  
  410. TOCObjectPtr cmGetMasterListTail(const void *toc, CM_USHORT objectKindFlag);
  411.     /*
  412.     This routine returns the tail of one of the master chain lists in a TOC depending on 
  413.     the objectKindFlag.  This flag should be one of the standard object flags; ObjectObject,
  414.     PropertyObject, or TypeObject.  The respective chain head will be returned as the function
  415.     result.
  416.     
  417.     These chain tails are used by the CMGetPrevObject(), CMGetPrevProperty(), and
  418.     CMGetPrevType() routines to start them off.
  419.     */
  420.  
  421. void cmChangeRefNumHandling(const void *toc, CMBoolean setting);
  422.     /*
  423.     Normally all deleted values and objects are "remembered".  A value's header is placed on
  424.     the deleted values list attacthed to the container control block.  Deleted TOCObject's
  425.     are placed on the deleted object list attached to the toc control block.  Both value
  426.     headers and TOCObject's are the refNums we give to the user.  By remembering these we
  427.     can check for attempted reuse and report an error.
  428.     
  429.     However, there are times we don't want to track these things because we know internally
  430.     what we're doing (well, that's the theory).  So an override switch is provided.  Since
  431.     both kinds of refNums are TOC entities, the override is on a TOC basis and hence the
  432.     switch attached to the TOC control block.
  433.     
  434.     This routine is therefore provided to change the setting the override switch.  It is a
  435.     boolean with true meaning that deleted refNums are to be saved on their respective lists.
  436.     Setting the switch to false will cause the refNum to simply be freed.
  437.     
  438.     By calling cmKeepDeletedRefNums(), the current setting of the switch can be interrogated
  439.     to decide what to do.
  440.  
  441.   Oh, in case you're curious, one case where we suppress the refNum tracking is when we are
  442.   applying updates at open time where updating instructions are being interpreted to 
  443.   update a target container.
  444.     */
  445.  
  446.  
  447. CMBoolean cmKeepDeletedRefNums(const void *toc);
  448.     /*
  449.     As described above, this is used by all outside callers to see if a refNum is to be saved
  450.     on its deleted list.  The only thing outside callers can possibly be interested in is
  451.     for deleted values and whether the value headers are to be saved on the deleted values
  452.     list.
  453.     */
  454.     
  455. void cmPutObjectInTOC(const void *toc, TOCObjectPtr object, TOCObjectPtr *replacedObject);
  456.     /*
  457.     This routine let put put an object (currently belonging to another TOC) and put it into
  458.     this TOC. If an object of the same ID is already in this TOC, that old object in this
  459.     TOC will be replaced and also returned from the routine so that the caller can deal
  460.     with it.
  461.     
  462.     This routine is used to move objects from one TOC to another.
  463.     */        
  464.                                                           CM_END_CFUNCTIONS
  465. #endif
  466.