home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / GLBNAMES.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  18KB  |  394 lines
  1. /* @(#)Z 1.4 com/src/cm/GlbNames.h, odstorage, od96os2, odos29646d 96/11/15 15:27:12 (96/10/29 09:18:39) */
  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:        GlbNames.h
  31.  
  32.     Contains:    Container Manager Global Name Values 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        #1182319 Matches GlbNames.c.
  43.          <2>      5/9/94    MB        #1162181: Changes necessary to install MMM.
  44.          <1>      2/3/94    EL        first checked in
  45.  
  46.     To Do:
  47. */
  48.  
  49. /*---------------------------------------------------------------------------*
  50.  |                                                                           |
  51.  |                           <<<  GlbNames.h   >>>                           |
  52.  |                                                                           |
  53.  |              Container Manager Global Name Values Interfaces              |
  54.  |                                                                           |
  55.  |                               Ira L. Ruben                                |
  56.  |                                 12/12/91                                  |
  57.  |                                                                           |
  58.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  59.  |                           All rights reserved.                            |
  60.  |                                                                           |
  61.  *---------------------------------------------------------------------------*
  62.  
  63.  The routines here handle global names.  Global names are object values that are treated
  64.  speciaially.  Normally object values are written to a container and the value we keep in
  65.  the TOC is the offset to the value (and of course its length).  But we want to keep
  66.  global names around so we can handle such calls as CMGetGlobalName() which return
  67.  the global name value for the object (assuming it is such an object).  We also want to
  68.  efficiently determine if there are attempts at multiple definitions (CMRegister...()) of
  69.  the same global name.
  70.  
  71.  Special flag bits are used in the TOC entry to indicate the value is a global name and
  72.  points to it instead of being an offset.  There is room in the TOC value entry for the
  73.  offset too. It does get filled in when we actually write the global name to the container.
  74.  But the pointer must coexist so we can still get at the name string.  We can get away 
  75.  with this because a TOC value is two longs.  Thus we use one for the offset and one for
  76.  the pointer to the global name.  We therefore have to use the pointer to get at the
  77.  global name to get its length when doing the writing.  But this is getting off the track!
  78.  
  79.  Essentially a global name "belongs" to two data structures. The first is the TOC stucture
  80.  defined in  TOCEnts.h   (or .c).  As just mentioned there is a pointer from the value to
  81.  the global name.  The second data structure is the symbol table which contains the 
  82.  global names themselves.  This is a binary tree.  We can easily walk it when it comes time
  83.  to write the global names out instead of walking the more complicated TOC hunting down
  84.  just the global names (although there is nothing prohibiting that -- it was a time/space
  85.  trade-off).
  86.  
  87.  In addition to the global name in its symbol table entry, there is also a back link to
  88.  the value that points to it.  We can thus go from global name to owning object and vice
  89.  versa.  The back link is used when we write the global names to the container so that we
  90.  can fill in the offset in the object's value as mentioned above.
  91.  
  92.  This is a pretty complicated layout.  There is a potential "trap" in that TOC entries
  93.  can be deleted.  If they are, and it is one that points to a global name, we must delete
  94.  the global name too.  But deletingin in a binary tree is a pain! So what we do is 
  95.  simply mark an entry deleted by nulling out its back pointer.  The trap here is that if
  96.  we're not carful we could end up use a null pointer.  Just thought you would like to 
  97.  know that.
  98. */
  99.  
  100. #ifndef __GLOBALNAMES__
  101. #define __GLOBALNAMES__
  102.  
  103. #include <string.h>
  104. #include <setjmp.h>
  105.  
  106. #ifndef __CMTYPES__
  107. #include "CMTypes.h"
  108. #endif
  109. #ifndef __CM_API_TYPES__
  110. #include "CMAPITyp.h"
  111. #endif
  112. #ifndef __SYMMGR__
  113. #include "SymTbMgr.h"      
  114. #endif
  115. #ifndef __TOCENTRIES__
  116. #include "TOCEnts.h"   
  117. #endif
  118. #ifndef __TOCOBJECTS__
  119. #include "TOCObjs.h"   
  120. #endif
  121. #ifndef __CONTAINEROPS__
  122. #include "Containr.h"  
  123. #endif
  124. #ifndef __SESSIONDATA__
  125. #include "Session.h"          
  126. #endif
  127.  
  128.                                                                     CM_CFUNCTIONS
  129.  
  130. struct GlobalName {                                    /* Layout for a global name symbol table entry:            */
  131.     SymbolLinks         theNameLinks;            /*         standard right/left links (must be 1st)                */
  132.     struct TOCValue *theValue;                /*         back ptr to TOCValueBytes (NULL ==> deleted)    */
  133.     char        globalName[1];                        /*        start of this global name                                            */
  134. };
  135. typedef struct GlobalName GlobalName, *GlobalNamePtr;
  136.  
  137.  
  138. void *cmCreateGlobalNameTbl(ContainerPtr container);
  139.     /*
  140.     This routine MUST be called before any other global name routine is called. It is used to
  141.     set up the data needed by the other global name routines.  A "reference number" is
  142.     returned to the caller who must pass it to all the other global name routines. Any number
  143.     of global name tables can be created.  By passing the returned "reference number" to the
  144.     other routines they will operate on the corresponding table.
  145.      
  146.     Internally, i.e., in this file, the "reference number" is actually a pointer to a control
  147.     block containing the root pointer to the global name table (set to NULL here) and a use
  148.     count.  The use count is explained in cmUseGlobalNameTbl().
  149.     
  150.     This function returns the pointer if we can allocate the control block. NULL is returned
  151.     if the allocation fails.
  152.     */
  153.     
  154.     
  155. void *cmUseGlobalNameTbl(void *table, ContainerPtr container);
  156.     /*
  157.     This allows multiple users of the same global name symbol for the specified container. 
  158.     This can come about due to updating containers which want to use the global name table of
  159.     their target.  They call this routine to register the additional use of the specified 
  160.     table.  It is also returned as the function result.
  161.     
  162.     Here we register the additional use by incrementing a use count of the table.  When
  163.     cmFreeAllGlobalNames() is called to remove the global names it will decrement the use
  164.     count.  Only when the count goes to 0 is the data actually freed.
  165.     */
  166.     
  167.  
  168. char *cmIsGlobalNameObject(TOCObjectPtr typePropertyObject, CM_ULONG objectID);
  169.     /*
  170.     Given a pointer to a type or property object, which is expected to have the corresponding
  171.     standard global name object ID defined by the macros CM_StdObjID_GlobalTypeName and 
  172.     CM_StdObjID_GlobalPropName, return the pointer to the global name string if the object is
  173.     indeed for a global name.  NULL is returned if the object isn't for a global type or
  174.     property name.
  175.     */
  176.     
  177.     
  178. char *cmGetGlobalTypeName(ContainerPtr container, CM_ULONG typeID);
  179.     /*
  180.     This routine takes an object ID assumed to be a type object, and returns the global name
  181.     for that type.  A string is always returned.  If the ID does not correspond to a type,
  182.     "?" is returned as the string.
  183.     
  184.     Note, this routine differs from cmIsGlobalNameObject() in that here an object ID is
  185.     converted to its corresponding global name.  In cmIsGlobalNameObject(), it is assumed the
  186.     object has already been found.  So all we have to do here is do the find and then call
  187.     cmIsGlobalNameObject() to get the name.
  188.     */
  189.     
  190.     
  191. char *cmGetGlobalPropertyName(ContainerPtr container, CM_ULONG propertyID);
  192.     /*
  193.     This routine takes an object ID assumed to be a property object, and returns the global
  194.     name for that property.  A string is always returned.  If the ID does not correspond to a
  195.     type, "?" is returned as the string.
  196.     
  197.     Note, this routine differs from cmIsGlobalNameObject() in that here an object ID is
  198.     converted to its corresponding global name.  In cmIsGlobalNameObject(), it is assumed the
  199.     object has already been found.  So all we have to do here is do the find and then call
  200.     cmIsGlobalNameObject() to get the name.  This is exactly like cmGetGlobalTypeName() but
  201.     for property names instead of types.
  202.     
  203.     Both these routines are mainly used to generate error message inserts.
  204.     */
  205.  
  206.  
  207. #define MarkGlobalNameDeleted(g) ((GlobalNamePtr)(g))->theValue = NULL
  208.     /*
  209.     Marks a global name symbol pointed to by "g" as deleted.  Such an entry will not be
  210.     written to the container.  It is assumed that if there is an object's value pointing to
  211.     this entry, it will never be used (and should itself be deleted).
  212.     */
  213.  
  214.  
  215. #define GetGlobalNameValueBackPtr(g) (((GlobalNamePtr)(g))->theValue)
  216.     /*
  217.     This generates the TOCValue back pointer from a global name symbol table entry pointed to
  218.     by "g".
  219.     */
  220.  
  221.  
  222. #define SetGlobalNameValueBackPtr(g, v) ((GlobalNamePtr)(g))->theValue = (v)
  223.     /*
  224.     This sets the TOCValue back pointer field of a global name symbol table entry pointed to
  225.     by "g" to the value specified by "v".
  226.     */
  227.  
  228.  
  229. #define GetGlobalName(g) (((GlobalNamePtr)(g))->globalName)
  230.     /*
  231.     This generates a pointer to the global name string in a global name symbol table entry
  232.     pointed to by "g".
  233.     */
  234.  
  235.  
  236. #define GetGlobalNameLength(g) (strlen((char *)GetGlobalName(g)))
  237.     /*
  238.     This produces the length of a global name string in a global name symbol table entry
  239.     pointed to by "g".  This length does NOT include the delimiting null at the end of the
  240.     string.
  241.     */
  242.  
  243.  
  244. GlobalNamePtr cmCreateGlobalName(const void *table, const CM_UCHAR *globalName,
  245.                                                                  CMBoolean *dup);
  246.     /*
  247.     Creates and defines a new global name symbol table entry in the specified global name
  248.     table.  A global name symbol table entry consists of the name and a back pointer to the
  249.     TOCValue which will point to the symbol table entry to be able to get the value data. The
  250.     back pointer is set to NULL in the newly defined global name entry returned from here.
  251.     
  252.     The function returns a pointer to the created definition.  If dup is true, a pointer to
  253.     a previously defined entry is returned.  If NULL is returned then there was an allocation
  254.     failure and the new type could not be created.
  255.  
  256.     The back pointer is used (when cmWriteAllGlobalNames() is called) when we write global
  257.     names to the container to allow us to fill in the ACTUAL TOC value data with the
  258.     container offset to the value.     We make sure we write the global names to the container
  259.     before we write the TOC.  Thus by the time the TOC is written the offsets will be known.
  260.     
  261.     Note, it is assumed that the back pointer will be set by the caller of 
  262.     cmDefineGlobalName().
  263.     */
  264.  
  265.  
  266. GlobalNamePtr cmEnterGlobalName(const void *table, GlobalNamePtr createdGlobalName,
  267.                                                                 CMBoolean *dup);
  268.     /*
  269.     This routine takes a previously created global name symbol table entry end enters it into
  270.     the global name table.
  271.  
  272.     The function returns the entry pointer as its result when dup is false. It may NOT be the
  273.     input pointer if we are reusing a previously deleted entry.  In that case the input
  274.     pointer is freed.  
  275.     
  276.     If dup is true, a pointer to a previously defined entry is returned.
  277.     
  278.     This routine differs from cmCreateGlobalName() above in that here no global name entry
  279.     is allocated.  Indeed cmCreateGlobalName() does call this routine after it does its
  280.     allocation.  This routine is also called by buildGlobalNameTable() in  TOCEnts.c   to
  281.     enter read global names into the table.
  282.     
  283.     Caution: The caller should have only entered the name into the entry prior to call.  This
  284.                      is because we could return a pointer to a previously freed entry.
  285.     */
  286.     
  287.     
  288. GlobalNamePtr cmLookupGlobalName(const void *table, const CM_UCHAR *globalName);
  289.     /*
  290.   Finds the specified global name defined in the specified global name table.  If found,
  291.   the GlobalNamePtr to the found entry is returned.  If not found NULL is returned.
  292.     
  293.     Note, we allocate a temporary global name table entry here and then free it.  If the
  294.     allocation fails, SessionSuccess, a session status switch, is returned false.  Otherwise
  295.     SessionSuccess is true.
  296.     */
  297.  
  298.  
  299. TOCObjectPtr cmDefineGlobalNameObject(const ContainerPtr container, CM_ULONG objectID,
  300.                                                                           CM_ULONG propertyID, CM_ULONG typeID, 
  301.                                                                             CM_UCHAR *globalName, CM_ULONG generation,
  302.                                                                             CM_USHORT flags, CM_USHORT objectFlags);
  303.     /*
  304.     This routine is called to define an TOC object corresponding to a global name in the
  305.     specified container.  It is a special case of the more general cmDefineObject() routine.
  306.     See that routine for a discussion on the parameters.
  307.  
  308.     The function returns a pointer to the object if it was successfully created and NULL if
  309.     it wasn't.  An error is reported if NULL is returned.  Note, while error calls are not
  310.     supposed to return we assume here they due just to be safe!
  311.     
  312.     The only difference between this routine and cmDefineObject() is that the value is passed
  313.     as a global name string instead of a built TOCValueBytes structure.  Finally, we don't
  314.     bother returning a pointer to the value's header because here we should only have one
  315.     value for the global name.  We can always get at it if we need to through the object
  316.     itself.
  317.      
  318.     Here we take the string and build a TOCValueBytes value to point to a global name symbol
  319.     table entry which is also created from here.  The symbol table entry will have a back
  320.     pointer to the value entry we create for the object.
  321.     
  322.     The flags and objectFlags are passed just as in cmDefineObject().  However, the flags are
  323.     ORed with the kCMGlobalName flag.  This marks the value as unique and as a value with a
  324.     pointer to a global name symbol table entry. The ValueGlobal flag echos this in the value
  325.     valueHdr.
  326.     
  327.     The main reasons we don't use cmDefineObject() directly is because of the extra work
  328.     needed to be done for global names to set the back pointer in their entries. We can also
  329.     do the extra checks for attempts at multiply defining a global name object.
  330.     */
  331.     
  332.     
  333. int cmForEachGlobalName(const void *table, CMRefCon refCon,
  334.                                                 void (*action)(GlobalNamePtr globalName, CMRefCon refCon));
  335.     /*
  336.     Do (call) the specified action for each defined global name in the specified global name
  337.     symbol table. The pointer to each global name entry is passed to the action routine along
  338.     with a "refCon" which the caller can use as a communication facility to convey additional
  339.     info to the action routine. 0 is returned to indicate successfull completion.  Use the
  340.     AbortForEachGlobalName(x) (a macro) in the action routine to abort the interator.  The 
  341.     "x" is a integer which is returned from cmForEachGlobalName() so it should not be 0. 
  342.     */
  343.  
  344.  
  345. #define AbortForEachGlobalName(x) longjmp(SESSION->cmForEachGlobalNameEnv, x)
  346.     /*
  347.     Use this in routines passed to forEachGlobalName() to abort the interator. The value of x
  348.     is returned from forEachGlobalName().  It should be non-zero since 0 is the "success"
  349.     return value for forEachGlobalName().  It is assumed that the variable "container" is
  350.     the current container pointer.
  351.     */
  352.  
  353.  
  354. CMBoolean cmWriteAllGlobalNames(const void *table);
  355.     /*
  356.     This routine is called by CMCloseContainer() just prior to writing the TOC to the
  357.     container to make sure all the global names in the specified global name symbol table are
  358.     written to the (end of the) container first.  Global names are thus the last data objects
  359.     in a container before the TOC.
  360.  
  361.     The function returns true if the global names were successfully written and false
  362.     otherwise.  As usual this is as safety since the error handler should not normmaly
  363.     return.
  364.     
  365.     Note, only global names in the specified symbol table that are "owned" by the container
  366.     are written.  A container used to update a target container utilize a global symbol table
  367.     common to both.  However, only NEW global names  that are to be recorded as belonging to
  368.     the updating container are to be written into that container.
  369.     
  370.     We keep global names in memory to make it easier to get at them for such API routines as
  371.     CMGetGlobalName().  Another use is to efficiently determine if there are attempts at
  372.     multiple definitions (CMRegister...()) of the same global name.
  373.     
  374.     The price we pay for this is a complication of TOC entries in that the corresponding 
  375.     value for a global name is NOT a container offset prior to writing.  It is a pointer to
  376.     its global name symbol table entry!  By the time we return from here an offset WILL be
  377.     in the value along with the symbol table pointer.  Funny thing about that!  Just in time
  378.     for the TOC write.
  379.     */
  380.  
  381. void cmFreeAllGlobalNames(void **table);
  382.     /*
  383.     This routine is called to remove the definitions of ALL previously defined global names
  384.     in the specified global name symbol table for a container.  The caller's symbol table
  385.     pointer is set to NULL prior to return.
  386.  
  387.   Note, there may be multiple users of a global name symbol table.  Thus its use count is
  388.   passed.  It is decremented and the symbol table only freed if the count goes to 0.
  389.     */
  390.  
  391.  
  392.                                                           CM_END_CFUNCTIONS
  393. #endif
  394.