home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / SYMTBMGR.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  8KB  |  182 lines
  1. /* @(#)Z 1.4 com/src/cm/SymTbMgr.h, odstorage, od96os2, odos29646d 96/11/15 15:27:15 (96/10/29 09:19:22) */
  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:        SymTbMgr.h
  31.  
  32.     Contains:    Container Manager Binary Tree Symbol 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 The compare function in
  43.                                     lookUpSymbol now compare name to symbol
  44.                                     rather than symbol to symbol.
  45.          <1>      2/3/94    EL        first checked in
  46.  
  47.     To Do:
  48. */
  49.  
  50. /*---------------------------------------------------------------------------*
  51.  |                                                                           |
  52.  |                         <<<    SymTbMgr.h    >>>                          |
  53.  |                                                                           |
  54.  |              Container Manager Binary Tree Symbol Interfaces              |
  55.  |                                                                           |
  56.  |                               Ira L. Ruben                                |
  57.  |                                 11/18/91                                  |
  58.  |                                                                           |
  59.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  60.  |                           All rights reserved.                            |
  61.  |                                                                           |
  62.  *---------------------------------------------------------------------------*
  63.  
  64.  The SymbolTableMgr contains all the generic symbol table routines.  They are in the form
  65.  of binary trees.  The three routines cmEnterSymbol(), cmLookupSymbol(), and
  66.  cmForEachSymbol() are the low level generic binary tree manipulators which higher level
  67.  "glue" routines use.
  68.  
  69.  All structs that are to be maintained as binary trees with this package must be of the
  70.  form:
  71.  
  72.                  struct {
  73.                     SymbolLinks theLinks;
  74.                     ...
  75.                 }...;
  76.                 
  77.  In other words, a field (any name will do) of type SymbolLinks MUST be the first field
  78.  of the structure.  The caller allocates all the struct symbol table entries.  This
  79.  package enters them into a symbol table based on a tree root pointer and maintains the
  80.  SymbolLinks.
  81.  
  82.  Being a generic package the links have to be at a know place in an otherwise arbitrary
  83.  struct.  Hence the position requirement.
  84. */
  85.  
  86.  
  87. #ifndef __SYMMGR__
  88. #define __SYMMGR__
  89.  
  90.  
  91. #ifndef __CMTYPES__
  92. #include "CMTypes.h"
  93. #endif
  94. #ifndef __CM_API_TYPES__
  95. #include "CMAPITyp.h"
  96. #endif
  97.  
  98. struct SessionGlobalData;
  99.                                                                     CM_CFUNCTIONS
  100.  
  101.  
  102. struct SymbolLinks {                                                        /* must be the first field in any symbol*/
  103.     struct SymbolLinks *lLink, *rLink;                        /*        left/right binary tree links            */
  104. };
  105. typedef struct SymbolLinks SymbolLinks, *SymbolLinksPtr;
  106.  
  107.  
  108. void *cmEnterSymbol(const void *symbol, void **root, Boolean *dup,
  109.                                         int (*compare)(const void *, const void *));
  110.     /*
  111.     Enter the specified symbol into its own binary tree symbol table with the specified root.
  112.     The function returns a pointer to the entry if entered.  If the entry is already there,
  113.     the pointer to the dup entry is returned, dup is set to true, and no other action taken.
  114.     
  115.     It is assumed the space for the new symbol has already been allocated and its pointer
  116.     passed as the symbol here.
  117.     
  118.     The binary tree is searched utilizing a comparison function provided by the caller.
  119.     Compare is function that takes as arguments pointers to two symbols and returns -1 if the
  120.     first symbol is "less than" the second, 1 if the first symbol is "greater than" the 
  121.     second, and 0 if the tow symbols are equal.
  122.     */
  123.  
  124.  
  125. void *cmLookupSymbol(const CM_UCHAR *name, const void *root,
  126.                                           int (*compare)(const void *, const CM_UCHAR *));
  127.  /*
  128.     Look up the specified symbol in its binary tree symbol table which starts at the
  129.     specified root.  Return the pointer to it if found and NULL if not found.
  130.  
  131.     The binary tree is searched utilizing a comparison function provided by the caller. 
  132.     Compare is function that takes as arguments pointers to two symbols and returns -1 if the
  133.     first symbol is "less than" the second, 1 if the first symbol is "greater than" the 
  134.     second, and 0 if the tow symbols are equal.
  135.      
  136.     It used to be that both arguments of compare are symbols, but that requires the
  137.     temporary geneation of a symbol during lookup. So we change the comparision to
  138.     a symbol and a name to improve the performance.
  139.     */
  140.  
  141.  
  142. void cmForEachSymbol(const void *symbol, CMRefCon refCon,
  143.                                           void (*action)(void *symbol, CMRefCon refCon));
  144.     /*
  145.     Do (call) the specified action for each entry in a binary tree symbol table. This
  146.     routine recursively traverses the binary tree calling (*action)() on each entry visited.
  147.     The pointer to the entry is passed to the action routine along with a "refCon" which the
  148.     caller can use as a communication facility to convey additional info to the action
  149.     routine.
  150.     
  151.     The search in the binary tree starts at the specified symbol location.  Generally this
  152.     will be a root of a tree, but need not be.  Tree traversal is such that the symbols are
  153.     visited in "ascending" order, i.e., whatever order that was used by the compare
  154.     function passed to cmEnterSymbol().
  155.     */
  156.     
  157.     
  158. typedef void (*SymbolAction)(void *, CMRefCon);
  159.     /*
  160.     The cmForEachSymbol() action routine is defined as the generic action routine to call
  161.     for a table consisting of symbols of a particular type.  Calling cmForEachSymbol() will
  162.     thus require casting the callers action routine to the generic type.  This typedef is
  163.     used for that purpose.  It must be here under the exter "C" C++ linkage specification
  164.     so that the cast, like the cmForEachSymbol() proptotype uses C calling conventions.
  165.     */ 
  166.     
  167.     
  168. void cmFreeAllSymbols(void **root, struct SessionGlobalData *sessionData);
  169.     /*
  170.   This routine takes a root of a binary tree symbol table and deletes ALL the entries in
  171.   the table.  The root pointer is returned as NULL.
  172.  
  173.     Note, that SymbolTableMgr routines are low level routines used in a number of contexts.
  174.     Here we need to uutilize the container memory deallocator handler.  Because we don't
  175.     know the context, which may be global, the session global data pointer is passed and we
  176.     access the handler through that.
  177.     */
  178.     
  179.     
  180.                                                           CM_END_CFUNCTIONS
  181. #endif
  182.