home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / LISTMGR.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  12KB  |  328 lines
  1. /* @(#)Z 1.4 com/src/cm/ListMgr.h, odstorage, od96os2, odos29646d 96/11/15 15:27:13 (96/10/29 09:19:02) */
  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:        ListMgr.h
  31.  
  32.     Contains:    Container Manager Doubly Linked Lists 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        #1181622 Ownership update.
  43.  
  44.     To Do:
  45. */
  46.  
  47. /*---------------------------------------------------------------------------*
  48.  |                                                                           |
  49.  |                             <<< ListMgr.h >>>                             |
  50.  |                                                                           |
  51.  |              Container Manager Doubly Linked Lists Interfaces             |
  52.  |                                                                           |
  53.  |                               Ira L. Ruben                                |
  54.  |                                 11/26/91                                  |
  55.  |                                                                           |
  56.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  57.  |                           All rights reserved.                            |
  58.  |                                                                           |
  59.  *---------------------------------------------------------------------------*
  60.  
  61.  The ListMgr package contains all the generic doubly linked list routines. The routines are
  62.  the low level generic doubly linked list manipulators which the higher level "glue"
  63.  routines use.
  64.  
  65.  All structs list cells that are to be maintained as doubly linked lists with this package
  66.  must be of the form:
  67.  
  68.                  struct {
  69.                     ListLinksPtr theLinks;
  70.                     ...
  71.                 }...;
  72.                 
  73.  In other words, a field (any name will do) of type ListLinksPtr MUST be the first field
  74.  of the struct.  The caller allocates all the struct list cells.  This package enters
  75.  them into a list based whose head and tail are pointed to by a header which takes the
  76.  following form:
  77.  
  78.                  struct {
  79.                     ListHdr theListHeader;
  80.                     ...
  81.                 }...;
  82.  
  83.  This is similar to the list entries themselves.  Here a ListHdr is the first field of
  84.  some structure.  Note, it is NOT necessary to make the ListHdr the first entry of a
  85.  larger structure if you pass the pointer to ListHdr pointer explicitly as the list
  86.  header pointer to any of the list routines defined here.
  87.  
  88.  Being a generic package the links and the header have to be at a know place in otherwise
  89.  arbitrary structs.  Hence the position requirements.
  90. */
  91.  
  92.  
  93. #ifndef __LISTMGR__
  94. #define __LISTMGR__
  95.  
  96. #ifndef __CM_API_TYPES__
  97. #include "CMAPITyp.h"
  98. #endif
  99.  
  100. struct SessionGlobalData;
  101.  
  102.                                                                     CM_CFUNCTIONS
  103.  
  104. struct ListLinks {                                                    /* must be the first field in any list entry */
  105.     struct ListLinks *next, *prev;                        /*        next/previous list links                             */
  106. };
  107. typedef struct ListLinks ListLinks, *ListLinksPtr;
  108.  
  109. struct ListHdr {                                                        /* all list headers must look like this            */
  110.     ListLinksPtr     head, tail;                                    /*         head/tail of the list                                    */
  111.     CM_ULONG        nbrOfCells;                                    /*        number of cells on the list                        */
  112. };                                                                                    /* struct can be 1st thin in a larger struct*/
  113. typedef struct ListHdr ListHdr, *ListHdrPtr;
  114.  
  115. #ifndef LISTMACROS                                                    
  116. #define LISTMACROS 1                                                /* 0 for less optimum function calls                */
  117. #endif
  118.  
  119.  
  120. void *cmInitList(const void *theList);
  121.     /*
  122.     This routine takes a list header and initializes the head and tail pointers to NULL.  All
  123.     empty lists are assumed to have NULL head and tail pointers.  The function returns the
  124.     input header pointer as its result.
  125.     */
  126.     
  127.     
  128. void *cmInsertBeforeListCell(const void *theList, const void *theCell, const void *beforeThisCell);
  129.     /*
  130.     Given a pointer to a list header (theList), this routine inserts a new cell (theCell)
  131.     before another cell already on the list (beforeThisCell).  The function returns the
  132.     input inserted cell pointer as its result.
  133.     
  134.     If beforeThisCell is NULL this function inserts theCell at the beginning of the list.
  135.     
  136.     If theCell is NULL, nothing is done and NULL is returned.
  137.     */
  138.     
  139.     
  140. void *cmInsertAfterListCell(const void *theList, const void *theCell, const void *afterThisCell);
  141.     /*
  142.     Given a pointer to a list header (theList), this routine inserts a new cell (theCell)
  143.     after another cell already on the list (beforeThisCell).  The function returns the
  144.     input inserted cell pointer as its result.
  145.     
  146.     If afterThisCell is NULL this function appends theCell to the end of the list.
  147.     
  148.     If theCell is NULL, nothing is done and NULL is returned.
  149.     */
  150.     
  151.     
  152. void *cmAppendListCell(const void *theList, const void *theCell);
  153.     /*
  154.     This function is the same as a cmInsertAfterListCell(theList, theCell, NULL), i.e., 
  155.     theCell is appended to the end of the list.  The function returns the input inserted
  156.     cell pointer as its result.
  157.     
  158.     If theCell is NULL, nothing is done and NULL is returned.
  159.     */
  160.     
  161.     
  162. void *cmDeleteListCell(const void *theList, const void *theCell);
  163.     /*
  164.     This function removes the specified cell (theCell) from a list whose header is pointed
  165.     to by theList.  It is up to the caller to free the memory occupied by the cell.  Here
  166.   it is simply "jump out" of the list link structure.  The input cell pointer (theCell) is
  167.   returned as the function result.
  168.  
  169.     If theCell is NULL, nothing is done and NULL is returned.
  170.     */
  171.     
  172.     
  173. #if LISTMACROS
  174. #define cmGetNextListCell(currCell) ((void *)(((ListLinksPtr)(currCell))->next))
  175. #else
  176. void *cmGetNextListCell(void *currCell);
  177.     /*
  178.   Given a pointer to a list cell, this function returns the pointer to the next cell on
  179.   the list or NULL if there is no next cell.
  180.  
  181.   NULL is also returned if the input cell pointer is NULL.
  182.     */
  183. #endif
  184.  
  185.     
  186. #if LISTMACROS
  187. #define cmGetPrevListCell(currCell) ((void *)(((ListLinksPtr)(currCell))->prev))
  188. #else
  189. void *cmGetPrevListCell(void *currCell);
  190.     /*
  191.   Given a pointer to a list cell, this function returns the pointer to the previous cell
  192.   on the list or NULL if there is no previous cell.
  193.   
  194.   NULL is also returned if the input cell pointer is NULL.
  195.     */
  196. #endif
  197.     
  198.     
  199. #if LISTMACROS
  200. #define cmCountListCells(theList) ((long)(((ListHdrPtr)(theList))->nbrOfCells))
  201. #else
  202. CM_ULONG cmCountListCells(const void *theList);
  203.     /*
  204.   This function can be used to determine the number of cells in a list.  0 is returned if
  205.   the list is currently empty. It is assumed that the list has been previously initialized
  206.   by cmInitList().
  207.     */
  208. #endif
  209.     
  210.     
  211. #if LISTMACROS
  212. #define cmIsEmptyList(theList) (((ListHdrPtr)(theList))->nbrOfCells == 0)
  213. #else
  214. CMBoolean cmIsEmptyList(const void *theList);
  215.     /*
  216.   This function returns true if the specified list is empty (i.e., contains no cells) and
  217.   false otherwise (i.e., contains cells).
  218.     */
  219. #endif
  220.  
  221.  
  222. #if LISTMACROS
  223. #define cmGetListHead(theList) ((void *)(((ListHdrPtr)(theList))->head))
  224. #else
  225. void *cmGetListHead(const void *theList);
  226.     /*
  227.     Return the pointer to the head of a list.
  228.     */
  229. #endif
  230.     
  231.  
  232. #if LISTMACROS
  233. #define cmGetListTail(theList) ((void *)(((ListHdrPtr)(theList))->tail))
  234. #else
  235. void *cmGetListTail(const void *theList);
  236.     /*
  237.     Return the pointer to the tail of a list.
  238.     */
  239. #endif
  240.  
  241.  
  242. #if LISTMACROS
  243. #define cmNullListLinks(theCell) (((ListLinksPtr)(theCell))->prev = ((ListLinksPtr)(theCell))->next = NULL, (void *)(theCell))
  244. #else
  245. void *cmNullListLinks(void *theCell);
  246.     /*
  247.     Force the links in a list cell to NULL.  This is generally done as a safety measure
  248.     after a cell is allocated.  If the cell finds its way into a linked list then most list
  249.     walkers will be happy with NULL list links if they see them.  "Bad" cells like these
  250.     could arise from error conditions which may be seen during a cleanup.
  251.     */
  252. #endif
  253.     
  254.     
  255. void *cmGetNthListCell(const void *theList, const CM_ULONG n);
  256.     /*
  257.   This function returns a pointer to the N'th cell (counting from 1) on a list whose
  258.   header is pointed to by theList.  NULL is returned if there is no N'th list item.
  259.     */
  260.     
  261.     
  262. void *cmInsertBeforeNthListCell(const void *theList, const void *theCell, const CM_ULONG n);
  263.     /*
  264.     This function inserts the specified cell (theCell) before the N'th cell (counting from
  265.     1) on the list whose header is pointed to by theList.  The function returns the input
  266.     inserted cell pointer as its result.
  267.     
  268.     Nothing is inserted and NULL is returned if if there is no N'th list item or theCell is
  269.     NULL.
  270.     */
  271.     
  272.     
  273. void *cmInsertAfterNthListCell(const void *theList, const void *theCell, const CM_ULONG n);    
  274.     /*
  275.     This function inserts the specified cell (theCell) after the N'th cell (counting from
  276.     1) on the list whose header is pointed to by theList.  The function returns the input
  277.     inserted cell pointer as its result.
  278.     
  279.     Nothing is inserted and NULL is returned if if there is no N'th list item or theCell is
  280.     NULL.
  281.     */
  282.  
  283.  
  284. void *cmInsertNthListCell(const void *theList, const void *theCell, const CM_ULONG n);
  285.     /*
  286.     This function makes the specified cell (theCell) the N'th cell (counting from 1) on the
  287.     list whose header is pointed to by theList.  The function returns the input inserted
  288.     cell pointer as its result.
  289.     
  290.     Nothing is inserted and NULL is returned or if N is specified as 0 or 1 greater than
  291.     the total number of cells currently on the list.  NULL is also returned if theCell is
  292.     NULL.
  293.     
  294.     If N is specified a 1 greater than the total number of cells currently on the list then
  295.     the new cell is APPENDED to the end of the list.  If N is anything less, the new cell
  296.     is inserted BEFORE the old N'th cell.  Thus the new cell becomes the N'th cell.
  297.     */
  298.     
  299.     
  300. CM_ULONG cmGetCellPosition(const void *theList, const void *theCell);
  301.     /*
  302.     This function returns the position index, 1 to N, of the cell (theCell) in the list whose
  303.     header is pointed to by theList.  The function returns 0 if theCell cannot be found in 
  304.     theList.
  305.     */
  306.     
  307.  
  308. void cmForEachListCell(const void *theList, CMRefCon refCon,
  309.                                               void (*action)(void *cell, CMRefCon refCon));
  310.     /*
  311.     Do (call) the specified action for each cell on the specified list whose header is 
  312.     pointed to by theList. This routine calls (*action)() on each cell along with a "refCon"
  313.     which the caller can use as a communication facility to convey additional info to the
  314.     action routine.  The pointer to the cell is passed to the action routine.
  315.     */
  316.     
  317.     
  318. void cmFreeAllListCells(const void *theList, struct SessionGlobalData *sessionData);
  319.     /*
  320.     This routine removes (i.e., free()s) all the cells from the specified list.  The list
  321.     header is reinitialized.  Because it uses the memory deallocator it need the global data
  322.     session pointer.
  323.     */
  324.     
  325.  
  326.                                                           CM_END_CFUNCTIONS
  327. #endif
  328.