home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / lvmtlk12.zip / include / lvm_list.h < prev    next >
C/C++ Source or Header  |  2001-09-12  |  143KB  |  2,129 lines

  1. /*
  2. *
  3. *   Copyright (c) International Business Machines  Corp., 2000
  4. *
  5. *   This program is free software;  you can redistribute it and/or modify
  6. *   it under the terms of the GNU General Public License as published by
  7. *   the Free Software Foundation; either version 2 of the License, or
  8. *   (at your option) any later version.
  9. *
  10. *   This program is distributed in the hope that it will be useful,
  11. *   but WITHOUT ANY WARRANTY;  without even the implied warranty of
  12. *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
  13. *   the GNU General Public License for more details.
  14. *
  15. *   You should have received a copy of the GNU General Public License
  16. *   along with this program;  if not, write to the Free Software
  17. *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18. *
  19. * Module: lvm_list.h
  20. */
  21.  
  22. /*
  23. * Change History:
  24. *
  25. */
  26.  
  27. /*
  28. * Functions: DLIST       CreateList
  29. *            void        InsertItem
  30. *            void        InsertObject
  31. *            void        GetItem
  32. *            void        GetNextItem
  33. *            void        GetPreviousItem
  34. *            ADDRESS     GetObject
  35. *            ADDRESS     GetNextObject
  36. *            ADDRESS     GetPreviousObject
  37. *            void        ExtractItem
  38. *            ADDRESS     ExtractObject
  39. *            void        ReplaceItem
  40. *            ADDRESS     ReplaceObject
  41. *            void        DeleteItem
  42. *            TAG         GetTag
  43. *            ADDRESS     GetHandle
  44. *            CARDINAL32  GetListSize
  45. *            BOOLEAN     ListEmpty
  46. *            BOOLEAN     AtEndOfList
  47. *            BOOLEAN     AtStartOfList
  48. *            void        DestroyList
  49. *            void        NextItem
  50. *            void        PreviousItem
  51. *            void        GoToStartOfList
  52. *            void        GoToEndOfList
  53. *            void        GoToSpecifiedItem
  54. *            void        SortList
  55. *            void        ForEachItem
  56. *            void        PruneList
  57. *            void        AppendList
  58. *            void        TransferItem
  59. *
  60. * Description:  This module implements a simple, generic, doubly linked list.
  61. *               Data objects of any type can be placed into a linked list
  62. *               created by this module.  Futhermore, data objects of different
  63. *               types may be placed into the same linked list.
  64. *
  65. * Notes:  This linked list implementation makes use of the concept of the
  66. *         current item.  In any non-empty list, one item in the list will
  67. *         be designated as the current item.  When any of the following
  68. *         functions are called, they will operate upon the current item
  69. *         only: GetItem, ReplaceItem, DeleteItem, GetTag, NextItem,
  70. *         PreviousItem, GetObject, ExtractItem, and ExtractObject.  The
  71. *         user of this module may set the current item through the use of
  72. *         the GoToStartOfList, GoToEndOfList, NextItem, PreviousItem,
  73. *         and GoToSpecifiedItem functions.
  74. *
  75. *         Since a linked list created by this module may contain items
  76. *         of different types, the user will need a way to identify items
  77. *         of different types which may be in the same list.  To allow users
  78. *         to do this, the concept of an item tag is used.  When an item is
  79. *         added to the list, the user must enter an item tag.  The item
  80. *         tag is merely some identifier that the user wishes to associate
  81. *         with the item being placed into the list.  When used as intended,
  82. *         each type of data item will have a unique tag associated with it.
  83. *         This way, all data items of the same type will have the same tag
  84. *         while data items of different types will have different tags.
  85. *         Thus, by using the GetTag function, the user can get the item
  86. *         tag for the current item without having to get the item from the
  87. *         list.  This allows the user to differentiate between items of
  88. *         different types which reside in the same list.
  89. *
  90. *         This module is single threaded.  If used in a multi-threaded
  91. *         environment, the user must implement appropriate access controls.
  92. *
  93. *         When an item is inserted or appended to a list, this module
  94. *         allocates memory on the heap to hold the item and then copies
  95. *         the item to the memory that it allocated.  This allows local
  96. *         variables to be safely inserted or appended to a list.  However,
  97. *         it should be noted that under certain circumstances a copy of the
  98. *         entire data item will NOT be made.  Specifically, if the data item
  99. *         is a structure or array containing pointers, then the data pointed
  100. *         to by the pointers will NOT be copied even though the structure or
  101. *         array is!  This results from the fact that, when an item is being
  102. *         inserted or appended to a list, the user provides just an address
  103. *         and size.  This module assumes that the item to inserted or append
  104. *         lies in a contiguous block of memory at the address provided by the
  105. *         user.  This module has no way of knowing the structure of the data
  106. *         at the specified address, and therefore can not know about any
  107. *         embedded pointers which may lie within that block of memory.
  108. *
  109. *         This module now employs the concept of a handle.  A handle is a
  110. *         reference to a specific item in a list which allows that item to
  111. *         be made the current item in the list quickly.  Example:  If you
  112. *         use the GetHandle function to get a handle for the current item
  113. *         (lets call the item B1), then, regardless of where you are in the
  114. *         list (or any reodering of the items in the list), you can make item
  115. *         B1 the current item by passing its handle to the GoToSpecifiedItem
  116. *         function.  Alternatively, you could operate directly on B1 using
  117. *         the other handle based functions, such as GetItem_By_Handle, for
  118. *         example.  GetItem_By_Handle gets the item associated with the
  119. *         specified handle without changing which item in the list is the
  120. *         current item in the list.
  121. *
  122. *         The functions of this module refer to user data as either items or
  123. *         objects.  The difference between the two is simple, yet subtle.  It
  124. *         deals with who is responsible for the memory used to hold the data.
  125. *         In the case of an item, this module is responsible for the memory
  126. *         used to hold the user data.  In the case of an object, the user
  127. *         is responsible for the memory used to hold the data.
  128. *
  129. *         What this means is that, for functions adding ITEMS to a list,
  130. *         this module will be responsible for allocating memory to hold
  131. *         the user data and then copying the user data into the memory
  132. *         that was allocated.  For functions which return items, this
  133. *         module will COPY the user data from the LIST into a buffer
  134. *         specified by the user.  For functions which add objects to a
  135. *         list, the user provides a pointer to a block of memory holding
  136. *         user data.  This block of memory was allocated by the user, and
  137. *         becomes the "property" of this module once it has been added to
  138. *         a LIST.  For functions which return objects, a pointer to the
  139. *         memory where the data is stored is returned.  As long as an item/object
  140. *         is in a LIST, this module will be responsible for the memory that
  141. *         is used to store the data associated with that item.  This means that
  142. *         users of this module should not call free on an object returned by this
  143. *         module as long as that object is still within a list.
  144. *
  145. *
  146. */
  147.  
  148. #ifndef LVM_DLISTHANDLER
  149.  
  150. #define LVM_DLISTHANDLER  1
  151.  
  152. /*--------------------------------------------------
  153. * Type definitions
  154. --------------------------------------------------*/
  155.  
  156. #include "LVM_GBLS.h"
  157.  
  158. typedef unsigned long TAG;
  159.  
  160. typedef ADDRESS DLIST;
  161.  
  162. /*--------------------------------------------------
  163. * Type definitions
  164. --------------------------------------------------*/
  165.  
  166. typedef enum _Insertion_Modes {
  167. InsertAtStart,
  168. InsertBefore,
  169. InsertAfter,
  170. AppendToList
  171. } Insertion_Modes;
  172.  
  173. /************************************************
  174. *           Functions Available                *
  175. ************************************************/
  176.  
  177. /*
  178. * The parameter *Error is set by every function in this module.  It
  179. * will be set to 0 to indicate success, and will be > 0 if an
  180. * error occurs.  The following table lists the possible error codes:
  181. *     0 : No error.
  182. *     1 : Out of memory
  183. *     2 : Memory has been corrupted!
  184. *     3 : Bad List Record!
  185. *     4 : List Record not initialized yet!
  186. *     5 : List is empty!
  187. *     6 : Item size mismatch!
  188. *     7 : Bad item pointer!
  189. *     8 : Item has zero size!
  190. *     9 : Item tag mismatch!
  191. *    10 : Already at end of list!
  192. *    11 : Already at start of list!
  193. *    12 : Bad Handle!
  194. *    13 : Invalid Insertion Mode!
  195. */
  196.  
  197. #define DLIST_SUCCESS                    0
  198. #define DLIST_OUT_OF_MEMORY              1
  199. #define DLIST_CORRUPTED                  2
  200. #define DLIST_BAD                        3
  201. #define DLIST_NOT_INITIALIZED            4
  202. #define DLIST_EMPTY                      5
  203. #define DLIST_ITEM_SIZE_WRONG            6
  204. #define DLIST_BAD_ITEM_POINTER           7
  205. #define DLIST_ITEM_SIZE_ZERO             8
  206. #define DLIST_ITEM_TAG_WRONG             9
  207. #define DLIST_END_OF_LIST               10
  208. #define DLIST_ALREADY_AT_START          11
  209. #define DLIST_BAD_HANDLE                12
  210. #define DLIST_INVALID_INSERTION_MODE    13
  211.  
  212. /* The following code is special.  It is for use with the PruneList and ForEachItem functions.  Basically, these functions
  213. can be thought of as "searching" a list.  They present each item in the list to a user supplied function which can then
  214. operate on the items.  If the user supplied function returns a non-zero error code, ForEachItem and PruneList abort and
  215. return an error to the caller.  This may be undesirable.  If the user supplied function used with PruneList and ForEachItem
  216. returns the code below, PruneList/ForEachItem will abort and return DLIST_SUCCESS.  This allows PruneList and ForEachItem
  217. to be used to search a list and terminate the search when the desired item is found without having to traverse the
  218. remaining items in the list.                                                                                                  */
  219. #define DLIST_SEARCH_COMPLETE  0xFF
  220.  
  221. #ifdef USE_POOLMAN
  222.  
  223. /*********************************************************************/
  224. /*                                                                   */
  225. /*   Function Name:  CreateList                                      */
  226. /*                                                                   */
  227. /*   Descriptive Name: This function allocates and initializes the   */
  228. /*                     data structures associated with a list and    */
  229. /*                     then returns a pointer to these structures.   */
  230. /*                                                                   */
  231. /*   Input: CARDINAL32 InitialPoolSize - Each List gets a pool of    */
  232. /*                                     link nodes.  When items are   */
  233. /*                                     added to the List, a link node*/
  234. /*                                     is removed from the pool.     */
  235. /*                                     When an item is removed from  */
  236. /*                                     the List, the link node used  */
  237. /*                                     for that item is returned to  */
  238. /*                                     the pool.  InitialPoolSize is */
  239. /*                                     the number of link nodes to   */
  240. /*                                     place in the pool when the    */
  241. /*                                     pool is created.              */
  242. /*          CARDINAL32 MaximumPoolSize - When the pool runs out of   */
  243. /*                                     link nodes, new nodes are     */
  244. /*                                     allocated by the pool.  When  */
  245. /*                                     these links start being       */
  246. /*                                     returned to the pool, the pool*/
  247. /*                                     will grow.  This parameter    */
  248. /*                                     puts a limit on how big the   */
  249. /*                                     pool may grow to.  Once the   */
  250. /*                                     pool reaches this size, any   */
  251. /*                                     link nodes being returned to  */
  252. /*                                     the pool will be deallocated. */
  253. /*          CARDINAL32 PoolIncrement - When the pool runs out of link*/
  254. /*                                   nodes and more are required,    */
  255. /*                                   the pool will allocate one or   */
  256. /*                                   more link nodes.  This tells the*/
  257. /*                                   pool how many link nodes to     */
  258. /*                                   allocate at one time.           */
  259. /*                                                                   */
  260. /*   Output: If Success : The function return value will be non-NULL */
  261. /*                                                                   */
  262. /*           If Failure : The function return value will be NULL.    */
  263. /*                                                                   */
  264. /*   Error Handling:  The function will only fail if it can not      */
  265. /*                    allocate enough memory to create the new list  */
  266. /*                    and its associated pool of link nodes.         */
  267. /*                                                                   */
  268. /*   Side Effects:  None.                                            */
  269. /*                                                                   */
  270. /*   Notes:  None.                                                   */
  271. /*                                                                   */
  272. /*********************************************************************/
  273. DLIST _System CreateList(CARDINAL32 InitialPoolSize,
  274. CARDINAL32 MaximumPoolSize,
  275. CARDINAL32 PoolIncrement);
  276.  
  277. #else
  278.  
  279. /*********************************************************************/
  280. /*                                                                   */
  281. /*   Function Name:  CreateList                                      */
  282. /*                                                                   */
  283. /*   Descriptive Name: This function allocates and initializes the   */
  284. /*                     data structures associated with a list and    */
  285. /*                     then returns a pointer to these structures.   */
  286. /*                                                                   */
  287. /*   Input: None.                                                    */
  288. /*                                                                   */
  289. /*   Output: If Success : The function return value will be non-NULL */
  290. /*                                                                   */
  291. /*           If Failure : The function return value will be NULL.    */
  292. /*                                                                   */
  293. /*   Error Handling:  The function will only fail if it can not      */
  294. /*                    allocate enough memory to create the new list. */
  295. /*                                                                   */
  296. /*   Side Effects:  None.                                            */
  297. /*                                                                   */
  298. /*   Notes:  None.                                                   */
  299. /*                                                                   */
  300. /*********************************************************************/
  301. DLIST _System CreateList( void );
  302.  
  303. #endif
  304.  
  305. /*********************************************************************/
  306. /*                                                                   */
  307. /*   Function Name: InsertItem                                       */
  308. /*                                                                   */
  309. /*   Descriptive Name:  This function inserts an item into a DLIST.  */
  310. /*                      The item can be placed either before or      */
  311. /*                      after the current item in the DLIST.         */
  312. /*                                                                   */
  313. /*   Input:  DLIST          ListToAddTo : The list to which the      */
  314. /*                                        data item is to be         */
  315. /*                                        added.                     */
  316. /*           CARDINAL32    ItemSize : The size of the data item, in  */
  317. /*                                    bytes.                         */
  318. /*           ADDRESS       ItemLocation : The address of the data    */
  319. /*                                        to append to the list      */
  320. /*           TAG           ItemTag : The item tag to associate with  */
  321. /*                                   item being appended to the list */
  322. /*           ADDRESS TargetHandle : The item in ListToAddTo which    */
  323. /*                                   is used to determine where      */
  324. /*                                   the item being transferred will */
  325. /*                                   be placed.  If this is NULL,    */
  326. /*                                   then the current item in        */
  327. /*                                   ListToAddTo will be used.       */
  328. /*           Insertion_Modes InsertMode : This indicates where,      */
  329. /*                                   relative to the item in         */
  330. /*                                   ListToAddTo specified by        */
  331. /*                                   Target_Handle, the item being   */
  332. /*                                   inserted can be placed.         */
  333. /*           BOOLEAN MakeCurrent : If TRUE, the item being inserted  */
  334. /*                                 into ListToAddTo becomes the      */
  335. /*                                 current item in ListToAddTo.      */
  336. /*           CARDINAL32 *  Error : The address of a variable to hold */
  337. /*                                 the error return code.            */
  338. /*                                                                   */
  339. /*   Output:  If the operation is successful, then *Error will be    */
  340. /*            set to 0 and the function return value will be the     */
  341. /*            handle for the item that was appended to the list.     */
  342. /*            If the operation fails, then *Error will contain an    */
  343. /*            error code and the function return value will be NULL. */
  344. /*                                                                   */
  345. /*   Error Handling: This function will fail under the following     */
  346. /*                   conditions:                                     */
  347. /*                       ListToAddTo does not point to a valid       */
  348. /*                           list                                    */
  349. /*                       ItemSize is 0                               */
  350. /*                       ItemLocation is NULL                        */
  351. /*                       The memory required to hold a copy of the   */
  352. /*                           item can not be allocated.              */
  353. /*                       The memory required to create a LINK NODE   */
  354. /*                           can not be allocated.                   */
  355. /*                       TargetHandle is invalid or is for an item   */
  356. /*                           in another list.                        */
  357. /*                   If this routine fails, an error code is returned*/
  358. /*                   and any memory allocated by this function is    */
  359. /*                   freed.                                          */
  360. /*                                                                   */
  361. /*   Side Effects: None.                                             */
  362. /*                                                                   */
  363. /*   Notes:  The item to add is copied to the heap to                */
  364. /*           avoid possible conflicts with the usage of              */
  365. /*           local variables in functions which process              */
  366. /*           DLISTs.  However, a pointer to a local variable         */
  367. /*           should not be appended to the DLIST.                    */
  368. /*                                                                   */
  369. /*           It is assumed that TargetHandle is valid, or is at least*/
  370. /*           the address of an accessible block of storage.  If      */
  371. /*           TargetHandle is invalid, or is not the address of an    */
  372. /*           accessible block of storage, then a trap or exception   */
  373. /*           may occur.                                              */
  374. /*                                                                   */
  375. /*           It is assumed that Error contains a valid address. It   */
  376. /*           is also assumed that if ItemLocation is not NULL, then  */
  377. /*           it is a valid address that can be dereferenced.  If     */
  378. /*           these assumptions are violated, an exception or trap    */
  379. /*           may occur.                                              */
  380. /*                                                                   */
  381. /*                                                                   */
  382. /*********************************************************************/
  383. ADDRESS _System InsertItem ( DLIST           ListToAddTo,
  384. CARDINAL32      ItemSize,
  385. ADDRESS         ItemLocation,
  386. TAG             ItemTag,
  387. ADDRESS         TargetHandle,
  388. Insertion_Modes Insert_Mode,
  389. BOOLEAN         MakeCurrent,
  390. CARDINAL32 *    Error);
  391.  
  392. /*********************************************************************/
  393. /*                                                                   */
  394. /*   Function Name: InsertObject                                     */
  395. /*                                                                   */
  396. /*   Descriptive Name:  This function inserts an object into a DLIST.*/
  397. /*                      The object can be inserted before or after   */
  398. /*                      the current item in the list.                */
  399. /*                                                                   */
  400. /*   Input:  DLIST          ListToAddTo : The list to which the      */
  401. /*                                          data object is to be     */
  402. /*                                          inserted.                */
  403. /*           CARDINAL32    ItemSize : The size of the data item, in  */
  404. /*                                    bytes.                         */
  405. /*           ADDRESS       ItemLocation : The address of the data    */
  406. /*                                        to append to the list      */
  407. /*           TAG           ItemTag : The item tag to associate with  */
  408. /*                                   the item being appended to the  */
  409. /*                                   list                            */
  410. /*           ADDRESS TargetHandle : The item in ListToAddTo which    */
  411. /*                                   is used to determine where      */
  412. /*                                   the item being transferred will */
  413. /*                                   be placed.  If this is NULL,    */
  414. /*                                   then the current item in        */
  415. /*                                   ListToAddTo will be used.       */
  416. /*           Insertion_Modes InsertMode : This indicates where,      */
  417. /*                                   relative to the item in         */
  418. /*                                   ListToAddTo specified by        */
  419. /*                                   Target_Handle, the item being   */
  420. /*                                   inserted can be placed.         */
  421. /*           BOOLEAN MakeCurrent : If TRUE, the item being inserted  */
  422. /*                                 into ListToAddTo becomes the      */
  423. /*                                 current item in ListToAddTo.      */
  424. /*           CARDINAL32 *  Error : The address of a variable to hold */
  425. /*                                 the error return code.            */
  426. /*                                                                   */
  427. /*   Output:  If the operation is successful, then *Error will be    */
  428. /*            set to 0 and the function return value will be the     */
  429. /*            handle for the item that was appended to the list.     */
  430. /*            If the operation fails, then *Error will contain an    */
  431. /*            error code and the function return value will be NULL. */
  432. /*                                                                   */
  433. /*   Error Handling: This function will fail under the following     */
  434. /*                   conditions:                                     */
  435. /*                       ListToAddTo does not point to a valid       */
  436. /*                           list                                    */
  437. /*                       ItemSize is 0                               */
  438. /*                       ItemLocation is NULL                        */
  439. /*                       The memory required for a LINK NODE can not */
  440. /*                           be allocated.                           */
  441. /*                       TargetHandle is invalid or is for an item   */
  442. /*                           in another list.                        */
  443. /*                   If this routine fails, an error code is returned*/
  444. /*                   and any memory allocated by this function is    */
  445. /*                   freed.                                          */
  446. /*                                                                   */
  447. /*   Side Effects: None.                                             */
  448. /*                                                                   */
  449. /*   Notes:  The item to insert is NOT copied to the heap.  Instead, */
  450. /*           the location of the item is stored in the list.  This   */
  451. /*           is the major difference between InsertObject and        */
  452. /*           InsertItem.  InsertItem allocates memory on the heap,   */
  453. /*           copies the item to the memory it allocated, and stores  */
  454. /*           the address of the memory it allocated in the list.     */
  455. /*           InsertObject stores the address provided by the user.   */
  456. /*                                                                   */
  457. /*           It is assumed that TargetHandle is valid, or is at least*/
  458. /*           the address of an accessible block of storage.  If      */
  459. /*           TargetHandle is invalid, or is not the address of an    */
  460. /*           accessible block of storage, then a trap or exception   */
  461. /*           may occur.                                              */
  462. /*                                                                   */
  463. /*           It is assumed that Error contains a valid address. It   */
  464. /*           is also assumed that if ItemLocation is not NULL, then  */
  465. /*           it is a valid address that can be dereferenced.  If     */
  466. /*           these assumptions are violated, an exception or trap    */
  467. /*           may occur.                                              */
  468. /*                                                                   */
  469. /*                                                                   */
  470. /*********************************************************************/
  471. ADDRESS _System InsertObject ( DLIST           ListToAddTo,
  472. CARDINAL32      ItemSize,
  473. ADDRESS         ItemLocation,
  474. TAG             ItemTag,
  475. ADDRESS         TargetHandle,
  476. Insertion_Modes Insert_Mode,
  477. BOOLEAN         MakeCurrent,
  478. CARDINAL32 *    Error);
  479.  
  480. /*********************************************************************/
  481. /*                                                                   */
  482. /*   Function Name:  DeleteItem                                      */
  483. /*                                                                   */
  484. /*   Descriptive Name:  This function removes the specified item from*/
  485. /*                      the list and optionally frees the memory     */
  486. /*                      associated with it.                          */
  487. /*                                                                   */
  488. /*   Input:  DLIST       ListToDeleteFrom : The list whose current   */
  489. /*                                         item is to be deleted.    */
  490. /*           BOOLEAN    FreeMemory : If TRUE, then the memory        */
  491. /*                                   associated with the current     */
  492. /*                                   item will be freed.  If FALSE   */
  493. /*                                   then the current item will be   */
  494. /*                                   removed from the list but its   */
  495. /*                                   memory will not be freed.       */
  496. /*           ADDRESS Handle : The handle of the item to get.  This   */
  497. /*                            handle must be of an item which resides*/
  498. /*                            in ListToDeleteFrom, or NULL.  If      */
  499. /*                            NULL is used, then the current item    */
  500. /*                            in ListToDeleteFrom will be deleted.   */
  501. /*           CARDINAL32 * Error : The address of a variable to hold  */
  502. /*                                 the error return code.            */
  503. /*                                                                   */
  504. /*   Output:  If the operation is successful, then *Error will be    */
  505. /*            set to 0.  If the operation fails, then *Error will    */
  506. /*            contain an error code.                                 */
  507. /*                                                                   */
  508. /*   Error Handling: This function will fail if ListToDeleteFrom is  */
  509. /*                   not a valid list, or if ListToDeleteFrom is     */
  510. /*                   empty, or if Handle is invalid.                 */
  511. /*                   If this routine fails, an error code is returned*/
  512. /*                   in *Error.                                      */
  513. /*                                                                   */
  514. /*   Side Effects:  None.                                            */
  515. /*                                                                   */
  516. /*   Notes:  Items in a list can be accessed in two ways:  A copy of */
  517. /*           the item can be obtained using GetItem and its related  */
  518. /*           calls, or a pointer to the item can be obtained using   */
  519. /*           GetObject and its related calls.  If you have a copy of */
  520. /*           the data and wish to remove the item from the list, set */
  521. /*           FreeMemory to TRUE.  This will remove the item from the */
  522. /*           list and deallocate the memory used to hold it.  If you */
  523. /*           have a pointer to the item in the list (from one of the */
  524. /*           GetObject style functions) and wish to remove the item  */
  525. /*           from the list, set FreeMemory to FALSE.  This removes   */
  526. /*           the item from the list without freeing its memory, so   */
  527. /*           that the pointer obtained with the GetObject style      */
  528. /*           functions is still useable.                             */
  529. /*                                                                   */
  530. /*           It is assumed that Error contains a valid address. If   */
  531. /*           this assumption is violated, an exception or trap       */
  532. /*           may occur.                                              */
  533. /*                                                                   */
  534. /*           It is assumed that Handle is valid, or is at least the  */
  535. /*           address of an accessible block of storage.  If Handle   */
  536. /*           is invalid, or is not the address of an accessible block*/
  537. /*           of storage, then a trap or exception may occur.         */
  538. /*           NOTE: For this function, NULL is considered a valid     */
  539. /*                 handle which refers to the current item in        */
  540. /*                 ListToDeleteFrom.                                 */
  541. /*                                                                   */
  542. /*           This function does not alter which item is the current  */
  543. /*           item in the list, unless the handle specified belongs   */
  544. /*           to the current item in the list, in which case the      */
  545. /*           item following the current item becomes the current     */
  546. /*           item in the list.  If there is no item following the    */
  547. /*           current item in the list, then the item preceeding the  */
  548. /*           current item will become the current item in the list.  */
  549. /*                                                                   */
  550. /*********************************************************************/
  551. void _System DeleteItem (DLIST        ListToDeleteFrom,
  552. BOOLEAN      FreeMemory,
  553. ADDRESS      Handle,
  554. CARDINAL32 * Error);
  555.  
  556. /*********************************************************************/
  557. /*                                                                   */
  558. /*   Function Name:  DeleteAllItems                                  */
  559. /*                                                                   */
  560. /*   Descriptive Name:  This function deletes all of the items in the*/
  561. /*                      specified list and optionally frees the      */
  562. /*                      memory associated with each item deleted.    */
  563. /*                                                                   */
  564. /*   Input:  DLIST       ListToDeleteFrom : The list whose items     */
  565. /*                                          are to be deleted.       */
  566. /*           BOOLEAN    FreeMemory : If TRUE, then the memory        */
  567. /*                                   associated with each item in the*/
  568. /*                                   list will be freed.  If FALSE   */
  569. /*                                   then the each item will be      */
  570. /*                                   removed from the list but its   */
  571. /*                                   memory will not be freed.       */
  572. /*           CARDINAL32 * Error : The address of a variable to hold  */
  573. /*                                 the error return code.            */
  574. /*                                                                   */
  575. /*   Output:  If the operation is successful, then *Error will be    */
  576. /*            set to 0.  If the operation fails, then *Error will    */
  577. /*            contain an error code.                                 */
  578. /*                                                                   */
  579. /*   Error Handling: This function will fail if ListToDeleteFrom is  */
  580. /*                   not a valid list, or if ListToDeleteFrom is     */
  581. /*                   empty.                                          */
  582. /*                   If this routine fails, an error code is returned*/
  583. /*                   in *Error.                                      */
  584. /*                                                                   */
  585. /*   Side Effects:  None.                                            */
  586. /*                                                                   */
  587. /*   Notes:  Items in a list can be accessed in two ways:  A copy of */
  588. /*           the item can be obtained using GetItem and its related  */
  589. /*           calls, or a pointer to the item can be obtained using   */
  590. /*           GetObject and its related calls.  If you have a copy of */
  591. /*           the data and wish to remove the item from the list, set */
  592. /*           FreeMemory to TRUE.  This will remove the item from the */
  593. /*           list and deallocate the memory used to hold it.  If you */
  594. /*           have a pointer to the item in the list (from one of the */
  595. /*           GetObject style functions) and wish to remove the item  */
  596. /*           from the list, set FreeMemory to FALSE.  This removes   */
  597. /*           the item from the list without freeing its memory, so   */
  598. /*           that the pointer obtained with the GetObject style      */
  599. /*           functions is still useable.                             */
  600. /*                                                                   */
  601. /*           It is assumed that Error contains a valid address. If   */
  602. /*           this assumption is violated, an exception or trap       */
  603. /*           may occur.                                              */
  604. /*                                                                   */
  605. /*********************************************************************/
  606. void _System DeleteAllItems (DLIST        ListToDeleteFrom,
  607. BOOLEAN      FreeMemory,
  608. CARDINAL32 * Error);
  609.  
  610. /*********************************************************************/
  611. /*                                                                   */
  612. /*   Function Name:  GetItem                                         */
  613. /*                                                                   */
  614. /*   Descriptive Name:  This function copies the specified item in   */
  615. /*                      the list to a buffer provided by the caller. */
  616. /*                                                                   */
  617. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  618. /*                                      is to be copied and returned */
  619. /*                                      to the caller.               */
  620. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  621. /*                               the current item is.                */
  622. /*           ADDRESS     ItemLocation : This is the location of the  */
  623. /*                                      buffer into which the current*/
  624. /*                                      item is to be copied.        */
  625. /*           TAG     ItemTag : What the caller thinks the item tag   */
  626. /*                             of the current item is.               */
  627. /*           ADDRESS Handle : The handle of the item to get.  This   */
  628. /*                            handle must be of an item which resides*/
  629. /*                            in ListToGetItemFrom, or NULL.  If     */
  630. /*                            NULL, then the current item in the list*/
  631. /*                            will be used.                          */
  632. /*           BOOLEAN MakeCurrent : If TRUE, the item to get will     */
  633. /*                                 become the current item in the    */
  634. /*                                 list.                             */
  635. /*           CARDINAL32 * Error : The address of a variable to hold  */
  636. /*                              the error return code.               */
  637. /*                                                                   */
  638. /*   Output:  If Successful :                                        */
  639. /*                 *Error will be set to 0.                          */
  640. /*                 The buffer at ItemLocation will contain a copy of */
  641. /*                    the current item from ListToGetItemFrom.       */
  642. /*            If Failure :                                           */
  643. /*                 *Error will contain an error code.                */
  644. /*                                                                   */
  645. /*                                                                   */
  646. /*   Error Handling: This function will fail under any of the        */
  647. /*                   following conditions:                           */
  648. /*                         ListToGetItemFrom is not a valid list     */
  649. /*                         ItemSize does not match the size of the   */
  650. /*                             current item in the list              */
  651. /*                         ItemLocation is NULL                      */
  652. /*                         ItemTag does not match the item tag       */
  653. /*                             of the current item in the list       */
  654. /*                         Handle is invalid, or is for an item      */
  655. /*                             which is not in ListToGetItemFrom     */
  656. /*                   If any of these conditions occur, *Error will   */
  657. /*                   contain a non-zero error code.                  */
  658. /*                                                                   */
  659. /*   Side Effects:  None.                                            */
  660. /*                                                                   */
  661. /*   Notes:  It is assumed that Error contains a valid address. It   */
  662. /*           is also assumed that if ItemLocation is not NULL, then  */
  663. /*           it is a valid address that can be dereferenced.  If     */
  664. /*           these assumptions are violated, an exception or trap    */
  665. /*           may occur.                                              */
  666. /*                                                                   */
  667. /*           It is assumed that Handle is valid, or is at least the  */
  668. /*           address of an accessible block of storage.  If Handle   */
  669. /*           is invalid, or is not the address of an accessible block*/
  670. /*           of storage, then a trap or exception may occur.         */
  671. /*           NOTE: For this function, NULL is considered a valid     */
  672. /*                 handle corresponding to the current item in the   */
  673. /*                 list.                                             */
  674. /*                                                                   */
  675. /*           This function does not alter which item is the current  */
  676. /*           item in the list.                                       */
  677. /*                                                                   */
  678. /*********************************************************************/
  679. void _System GetItem( DLIST          ListToGetItemFrom,
  680. CARDINAL32     ItemSize,
  681. ADDRESS        ItemLocation,
  682. TAG            ItemTag,
  683. ADDRESS        Handle,
  684. BOOLEAN        MakeCurrent,
  685. CARDINAL32 *   Error);
  686.  
  687. /*********************************************************************/
  688. /*                                                                   */
  689. /*   Function Name:  GetNextItem                                     */
  690. /*                                                                   */
  691. /*   Descriptive Name:  This function advances the current item      */
  692. /*                      pointer and then copies the current item in  */
  693. /*                      the list to a buffer provided by the caller. */
  694. /*                                                                   */
  695. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  696. /*                                      is to be copied and returned */
  697. /*                                      to the caller.               */
  698. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  699. /*                                 the current item is.              */
  700. /*           ADDRESS     ItemLocation : This is the location of the  */
  701. /*                                      buffer into which the current*/
  702. /*                                      item is to be copied.        */
  703. /*           TAG     ItemTag : What the caller thinks the item tag   */
  704. /*                             of the current item is.               */
  705. /*           CARDINAL32 * Error : The address of a variable to hold  */
  706. /*                                the error return code.             */
  707. /*                                                                   */
  708. /*   Output:  If Successful :                                        */
  709. /*                 *Error will be set to 0.                          */
  710. /*                 The buffer at ItemLocation will contain a copy of */
  711. /*                    the current item from ListToGetItemFrom.       */
  712. /*            If Failure :                                           */
  713. /*                 *Error will contain an error code.                */
  714. /*                 The current item pointer will NOT be advanced.    */
  715. /*                     The current item in the list will be the same */
  716. /*                     as before the call to this function.          */
  717. /*                                                                   */
  718. /*   Error Handling: This function will fail under any of the        */
  719. /*                   following conditions:                           */
  720. /*                         ListToGetItemFrom is not a valid list     */
  721. /*                         ItemSize does not match the size of the   */
  722. /*                             current item in the list              */
  723. /*                         ItemLocation is NULL                      */
  724. /*                         ItemTag does not match the item tag       */
  725. /*                             of the current item in the list       */
  726. /*                         The current item in the list before this  */
  727. /*                             function is called is the last item   */
  728. /*                             item in the list.                     */
  729. /*                   If any of these conditions occur, *Error will   */
  730. /*                   contain a non-zero error code.                  */
  731. /*                                                                   */
  732. /*   Side Effects:  None.                                            */
  733. /*                                                                   */
  734. /*   Notes:  It is assumed that Error contains a valid address. It   */
  735. /*           is also assumed that if ItemLocation is not NULL, then  */
  736. /*           it is a valid address that can be dereferenced.  If     */
  737. /*           these assumptions are violated, an exception or trap    */
  738. /*           may occur.                                              */
  739. /*                                                                   */
  740. /*********************************************************************/
  741. void _System GetNextItem( DLIST          ListToGetItemFrom,
  742. CARDINAL32     ItemSize,
  743. ADDRESS        ItemLocation,
  744. TAG            ItemTag,
  745. CARDINAL32 *   Error);
  746.  
  747. /*********************************************************************/
  748. /*                                                                   */
  749. /*   Function Name:  GetPreviousItem                                 */
  750. /*                                                                   */
  751. /*   Descriptive Name:  This function makes the previous item in the */
  752. /*                      list the current item in the list and then   */
  753. /*                      copies that item to a buffer provided by the */
  754. /*                      user.                                        */
  755. /*                                                                   */
  756. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  757. /*                                      is to be copied and returned */
  758. /*                                      to the caller.               */
  759. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  760. /*                                 the current item is.              */
  761. /*           ADDRESS    ItemLocation : This is the location of the   */
  762. /*                                      buffer into which the current*/
  763. /*                                      item is to be copied.        */
  764. /*           TAG     ItemTag : What the caller thinks the item tag   */
  765. /*                             of the current item is.               */
  766. /*           CARDINAL32 * Error : The address of a variable to hold  */
  767. /*                                the error return code.             */
  768. /*                                                                   */
  769. /*   Output:  If Successful :                                        */
  770. /*                 *Error will be set to 0.                          */
  771. /*                 The buffer at ItemLocation will contain a copy of */
  772. /*                    the current item from ListToGetItemFrom.       */
  773. /*            If Failure :                                           */
  774. /*                 *Error will contain an error code.                */
  775. /*                 The current item pointer will NOT be advanced.    */
  776. /*                     The current item in the list will be the same */
  777. /*                     as before the call to this function.          */
  778. /*                                                                   */
  779. /*   Error Handling: This function will fail under any of the        */
  780. /*                   following conditions:                           */
  781. /*                         ListToGetItemFrom is not a valid list     */
  782. /*                         ItemSize does not match the size of the   */
  783. /*                             current item in the list              */
  784. /*                         ItemLocation is NULL                      */
  785. /*                         ItemTag does not match the item tag       */
  786. /*                             of the current item in the list       */
  787. /*                         The current item in the list before this  */
  788. /*                             function is called is the last item   */
  789. /*                             item in the list.                     */
  790. /*                   If any of these conditions occur, *Error will   */
  791. /*                   contain a non-zero error code.                  */
  792. /*                                                                   */
  793. /*   Side Effects:  None.                                            */
  794. /*                                                                   */
  795. /*   Notes:  It is assumed that Error contains a valid address. It   */
  796. /*           is also assumed that if ItemLocation is not NULL, then  */
  797. /*           it is a valid address that can be dereferenced.  If     */
  798. /*           these assumptions are violated, an exception or trap    */
  799. /*           may occur.                                              */
  800. /*                                                                   */
  801. /*********************************************************************/
  802. void _System GetPreviousItem( DLIST          ListToGetItemFrom,
  803. CARDINAL32     ItemSize,
  804. ADDRESS        ItemLocation,
  805. TAG            ItemTag,
  806. CARDINAL32 *   Error);
  807.  
  808. /*********************************************************************/
  809. /*                                                                   */
  810. /*   Function Name:  GetObject                                       */
  811. /*                                                                   */
  812. /*   Descriptive Name:  This function returns the address of the data*/
  813. /*                      associated with the specified item in the    */
  814. /*                      list.                                        */
  815. /*                                                                   */
  816. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  817. /*                                      is to have its address       */
  818. /*                                      returned to the caller.      */
  819. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  820. /*                               the current item is.                */
  821. /*           TAG     ItemTag : What the caller thinks the item tag   */
  822. /*                             of the current item is.               */
  823. /*           ADDRESS Handle : The handle of the item to get.  This   */
  824. /*                            handle must be of an item which resides*/
  825. /*                            in ListToGetItemFrom, or NULL.  If     */
  826. /*                            NULL, then the current item in the list*/
  827. /*           BOOLEAN MakeCurrent : If TRUE, the item to get will     */
  828. /*                                 become the current item in the    */
  829. /*                                 list.                             */
  830. /*           CARDINAL32 * Error : The address of a variable to hold  */
  831. /*                                the error return code.             */
  832. /*                                                                   */
  833. /*   Output:  If Successful :                                        */
  834. /*                 *Error will be set to 0.                          */
  835. /*                 The function return value will be the address of  */
  836. /*                 the data associated with the current item in the  */
  837. /*                 list.                                             */
  838. /*            If Failure :                                           */
  839. /*                 *Error will contain an error code.                */
  840. /*                 The function return value will be NULL.           */
  841. /*                                                                   */
  842. /*   Error Handling: This function will fail under any of the        */
  843. /*                   following conditions:                           */
  844. /*                         ListToGetItemFrom is not a valid list     */
  845. /*                         ItemSize does not match the size of the   */
  846. /*                             current item in the list              */
  847. /*                         ItemTag does not match the item tag       */
  848. /*                             of the current item in the list       */
  849. /*                         Handle is invalid, or is for an item      */
  850. /*                             which is not in ListToGetItemFrom     */
  851. /*                   If any of these conditions occur, *Error will   */
  852. /*                   contain a non-zero error code.                  */
  853. /*                                                                   */
  854. /*   Side Effects:  None.                                            */
  855. /*                                                                   */
  856. /*   Notes:  The user should not free the memory associated with     */
  857. /*           the address returned by this function as the object is  */
  858. /*           still in the list.                                      */
  859. /*                                                                   */
  860. /*           It is assumed that Error contains a valid address. If   */
  861. /*           this assumption is violated, an exception or trap may   */
  862. /*           occur.                                                  */
  863. /*                                                                   */
  864. /*           It is assumed that Handle is valid, or is at least the  */
  865. /*           address of an accessible block of storage.  If Handle   */
  866. /*           is invalid, or is not the address of an accessible block*/
  867. /*           of storage, then a trap or exception may occur.         */
  868. /*           NOTE: For this function, NULL is considered a valid     */
  869. /*                 handle designating the current item in the list.  */
  870. /*                                                                   */
  871. /*           This function does not alter which item is the current  */
  872. /*           item in the list.                                       */
  873. /*                                                                   */
  874. /*********************************************************************/
  875. ADDRESS _System GetObject( DLIST          ListToGetItemFrom,
  876. CARDINAL32     ItemSize,
  877. TAG            ItemTag,
  878. ADDRESS        Handle,
  879. BOOLEAN        MakeCurrent,
  880. CARDINAL32 *   Error);
  881.  
  882. /*********************************************************************/
  883. /*                                                                   */
  884. /*   Function Name:  GetNextObject                                   */
  885. /*                                                                   */
  886. /*   Descriptive Name:  This function advances the current item      */
  887. /*                      pointer and then returns the address of the  */
  888. /*                      data associated with the current item in the */
  889. /*                      list.                                        */
  890. /*                                                                   */
  891. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  892. /*                                      is to be copied and returned */
  893. /*                                      to the caller.               */
  894. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  895. /*                                 the current item is.              */
  896. /*           TAG     ItemTag : What the caller thinks the item tag   */
  897. /*                             of the current item is.               */
  898. /*           CARDINAL32 * Error : The address of a variable to hold  */
  899. /*                                the error return code.             */
  900. /*                                                                   */
  901. /*   Output:  If Successful :                                        */
  902. /*                 *Error will be set to 0.                          */
  903. /*                 The function return value will be the address of  */
  904. /*                 the data associated with the current item in the  */
  905. /*                 list.                                             */
  906. /*            If Failure :                                           */
  907. /*                 *Error will contain an error code.                */
  908. /*                 The function return value will be NULL.           */
  909. /*                 The current item pointer will NOT be advanced.    */
  910. /*                     The current item in the list will be the same */
  911. /*                     as before the call to this function.          */
  912. /*                                                                   */
  913. /*   Error Handling: This function will fail under any of the        */
  914. /*                   following conditions:                           */
  915. /*                         ListToGetItemFrom is not a valid list     */
  916. /*                         ItemSize does not match the size of the   */
  917. /*                             current item in the list              */
  918. /*                         ItemTag does not match the item tag       */
  919. /*                             of the current item in the list       */
  920. /*                         The current item in the list before this  */
  921. /*                             function is called is the last item   */
  922. /*                             item in the list.                     */
  923. /*                   If any of these conditions occur, *Error will   */
  924. /*                   contain a non-zero error code.                  */
  925. /*                                                                   */
  926. /*   Side Effects:  None.                                            */
  927. /*                                                                   */
  928. /*   Notes:  The user should not free the memory associated with     */
  929. /*           the address returned by this function as the object is  */
  930. /*           still in the list.                                      */
  931. /*                                                                   */
  932. /*           It is assumed that Error contains a valid address. If   */
  933. /*           this assumption are violated, an exception or trap may  */
  934. /*           occur.                                                  */
  935. /*                                                                   */
  936. /*********************************************************************/
  937. ADDRESS _System GetNextObject( DLIST          ListToGetItemFrom,
  938. CARDINAL32     ItemSize,
  939. TAG            ItemTag,
  940. CARDINAL32 *   Error);
  941.  
  942. /*********************************************************************/
  943. /*                                                                   */
  944. /*   Function Name:  GetPreviousObject                               */
  945. /*                                                                   */
  946. /*   Descriptive Name:  This function makes the previous item in the */
  947. /*                      list the current item and then returns the   */
  948. /*                      address of the data associated with the      */
  949. /*                      current item in the list.                    */
  950. /*                                                                   */
  951. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  952. /*                                      is to be copied and returned */
  953. /*                                      to the caller.               */
  954. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  955. /*                                 the current item is.              */
  956. /*           TAG     ItemTag : What the caller thinks the item tag   */
  957. /*                             of the current item is.               */
  958. /*           CARDINAL32 * Error : The address of a variable to hold  */
  959. /*                                the error return code.             */
  960. /*                                                                   */
  961. /*   Output:  If Successful :                                        */
  962. /*                 *Error will be set to 0.                          */
  963. /*                 The function return value will be the address of  */
  964. /*                 the data associated with the current item in the  */
  965. /*                 list.                                             */
  966. /*            If Failure :                                           */
  967. /*                 *Error will contain an error code.                */
  968. /*                 The function return value will be NULL.           */
  969. /*                 The current item pointer will NOT be advanced.    */
  970. /*                     The current item in the list will be the same */
  971. /*                     as before the call to this function.          */
  972. /*                                                                   */
  973. /*   Error Handling: This function will fail under any of the        */
  974. /*                   following conditions:                           */
  975. /*                         ListToGetItemFrom is not a valid list     */
  976. /*                         ItemSize does not match the size of the   */
  977. /*                             current item in the list              */
  978. /*                         ItemTag does not match the item tag       */
  979. /*                             of the current item in the list       */
  980. /*                         The current item in the list before this  */
  981. /*                             function is called is the last item   */
  982. /*                             item in the list.                     */
  983. /*                   If any of these conditions occur, *Error will   */
  984. /*                   contain a non-zero error code.                  */
  985. /*                                                                   */
  986. /*   Side Effects:  None.                                            */
  987. /*                                                                   */
  988. /*   Notes:  The user should not free the memory associated with     */
  989. /*           the address returned by this function as the object is  */
  990. /*           still in the list.                                      */
  991. /*                                                                   */
  992. /*           It is assumed that Error contains a valid address. If   */
  993. /*           this assumption are violated, an exception or trap may  */
  994. /*           occur.                                                  */
  995. /*                                                                   */
  996. /*********************************************************************/
  997. ADDRESS _System GetPreviousObject( DLIST          ListToGetItemFrom,
  998. CARDINAL32     ItemSize,
  999. TAG            ItemTag,
  1000. CARDINAL32 *   Error);
  1001.  
  1002. /*********************************************************************/
  1003. /*                                                                   */
  1004. /*   Function Name:  ExtractItem                                     */
  1005. /*                                                                   */
  1006. /*   Descriptive Name:  This function copies the specified item in   */
  1007. /*                      the list to a buffer provided by the caller  */
  1008. /*                      and removes the item from the list.          */
  1009. /*                                                                   */
  1010. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  1011. /*                                      is to be copied and returned */
  1012. /*                                      to the caller.               */
  1013. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  1014. /*                                 the current item is.              */
  1015. /*           ADDRESS     ItemLocation : This is the location of the  */
  1016. /*                                      buffer into which the current*/
  1017. /*                                      item is to be copied.        */
  1018. /*           TAG     ItemTag : What the caller thinks the item tag   */
  1019. /*                             of the current item is.               */
  1020. /*           ADDRESS Handle : The handle of the item to get.  This   */
  1021. /*                            handle must be of an item which resides*/
  1022. /*                            in ListToGetItemFrom, or NULL.  If     */
  1023. /*                            NULL, then the current item in the list*/
  1024. /*                            will be used.                          */
  1025. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1026. /*                                the error return code.             */
  1027. /*                                                                   */
  1028. /*   Output:  If Successful :                                        */
  1029. /*                 *Error will be set to 0.                          */
  1030. /*                 The buffer at ItemLocation will contain a copy of */
  1031. /*                    the current item from ListToGetItemFrom.       */
  1032. /*                 The item will have been removed from the list and */
  1033. /*                    its memory deallocated.                        */
  1034. /*            If Failure :                                           */
  1035. /*                 *Error will contain an error code.                */
  1036. /*                                                                   */
  1037. /*   Error Handling: This function will fail under any of the        */
  1038. /*                   following conditions:                           */
  1039. /*                         ListToGetItemFrom is not a valid list     */
  1040. /*                         ItemSize does not match the size of the   */
  1041. /*                             current item in the list              */
  1042. /*                         ItemLocation is NULL                      */
  1043. /*                         ItemTag does not match the item tag       */
  1044. /*                             of the current item in the list       */
  1045. /*                         Handle is invalid, or is for an item      */
  1046. /*                             which is not in ListToGetItemFrom     */
  1047. /*                   If any of these conditions occur, *Error will   */
  1048. /*                   contain a non-zero error code.                  */
  1049. /*                                                                   */
  1050. /*   Side Effects:  None.                                            */
  1051. /*                                                                   */
  1052. /*   Notes:  It is assumed that Error contains a valid address. It   */
  1053. /*           is also assumed that if ItemLocation is not NULL, then  */
  1054. /*           it is a valid address that can be dereferenced.  If     */
  1055. /*           these assumptions are violated, an exception or trap    */
  1056. /*           may occur.                                              */
  1057. /*                                                                   */
  1058. /*           It is assumed that Handle is valid, or is at least the  */
  1059. /*           address of an accessible block of storage.  If Handle   */
  1060. /*           is invalid, or is not the address of an accessible block*/
  1061. /*           of storage, then a trap or exception may occur.         */
  1062. /*           NOTE: For this function, NULL is considered a valid     */
  1063. /*                 handle which refers to the current item in the    */
  1064. /*                 list.                                             */
  1065. /*                                                                   */
  1066. /*           This function does not alter which item is the current  */
  1067. /*           item in the list, unless the handle specified belongs   */
  1068. /*           to the current item in the list, in which case the      */
  1069. /*           item following the current item becomes the current     */
  1070. /*           item in the list.  If there is no item following the    */
  1071. /*           current item in the list, then the item preceeding the  */
  1072. /*           current item will become the current item in the list.  */
  1073. /*                                                                   */
  1074. /*********************************************************************/
  1075. void _System ExtractItem( DLIST          ListToGetItemFrom,
  1076. CARDINAL32     ItemSize,
  1077. ADDRESS        ItemLocation,
  1078. TAG            ItemTag,
  1079. ADDRESS        Handle,
  1080. CARDINAL32 *   Error);
  1081.  
  1082. /*********************************************************************/
  1083. /*                                                                   */
  1084. /*   Function Name:  ExtractObject                                   */
  1085. /*                                                                   */
  1086. /*   Descriptive Name:  This function returns the address of the data*/
  1087. /*                      associated with the specified item in the    */
  1088. /*                      list and then removes that item from the list*/
  1089. /*                                                                   */
  1090. /*   Input:  DLIST   ListToGetItemFrom : The list whose current item */
  1091. /*                                      is to be copied and returned */
  1092. /*                                      to the caller.               */
  1093. /*           CARDINAL32 ItemSize : What the caller thinks the size of*/
  1094. /*                                 the current item is.              */
  1095. /*           TAG     ItemTag : What the caller thinks the item tag   */
  1096. /*                             of the current item is.               */
  1097. /*           ADDRESS Handle : The handle of the item to get.  This   */
  1098. /*                            handle must be of an item which resides*/
  1099. /*                            in ListToGetItemFrom, or NULL.  If     */
  1100. /*                            NULL, then the current item in the     */
  1101. /*                            list will be used.                     */
  1102. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1103. /*                                the error return code.             */
  1104. /*                                                                   */
  1105. /*   Output:  If Successful :                                        */
  1106. /*                 *Error will be set to 0.                          */
  1107. /*                 The function return value will be the address of  */
  1108. /*                 the data associated with the current item in the  */
  1109. /*                 list.                                             */
  1110. /*                 The current item is removed from the list.        */
  1111. /*            If Failure :                                           */
  1112. /*                 *Error will contain an error code.                */
  1113. /*                 The function return value will be NULL.           */
  1114. /*                                                                   */
  1115. /*   Error Handling: This function will fail under any of the        */
  1116. /*                   following conditions:                           */
  1117. /*                         ListToGetItemFrom is not a valid list     */
  1118. /*                         ItemSize does not match the size of the   */
  1119. /*                             current item in the list              */
  1120. /*                         ItemTag does not match the item tag       */
  1121. /*                             of the current item in the list       */
  1122. /*                         Handle is invalid, or is for an item      */
  1123. /*                             which is not in ListToGetItemFrom     */
  1124. /*                   If any of these conditions occur, *Error will   */
  1125. /*                   contain a non-zero error code.                  */
  1126. /*                                                                   */
  1127. /*   Side Effects:  None.                                            */
  1128. /*                                                                   */
  1129. /*   Notes:  The user is responsible for the memory associated with  */
  1130. /*           the address returned by this function since this        */
  1131. /*           function removes that object from the list.  This means */
  1132. /*           that, when the user is through with the object, they    */
  1133. /*           should free it.                                         */
  1134. /*                                                                   */
  1135. /*           It is assumed that Error contains a valid address. If   */
  1136. /*           this assumption is violated, an exception or trap may   */
  1137. /*           occur.                                                  */
  1138. /*                                                                   */
  1139. /*           It is assumed that Handle is valid, or is at least the  */
  1140. /*           address of an accessible block of storage.  If Handle   */
  1141. /*           is invalid, or is not the address of an accessible block*/
  1142. /*           of storage, then a trap or exception may occur.         */
  1143. /*           NOTE: For this function, NULL is considered a valid     */
  1144. /*                 handle which refers to the current item in the    */
  1145. /*                 list.                                             */
  1146. /*                                                                   */
  1147. /*           This function does not alter which item is the current  */
  1148. /*           item in the list, unless the handle specified belongs   */
  1149. /*           to the current item in the list, in which case the      */
  1150. /*           item following the current item becomes the current     */
  1151. /*           item in the list.  If there is no item following the    */
  1152. /*           current item in the list, then the item preceeding the  */
  1153. /*           current item will become the current item in the list.  */
  1154. /*                                                                   */
  1155. /*********************************************************************/
  1156. ADDRESS _System ExtractObject( DLIST          ListToGetItemFrom,
  1157. CARDINAL32     ItemSize,
  1158. TAG            ItemTag,
  1159. ADDRESS        Handle,
  1160. CARDINAL32 *   Error);
  1161.  
  1162. /*********************************************************************/
  1163. /*                                                                   */
  1164. /*   Function Name:  ReplaceItem                                     */
  1165. /*                                                                   */
  1166. /*   Descriptive Name:  This function replaces the specified item in */
  1167. /*                      the list with the one provided as its        */
  1168. /*                      argument.                                    */
  1169. /*                                                                   */
  1170. /*   Input: DLIST   ListToReplaceItemIn : The list whose current item*/
  1171. /*                                       is to be replaced           */
  1172. /*          CARDINAL32 ItemSize : The size, in bytes, of the         */
  1173. /*                              replacement item                     */
  1174. /*          ADDRESS     ItemLocation : The address of the replacement*/
  1175. /*                                     item                          */
  1176. /*          TAG     ItemTag : The item tag that the user wishes to   */
  1177. /*                            associate with the replacement item    */
  1178. /*          ADDRESS Handle : The handle of the item to get.  This    */
  1179. /*                           handle must be of an item which resides */
  1180. /*                           in ListToGetItemFrom, or NULL.  If NULL */
  1181. /*                           then the current item in the list will  */
  1182. /*                           used.                                   */
  1183. /*          BOOLEAN MakeCurrent : If TRUE, the item to get will      */
  1184. /*                                become the current item in the     */
  1185. /*                                list.                              */
  1186. /*          CARDINAL32 * Error : The address of a variable to hold   */
  1187. /*                               the error return code               */
  1188. /*                                                                   */
  1189. /*   Output:  If Successful then *Error will be set to 0.            */
  1190. /*            If Unsuccessful, then *Error will be set to a non-zero */
  1191. /*              error code.                                          */
  1192. /*                                                                   */
  1193. /*   Error Handling:  This function will fail under the following    */
  1194. /*                    conditions:                                    */
  1195. /*                         ListToReplaceItemIn is empty              */
  1196. /*                         ItemSize is 0                             */
  1197. /*                         ItemLocation is NULL                      */
  1198. /*                         The memory required can not be allocated. */
  1199. /*                         Handle is invalid, or is for an item      */
  1200. /*                             which is not in ListToGetItemFrom     */
  1201. /*                    If any of these conditions occurs, *Error      */
  1202. /*                    will contain a non-zero error code.            */
  1203. /*                                                                   */
  1204. /*   Side Effects:  None.                                            */
  1205. /*                                                                   */
  1206. /*   Notes:  It is assumed that Error contains a valid address. It   */
  1207. /*           is also assumed that if ItemLocation is not NULL, then  */
  1208. /*           it is a valid address that can be dereferenced.  If     */
  1209. /*           these assumptions are violated, an exception or trap    */
  1210. /*           may occur.                                              */
  1211. /*                                                                   */
  1212. /*           It is assumed that Handle is valid, or is at least the  */
  1213. /*           address of an accessible block of storage.  If Handle   */
  1214. /*           is invalid, or is not the address of an accessible block*/
  1215. /*           of storage, then a trap or exception may occur.         */
  1216. /*           NOTE: For this function, NULL is a valid handle which   */
  1217. /*                 refers to the current item in the list.           */
  1218. /*                                                                   */
  1219. /*           This function does not alter which item is the current  */
  1220. /*           item in the list.                                       */
  1221. /*                                                                   */
  1222. /*********************************************************************/
  1223. void _System ReplaceItem( DLIST         ListToReplaceItemIn,
  1224. CARDINAL32    ItemSize,
  1225. ADDRESS       ItemLocation,
  1226. TAG           ItemTag,
  1227. ADDRESS       Handle,
  1228. BOOLEAN       MakeCurrent,
  1229. CARDINAL32 *  Error);
  1230.  
  1231. /*********************************************************************/
  1232. /*                                                                   */
  1233. /*   Function Name: ReplaceObject                                    */
  1234. /*                                                                   */
  1235. /*   Descriptive Name:  This function replaces the specified object  */
  1236. /*                      in the list with the one provided as its     */
  1237. /*                      argument.                                    */
  1238. /*                                                                   */
  1239. /*   Input: DLIST   ListToReplaceItemIn : The list whose current     */
  1240. /*                                       object is to be replaced    */
  1241. /*          CARDINAL32 ItemSize : The size, in bytes, of the         */
  1242. /*                              replacement object                   */
  1243. /*          ADDRESS     ItemLocation : The address of the replacement*/
  1244. /*                                     item                          */
  1245. /*          TAG     ItemTag : The item tag that the user wishes to   */
  1246. /*                            associate with the replacement item    */
  1247. /*          ADDRESS Handle : The handle of the item to get.  This    */
  1248. /*                           handle must be of an item which resides */
  1249. /*                           in ListToGetItemFrom, or NULL.  If NULL */
  1250. /*                           then the current item in the list will  */
  1251. /*                           be used.                                */
  1252. /*          BOOLEAN MakeCurrent : If TRUE, the item to get will      */
  1253. /*                                become the current item in the     */
  1254. /*                                list.                              */
  1255. /*          CARDINAL32 * Error : The address of a variable to hold   */
  1256. /*                               the error return code               */
  1257. /*                                                                   */
  1258. /*   Output:  If Successful then *Error will be set to 0 and the     */
  1259. /*              return value of the function will be the address     */
  1260. /*              of the object that was replaced.                     */
  1261. /*            If Unsuccessful, then *Error will be set to a non-zero */
  1262. /*              error code and the function return value will be     */
  1263. /*              NULL.                                                */
  1264. /*                                                                   */
  1265. /*   Error Handling:  This function will fail under the following    */
  1266. /*                    conditions:                                    */
  1267. /*                         ListToReplaceItemIn is empty              */
  1268. /*                         ItemSize is 0                             */
  1269. /*                         ItemLocation is NULL                      */
  1270. /*                         The memory required can not be allocated. */
  1271. /*                         Handle is invalid, or is for an item      */
  1272. /*                             which is not in ListToGetItemFrom     */
  1273. /*                    If any of these conditions occurs, *Error      */
  1274. /*                    will contain a non-zero error code.            */
  1275. /*                                                                   */
  1276. /*   Side Effects:  None.                                            */
  1277. /*                                                                   */
  1278. /*   Notes:  The user is responsible for the memory associated with  */
  1279. /*           the object returned by this function as that object is  */
  1280. /*           removed from the list.  This means that, when the user  */
  1281. /*           is through with the object returned by this function,   */
  1282. /*           they should free it.                                    */
  1283. /*                                                                   */
  1284. /*           It is assumed that Error contains a valid address. It   */
  1285. /*           is also assumed that if ItemLocation is not NULL, then  */
  1286. /*           it is a valid address that can be dereferenced.  If     */
  1287. /*           these assumptions are violated, an exception or trap    */
  1288. /*           may occur.                                              */
  1289. /*                                                                   */
  1290. /*           It is assumed that Handle is valid, or is at least the  */
  1291. /*           address of an accessible block of storage.  If Handle   */
  1292. /*           is invalid, or is not the address of an accessible block*/
  1293. /*           of storage, then a trap or exception may occur.         */
  1294. /*           NOTE: For this function, NULL is a valid handle for the */
  1295. /*                 current item in the list.                         */
  1296. /*                                                                   */
  1297. /*           This function does not alter which item is the current  */
  1298. /*           item in the list.                                       */
  1299. /*                                                                   */
  1300. /*********************************************************************/
  1301. ADDRESS _System ReplaceObject( DLIST         ListToReplaceItemIn,
  1302. CARDINAL32 *  ItemSize,             /* On input - size of new object.  On return = size of old object. */
  1303. ADDRESS       ItemLocation,
  1304. TAG        *  ItemTag,              /* On input - TAG of new object.  On return = TAG of old object. */
  1305. ADDRESS       Handle,
  1306. BOOLEAN       MakeCurrent,
  1307. CARDINAL32 *  Error);
  1308.  
  1309. /*********************************************************************/
  1310. /*                                                                   */
  1311. /*   Function Name:  GetTag                                          */
  1312. /*                                                                   */
  1313. /*   Descriptive Name:  This function returns the item tag associated*/
  1314. /*                      with the current item in the list.           */
  1315. /*                                                                   */
  1316. /*   Input:  DLIST   ListToGetTagFrom : The list from which the item */
  1317. /*                                     tag of the current item is to */
  1318. /*                                     be returned                   */
  1319. /*           ADDRESS Handle : The handle of the item whose TAG and   */
  1320. /*                            size we are to get.  This handle must  */
  1321. /*                            be of an item which resides in         */
  1322. /*                            in ListToGetTagFrom, or NULL.  If NULL */
  1323. /*                            then the current item in the list will */
  1324. /*                            be used.                               */
  1325. /*           CARDINAL32 * ItemSize : The size, in bytes, of the      */
  1326. /*                                   current item in the list.       */
  1327. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1328. /*                                the error return code              */
  1329. /*                                                                   */
  1330. /*   Output:  If successful, the function returns the item tag & size*/
  1331. /*               associated with the current item in ListToGetTagFrom*/
  1332. /*               and *Error is set to 0.                             */
  1333. /*            If unsuccessful, the function returns 0 and *Error is  */
  1334. /*               set to a non-zero error code.                       */
  1335. /*                                                                   */
  1336. /*   Error Handling: This function will fail if ListToGetTagFrom is  */
  1337. /*                   not a valid list or is an empty list.  In either*/
  1338. /*                   of these cases, *Error is set to a non-zero     */
  1339. /*                   error code.                                     */
  1340. /*                                                                   */
  1341. /*   Side Effects:  None.                                            */
  1342. /*                                                                   */
  1343. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1344. /*           this assumption is violated, an exception or trap       */
  1345. /*           may occur.                                              */
  1346. /*                                                                   */
  1347. /*                                                                   */
  1348. /*********************************************************************/
  1349. TAG _System GetTag( DLIST  ListToGetTagFrom,
  1350. ADDRESS Handle,
  1351. CARDINAL32 * ItemSize,
  1352. CARDINAL32 * Error);
  1353.  
  1354. /*********************************************************************/
  1355. /*                                                                   */
  1356. /*   Function Name:  GetHandle                                       */
  1357. /*                                                                   */
  1358. /*   Descriptive Name:  This function returns a handle for the       */
  1359. /*                      current item in the list.  This handle is    */
  1360. /*                      then associated with that item regardless of */
  1361. /*                      its position in the list.  This handle can be*/
  1362. /*                      used to make its associated item the current */
  1363. /*                      item in the list.                            */
  1364. /*                                                                   */
  1365. /*   Input:  DLIST   ListToGetHandleFrom : The list from which a     */
  1366. /*                                        handle is needed.          */
  1367. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1368. /*                                the error return code              */
  1369. /*                                                                   */
  1370. /*   Output:  If successful, the function returns a handle for the   */
  1371. /*               the current item in ListToGetHandleFrom, and *Error */
  1372. /*               is set to 0.                                        */
  1373. /*            If unsuccessful, the function returns 0 and *Error is  */
  1374. /*               set to a non-zero error code.                       */
  1375. /*                                                                   */
  1376. /*   Error Handling: This function will fail if ListToGetHandleFrom  */
  1377. /*                   is not a valid list or is an empty list.  In    */
  1378. /*                   either of these cases, *Error is set to a       */
  1379. /*                   non-zero error code.                            */
  1380. /*                                                                   */
  1381. /*   Side Effects:  None.                                            */
  1382. /*                                                                   */
  1383. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1384. /*           this assumption is violated, an exception or trap       */
  1385. /*           may occur.                                              */
  1386. /*                                                                   */
  1387. /*           The handle returned is a pointer to an internal         */
  1388. /*           structure within the list.  If the item associated      */
  1389. /*           with this handle is removed from the list, the handle   */
  1390. /*           will be invalid and should not be used as the internal  */
  1391. /*           structure it points to will nolonger exist!             */
  1392. /*                                                                   */
  1393. /*********************************************************************/
  1394. ADDRESS _System GetHandle ( DLIST ListToGetHandleFrom, CARDINAL32 * Error);
  1395.  
  1396. /*********************************************************************/
  1397. /*                                                                   */
  1398. /*   Function Name:  GetListSize                                     */
  1399. /*                                                                   */
  1400. /*   Descriptive Name:  This function returns the number of items in */
  1401. /*                      a list.                                      */
  1402. /*                                                                   */
  1403. /*   Input:  DLIST   ListToGetSizeOf : The list whose size we wish to*/
  1404. /*                                    know                           */
  1405. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1406. /*                                the error return code              */
  1407. /*                                                                   */
  1408. /*   Output:  If successful, the function returns the a count of the */
  1409. /*               number of items in the list, and *Error is set to 0.*/
  1410. /*            If unsuccessful, the function returns 0 and *Error is  */
  1411. /*               set to a non-zero error code.                       */
  1412. /*                                                                   */
  1413. /*   Error Handling: This function will fail if ListToGetSizeOf is   */
  1414. /*                   not a valid list.  If this happens, then *Error */
  1415. /*                   is set to a non-zero error code.                */
  1416. /*                                                                   */
  1417. /*   Side Effects:  None.                                            */
  1418. /*                                                                   */
  1419. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1420. /*           this assumption is violated, an exception or trap       */
  1421. /*           may occur.                                              */
  1422. /*                                                                   */
  1423. /*********************************************************************/
  1424. CARDINAL32 _System GetListSize( DLIST ListToGetSizeOf, CARDINAL32 * Error);
  1425.  
  1426. /*********************************************************************/
  1427. /*                                                                   */
  1428. /*   Function Name:  ListEmpty                                       */
  1429. /*                                                                   */
  1430. /*   Descriptive Name:  This function returns TRUE if the            */
  1431. /*                      specified list is empty, otherwise it returns*/
  1432. /*                      FALSE.                                       */
  1433. /*                                                                   */
  1434. /*   Input:  DLIST       ListToCheck : The list to check to see if it*/
  1435. /*                                    is empty                       */
  1436. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1437. /*                                the error return code              */
  1438. /*                                                                   */
  1439. /*   Output:  If successful, the function returns TRUE if the        */
  1440. /*               number of items in the list is 0, otherwise it      */
  1441. /*               returns FALSE.  Also, *Error is set to 0.           */
  1442. /*            If unsuccessful, the function returns TRUE and         */
  1443. /*               *Error is set to a non-zero error code.             */
  1444. /*                                                                   */
  1445. /*   Error Handling: This function will fail if ListToCheck is not   */
  1446. /*                   a valid list.  If this happens, then *Error     */
  1447. /*                   is set to a non-zero error code.                */
  1448. /*                                                                   */
  1449. /*   Side Effects:  None.                                            */
  1450. /*                                                                   */
  1451. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1452. /*           this assumption is violated, an exception or trap       */
  1453. /*           may occur.                                              */
  1454. /*                                                                   */
  1455. /*********************************************************************/
  1456. BOOLEAN _System ListEmpty( DLIST ListToCheck, CARDINAL32 * Error);
  1457.  
  1458. /*********************************************************************/
  1459. /*                                                                   */
  1460. /*   Function Name:  AtEndOfList                                     */
  1461. /*                                                                   */
  1462. /*   Descriptive Name:  This function returns TRUE if the            */
  1463. /*                      current item in the list is the last item    */
  1464. /*                      in the list.  Returns FALSE otherwise.       */
  1465. /*                                                                   */
  1466. /*   Input:  DLIST       ListToCheck : The list to check.            */
  1467. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1468. /*                                the error return code              */
  1469. /*                                                                   */
  1470. /*   Output:  If successful, the function returns TRUE if the        */
  1471. /*               current item in the list is the last item in the    */
  1472. /*               list.  If it is not the last item in the list,      */
  1473. /*               FALSE is returned.  *Error_Code is set to           */
  1474. /*               DLIST_SUCCESS.                                      */
  1475. /*            If unsuccessful, the function returns FALSE and        */
  1476. /*               *Error is set to a non-zero error code.             */
  1477. /*                                                                   */
  1478. /*   Error Handling: This function will fail if ListToCheck is not   */
  1479. /*                   a valid list.  If this happens, then *Error     */
  1480. /*                   is set to a non-zero error code.                */
  1481. /*                                                                   */
  1482. /*   Side Effects:  None.                                            */
  1483. /*                                                                   */
  1484. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1485. /*           this assumption is violated, an exception or trap       */
  1486. /*           may occur.                                              */
  1487. /*                                                                   */
  1488. /*********************************************************************/
  1489. BOOLEAN _System AtEndOfList( DLIST ListToCheck, CARDINAL32 * Error);
  1490.  
  1491. /*********************************************************************/
  1492. /*                                                                   */
  1493. /*   Function Name:  AtStartOfList                                   */
  1494. /*                                                                   */
  1495. /*   Descriptive Name:  This function returns TRUE if the            */
  1496. /*                      current item in the list is the first item   */
  1497. /*                      in the list.  Returns FALSE otherwise.       */
  1498. /*                                                                   */
  1499. /*   Input:  DLIST       ListToCheck : The list to check.            */
  1500. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1501. /*                                the error return code              */
  1502. /*                                                                   */
  1503. /*   Output:  If successful, the function returns TRUE if the        */
  1504. /*               current item in the list is the first item in the   */
  1505. /*               list.  If it is not the first item in the list,     */
  1506. /*               FALSE is returned.  *Error_Code is set to           */
  1507. /*               DLIST_SUCCESS.                                      */
  1508. /*            If unsuccessful, the function returns FALSE and        */
  1509. /*               *Error is set to a non-zero error code.             */
  1510. /*                                                                   */
  1511. /*   Error Handling: This function will fail if ListToCheck is not   */
  1512. /*                   a valid list.  If this happens, then *Error     */
  1513. /*                   is set to a non-zero error code.                */
  1514. /*                                                                   */
  1515. /*   Side Effects:  None.                                            */
  1516. /*                                                                   */
  1517. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1518. /*           this assumption is violated, an exception or trap       */
  1519. /*           may occur.                                              */
  1520. /*                                                                   */
  1521. /*********************************************************************/
  1522. BOOLEAN _System AtStartOfList( DLIST ListToCheck, CARDINAL32 * Error);
  1523.  
  1524. /*********************************************************************/
  1525. /*                                                                   */
  1526. /*   Function Name:  DestroyList                                     */
  1527. /*                                                                   */
  1528. /*   Descriptive Name:  This function releases the memory associated */
  1529. /*                      with the internal data structures of a DLIST.*/
  1530. /*                      Once a DLIST has been eliminated by this     */
  1531. /*                      function, it must be reinitialized before it */
  1532. /*                      can be used again.                           */
  1533. /*                                                                   */
  1534. /*   Input:  DLIST       ListToDestroy : The list to be eliminated   */
  1535. /*                                      from memory.                 */
  1536. /*           BOOLEAN FreeItemMemory : If TRUE, all items in the list */
  1537. /*                                    will be freed.  If FALSE, all  */
  1538. /*                                    items in the list are not      */
  1539. /*                                    freed, only the list structures*/
  1540. /*                                    associated with them are.      */
  1541. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1542. /*                                the error return code              */
  1543. /*                                                                   */
  1544. /*   Output:  If successful, *Error will be set to 0.                */
  1545. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1546. /*               code.                                               */
  1547. /*                                                                   */
  1548. /*   Error Handling: This function will fail if ListToDestroy is not */
  1549. /*                   a valid list.  If this happens, then *Error     */
  1550. /*                   is set to a non-zero error code.                */
  1551. /*                                                                   */
  1552. /*   Side Effects:  None.                                            */
  1553. /*                                                                   */
  1554. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1555. /*           this assumption is violated, an exception or trap       */
  1556. /*           may occur.                                              */
  1557. /*                                                                   */
  1558. /*           If FreeItemMemory is TRUE, then this function will try  */
  1559. /*           to delete any items which may be in the list.  However, */
  1560. /*           since this function has no way of knowing the internal  */
  1561. /*           structure of an item, items which contain embedded      */
  1562. /*           pointers will not be entirely freed.  This can lead to  */
  1563. /*           memory leaks.  The programmer should ensure that any    */
  1564. /*           list passed to this function when the FreeItemMemory    */
  1565. /*           parameter is TRUE is empty or does not contain any      */
  1566. /*           items with embedded pointers.                           */
  1567. /*                                                                   */
  1568. /*********************************************************************/
  1569. void _System DestroyList( DLIST *  ListToDestroy, BOOLEAN FreeItemMemory, CARDINAL32 * Error);
  1570.  
  1571. /*********************************************************************/
  1572. /*                                                                   */
  1573. /*   Function Name:  NextItem                                        */
  1574. /*                                                                   */
  1575. /*   Descriptive Name:  This function makes the next item in the list*/
  1576. /*                      the current item in the list (i.e. it        */
  1577. /*                      advances the current item pointer).          */
  1578. /*                                                                   */
  1579. /*   Input:  DLIST       ListToAdvance : The list whose current item */
  1580. /*                                      pointer is to be advanced    */
  1581. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1582. /*                                the error return code              */
  1583. /*                                                                   */
  1584. /*   Output:  If successful, *Error will be set to 0.                */
  1585. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1586. /*               code.                                               */
  1587. /*                                                                   */
  1588. /*   Error Handling: This function will fail under the following     */
  1589. /*                   conditions:                                     */
  1590. /*                        ListToAdvance is not a valid list          */
  1591. /*                        ListToAdvance is empty                     */
  1592. /*                        The current item is the last item in the   */
  1593. /*                           list                                    */
  1594. /*                   If any of these conditions occurs, then *Error  */
  1595. /*                   is set to a non-zero error code.                */
  1596. /*                                                                   */
  1597. /*   Side Effects:  None.                                            */
  1598. /*                                                                   */
  1599. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1600. /*           this assumption is violated, an exception or trap       */
  1601. /*           may occur.                                              */
  1602. /*                                                                   */
  1603. /*********************************************************************/
  1604. void _System NextItem( DLIST  ListToAdvance, CARDINAL32 * Error);
  1605.  
  1606. /*********************************************************************/
  1607. /*                                                                   */
  1608. /*   Function Name:  PreviousItem                                    */
  1609. /*                                                                   */
  1610. /*   Descriptive Name:  This function makes the previous item in the */
  1611. /*                      list the current item in the list.           */
  1612. /*                                                                   */
  1613. /*   Input:  DLIST       ListToChange : The list whose current item  */
  1614. /*                                      pointer is to be changed     */
  1615. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1616. /*                                the error return code              */
  1617. /*                                                                   */
  1618. /*   Output:  If successful, *Error will be set to 0.                */
  1619. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1620. /*               code.                                               */
  1621. /*                                                                   */
  1622. /*   Error Handling: This function will fail under the following     */
  1623. /*                   conditions:                                     */
  1624. /*                        ListToChange is not a valid list           */
  1625. /*                        ListToChange is empty                      */
  1626. /*                        The current item is the first item in the  */
  1627. /*                           list                                    */
  1628. /*                   If any of these conditions occurs, then *Error  */
  1629. /*                   is set to a non-zero error code.                */
  1630. /*                                                                   */
  1631. /*   Side Effects:  None.                                            */
  1632. /*                                                                   */
  1633. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1634. /*           this assumption is violated, an exception or trap       */
  1635. /*           may occur.                                              */
  1636. /*                                                                   */
  1637. /*********************************************************************/
  1638. void _System PreviousItem( DLIST  ListToChange, CARDINAL32 * Error);
  1639.  
  1640. /*********************************************************************/
  1641. /*                                                                   */
  1642. /*   Function Name: GoToStartOfList                                  */
  1643. /*                                                                   */
  1644. /*   Descriptive Name:  This function makes the first item in the    */
  1645. /*                      list the current item in the list.           */
  1646. /*                                                                   */
  1647. /*   Input:  DLIST       ListToReset : The list whose current item   */
  1648. /*                                    is to be set to the first item */
  1649. /*                                    in the list                    */
  1650. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1651. /*                                the error return code              */
  1652. /*                                                                   */
  1653. /*   Output:  If successful, *Error will be set to 0.                */
  1654. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1655. /*               code.                                               */
  1656. /*                                                                   */
  1657. /*   Error Handling: This function will fail if ListToReset is not   */
  1658. /*                   a valid list.  If this occurs, then *Error      */
  1659. /*                   is set to a non-zero error code.                */
  1660. /*                                                                   */
  1661. /*   Side Effects:  None.                                            */
  1662. /*                                                                   */
  1663. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1664. /*           this assumption is violated, an exception or trap       */
  1665. /*           may occur.                                              */
  1666. /*                                                                   */
  1667. /*********************************************************************/
  1668. void _System GoToStartOfList( DLIST ListToReset, CARDINAL32 * Error);
  1669.  
  1670. /*********************************************************************/
  1671. /*                                                                   */
  1672. /*   Function Name: GoToEndOfList                                    */
  1673. /*                                                                   */
  1674. /*   Descriptive Name:  This function makes the last item in the     */
  1675. /*                      list the current item in the list.           */
  1676. /*                                                                   */
  1677. /*   Input:  DLIST       ListToSet : The list whose current item     */
  1678. /*                                    is to be set to the last item  */
  1679. /*                                    in the list                    */
  1680. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1681. /*                                the error return code              */
  1682. /*                                                                   */
  1683. /*   Output:  If successful, *Error will be set to 0.                */
  1684. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1685. /*               code.                                               */
  1686. /*                                                                   */
  1687. /*   Error Handling: This function will fail if ListToSet is not     */
  1688. /*                   a valid list.  If this occurs, then *Error      */
  1689. /*                   is set to a non-zero error code.                */
  1690. /*                                                                   */
  1691. /*   Side Effects:  None.                                            */
  1692. /*                                                                   */
  1693. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1694. /*           this assumption is violated, an exception or trap       */
  1695. /*           may occur.                                              */
  1696. /*                                                                   */
  1697. /*********************************************************************/
  1698. void _System GoToEndOfList( DLIST ListToSet, CARDINAL32 * Error);
  1699.  
  1700. /*********************************************************************/
  1701. /*                                                                   */
  1702. /*   Function Name: GoToSpecifiedItem                                */
  1703. /*                                                                   */
  1704. /*   Descriptive Name:  This function makes the item associated with */
  1705. /*                      Handle the current item in the list.         */
  1706. /*                                                                   */
  1707. /*   Input:  DLIST  ListToReposition:  The list whose current item   */
  1708. /*                                    is to be set to the item       */
  1709. /*                                    associated with Handle.        */
  1710. /*           ADDRESS Handle : A handle obtained by using the         */
  1711. /*                            GetHandle function.  This handle       */
  1712. /*                            identifies a unique item in the list.  */
  1713. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1714. /*                                the error return code              */
  1715. /*                                                                   */
  1716. /*   Output:  If successful, *Error will be set to 0.                */
  1717. /*            If unsuccessful, *Error will be set to a non-zero error*/
  1718. /*               code.                                               */
  1719. /*                                                                   */
  1720. /*   Error Handling: This function will fail if ListToReposition is  */
  1721. /*                   not a valid list.  If this occurs, then *Error  */
  1722. /*                   is set to a non-zero error code.                */
  1723. /*                                                                   */
  1724. /*   Side Effects:  None.                                            */
  1725. /*                                                                   */
  1726. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1727. /*           this assumption is violated, an exception or trap       */
  1728. /*           may occur.                                              */
  1729. /*                                                                   */
  1730. /*                                                                   */
  1731. /*           It is assumed that Handle is a valid handle and that    */
  1732. /*           the item associated with Handle is still in the list.   */
  1733. /*           If these conditions are not met, an exception or trap   */
  1734. /*           may occur.                                              */
  1735. /*                                                                   */
  1736. /*********************************************************************/
  1737. void _System GoToSpecifiedItem( DLIST ListToReposition, ADDRESS Handle, CARDINAL32 * Error);
  1738.  
  1739. /*********************************************************************/
  1740. /*                                                                   */
  1741. /*   Function Name:  SortList                                        */
  1742. /*                                                                   */
  1743. /*   Descriptive Name:  This function sorts the contents of a list.  */
  1744. /*                      The sorting algorithm used is a stable sort  */
  1745. /*                      whose performance is not dependent upon the  */
  1746. /*                      initial order of the items in the list.      */
  1747. /*                                                                   */
  1748. /*   Input: DLIST ListToSort : The DLIST that is to be sorted.       */
  1749. /*                                                                   */
  1750. /*          INTEGER32 (*Compare) ( ... )                             */
  1751. /*                                                                   */
  1752. /*              This is a pointer to a function that can compare any */
  1753. /*              two items in the list.  It should return -1 if       */
  1754. /*              Object1 is less than Object2, 0 if Object1 is equal  */
  1755. /*              to Object2, and 1 if Object1 is greater than Object2.*/
  1756. /*              This function will be called during the sort whenever*/
  1757. /*              the sorting algorithm needs to compare two objects.  */
  1758. /*                                                                   */
  1759. /*              The Compare function takes the following parameters: */
  1760. /*                                                                   */
  1761. /*              ADDRESS Object1 : The address of the data for the    */
  1762. /*                                first object to be compared.       */
  1763. /*              TAG Object1Tag : The user assigned TAG value for the */
  1764. /*                               first object to be compared.        */
  1765. /*              ADDRESS Object2 : The address of the data for the    */
  1766. /*                                second object to be compared.      */
  1767. /*              TAG Object2Tag : The user assigned TAG value for the */
  1768. /*                               second object to be compared.       */
  1769. /*              CARDINAL32 * Error : The address of a variable to    */
  1770. /*                                   hold the error return value.    */
  1771. /*                                                                   */
  1772. /*              If this function ever sets *Error to a non-zero value*/
  1773. /*              the sort will terminate and the error code will be   */
  1774. /*              returned to the caller of the SortList function.     */
  1775. /*                                                                   */
  1776. /*          CARDINAL32 * Error : The address of a variable to hold   */
  1777. /*                               the error return value.             */
  1778. /*                                                                   */
  1779. /*   Output:  If successful, this function will set *Error to        */
  1780. /*               DLIST_SUCCESS and ListToSort will have been sorted. */
  1781. /*            If unsuccessful, *Error will contain an error code.    */
  1782. /*               The order of the items in ListToSort is undefined   */
  1783. /*               and may have changed.                               */
  1784. /*                                                                   */
  1785. /*   Error Handling: This function will terminate if *Compare sets   */
  1786. /*                   *Error to a non-zero value, or if ListToSort    */
  1787. /*                   is invalid.  If this function does terminate in */
  1788. /*                   the middle of a sort, the order of the items in */
  1789. /*                   ListToSort may be different than it was before  */
  1790. /*                   the function was called.                        */
  1791. /*                                                                   */
  1792. /*   Side Effects: None.                                             */
  1793. /*                                                                   */
  1794. /*   Notes:  It is assumed that Error contains a valid address. If   */
  1795. /*           this assumption is violated, an exception or trap       */
  1796. /*           may occur.                                              */
  1797. /*                                                                   */
  1798. /*********************************************************************/
  1799. void _System SortList(DLIST        ListToSort,
  1800. INTEGER32    (* _System Compare) (ADDRESS Object1, TAG Object1Tag, ADDRESS Object2, TAG Object2Tag,CARDINAL32 * Error),
  1801. CARDINAL32 * Error);
  1802.  
  1803. /*********************************************************************/
  1804. /*                                                                   */
  1805. /*   Function Name:  ForEachItem                                     */
  1806. /*                                                                   */
  1807. /*   Descriptive Name:  This function passes a pointer to each item  */
  1808. /*                      in a list to a user provided function for    */
  1809. /*                      processing by the user provided function.    */
  1810. /*                                                                   */
  1811. /*   Input:  DLIST ListToProcess : The DLIST whose items are to be   */
  1812. /*                                processed by the user provided     */
  1813. /*                                function.                          */
  1814. /*                                                                   */
  1815. /*           void (*ProcessItem) (...)                               */
  1816. /*                                                                   */
  1817. /*               This is a pointer to the user provided function.    */
  1818. /*               This user provided function takes the following     */
  1819. /*                  parameters:                                      */
  1820. /*                                                                   */
  1821. /*                  ADDRESS Object : A pointer to an item in         */
  1822. /*                                   ListToProcess.                  */
  1823. /*                  TAG Object1Tag : The user assigned TAG value for */
  1824. /*                                   the item pointed to by Object.  */
  1825. /*                  ADDRESS Parameter : The address of a block of    */
  1826. /*                                      memory containing any        */
  1827. /*                                      parameters that the user     */
  1828. /*                                      wishes to have passed to this*/
  1829. /*                                      function.                    */
  1830. /*                  CARDINAL32 * Error : The address of a variable to*/
  1831. /*                                       hold the error return value.*/
  1832. /*                                                                   */
  1833. /*           ADDRESS Parameters : This field is passed through to    */
  1834. /*                                *ProcessItem.  This function does  */
  1835. /*                                not even look at the contents of   */
  1836. /*                                this field.  This field is here to */
  1837. /*                                provide the user a way to pass     */
  1838. /*                                additional data to *ProcessItem    */
  1839. /*                                that *ProcessItem may need to      */
  1840. /*                                function correctly.                */
  1841. /*                                                                   */
  1842. /*           BOOLEAN Forward : If TRUE, then the list is traversed   */
  1843. /*                             from the start of the list to the end */
  1844. /*                             of the list.  If FALSE, then the list */
  1845. /*                             is traversed from the end of the list */
  1846. /*                             to the beginning.                     */
  1847. /*                                                                   */
  1848. /*           CARDINAL32 * Error : The address of a variable to hold  */
  1849. /*                                the error return value.            */
  1850. /*                                                                   */
  1851. /*   Output:  If successful, this function will set *Error to        */
  1852. /*               DLIST_SUCCESS.                                      */
  1853. /*            If unsuccessful, then this function will set *Error to */
  1854. /*               a non-zero error code.                              */
  1855. /*                                                                   */
  1856. /*   Error Handling: This function aborts immediately when an error  */
  1857. /*                   is detected, and any remaining items in the list*/
  1858. /*                   will not be processed.                          */
  1859. /*                                                                   */
  1860. /*   Side Effects: None.                                             */
  1861. /*                                                                   */
  1862. /*   Notes: This function allows the user to access all of the items */
  1863. /*          in a list and perform an operation on them.  The         */
  1864. /*          operation performed must not free any items in the list, */
  1865. /*          or perform any list operations on the list being         */
  1866. /*          processed.                                               */
  1867. /*                                                                   */
  1868. /*          As an example of when this would be useful, consider a   */
  1869. /*          a list of graphic objects (rectangles, triangles, circles*/
  1870. /*          etc.)  which comprise a drawing.  To draw the picture    */
  1871. /*          that these graphic objects represent, one could build a  */
  1872. /*          loop which gets and draws each item.  Another way to     */
  1873. /*          do this would be to build a drawing function which can   */
  1874. /*          draw any of the graphic objects, and then use that       */
  1875. /*          function as the ProcessItem function in a call to        */
  1876. /*          ForEachItem.                                             */
  1877. /*                                                                   */
  1878. /*          If the ProcessItem function sets *Error to something     */
  1879. /*          other than DLIST_SUCCESS, then ForEachItem will terminate*/
  1880. /*          and return an error to whoever called it.  The single    */
  1881. /*          exception to this is if ProcessItem sets *Error to       */
  1882. /*          DLIST_SEARCH_COMPLETE, in which case ForEachItem         */
  1883. /*          terminates and sets *Error to DLIST_SUCCESS.  This is    */
  1884. /*          usefull for using ForEachItem to search a list and then  */
  1885. /*          terminating the search once the desired item is found.   */
  1886. /*                                                                   */
  1887. /*          A word about the Parameters parameter.  This parameter   */
  1888. /*          is passed through to *ProcessItem and is never looked at */
  1889. /*          by this function.  This means that the user can put any  */
  1890. /*          value they desire into Parameters as long as it is the   */
  1891. /*          same size (in bytes) as Parameters.  The intended use of */
  1892. /*          Parameters is to allow the user to pass information to   */
  1893. /*          *ProcessItem that *ProcessItem may need.  Either way,    */
  1894. /*          how Parameters is used is literally up to the user.      */
  1895. /*                                                                   */
  1896. /*********************************************************************/
  1897. void _System ForEachItem(DLIST        ListToProcess,
  1898. void         (* _System ProcessItem) (ADDRESS Object, TAG ObjectTag, CARDINAL32 ObjectSize, ADDRESS ObjectHandle, ADDRESS Parameters, CARDINAL32 * Error),
  1899. ADDRESS      Parameters,
  1900. BOOLEAN      Forward,
  1901. CARDINAL32 * Error);
  1902.  
  1903. /*********************************************************************/
  1904. /*                                                                   */
  1905. /*   Function Name:  PruneList                                       */
  1906. /*                                                                   */
  1907. /*   Descriptive Name:  This function allows the caller to examine   */
  1908. /*                      each item in a list and optionally delete    */
  1909. /*                      it from the list.                            */
  1910. /*                                                                   */
  1911. /*   Input:  DLIST ListToProcess : The DLIST to be pruned.           */
  1912. /*                                                                   */
  1913. /*           BOOLEAN (*KillItem) (...)                               */
  1914. /*                                                                   */
  1915. /*               This is a pointer to a user provided function.      */
  1916. /*               This user provided function takes the following     */
  1917. /*                  parameters:                                      */
  1918. /*                                                                   */
  1919. /*                  ADDRESS Object : A pointer to an item in         */
  1920. /*                                   ListToProcess.                  */
  1921. /*                  TAG Object1Tag : The user assigned TAG value for */
  1922. /*                                   the item pointed to by Object.  */
  1923. /*                  ADDRESS Parameter : The address of a block of    */
  1924. /*                                      memory containing any        */
  1925. /*                                      parameters that the user     */
  1926. /*                                      wishes to have passed to this*/
  1927. /*                                      function.                    */
  1928. /*                  BOOLEAN * FreeMemory : The address of a BOOLEAN  */
  1929. /*                                         variable which this       */
  1930. /*                                         function will set to      */
  1931. /*                                         either TRUE or FALSE.     */
  1932. /*                                         If the function return    */
  1933. /*                                         value is TRUE, then the   */
  1934. /*                                         value in *FreeMemory will */
  1935. /*                                         be examined.  If it is    */
  1936. /*                                         TRUE, then PruneList will */
  1937. /*                                         free the memory associated*/
  1938. /*                                         with the item being       */
  1939. /*                                         deleted.  If *FreeMemory  */
  1940. /*                                         is FALSE, then the item   */
  1941. /*                                         being removed from the    */
  1942. /*                                         DLIST will not be freed,  */
  1943. /*                                         and it is up to the user  */
  1944. /*                                         to ensure that this memory*/
  1945. /*                                         is handled properly.      */
  1946. /*                  CARDINAL32 * Error : The address of a variable to*/
  1947. /*                                       hold the error return value.*/
  1948. /*                                                                   */
  1949. /*           ADDRESS Parameters : This field is passed through to    */
  1950. /*                                *ProcessItem.  This function does  */
  1951. /*                                not even look at the contents of   */
  1952. /*                                this field.  This field is here to */
  1953. /*                                provide the user a way to pass     */
  1954. /*                                additional data to *ProcessItem    */
  1955. /*                                that *ProcessItem may need to      */
  1956. /*                                function correctly.                */
  1957. /*                                                                   */
  1958. /*          CARDINAL32 * Error : The address of a variable to hold   */
  1959. /*                               the error return value.             */
  1960. /*                                                                   */
  1961. /*   Output:  If successful, this function will set *Error to        */
  1962. /*               DLIST_SUCCESS.                                      */
  1963. /*            If unsuccessful, then this function will set *Error to */
  1964. /*               a non-zero error code.                              */
  1965. /*                                                                   */
  1966. /*   Error Handling: This function aborts immediately when an error  */
  1967. /*                   is detected, and any remaining items in the list*/
  1968. /*                   will not be processed.                          */
  1969. /*                                                                   */
  1970. /*   Side Effects: None.                                             */
  1971. /*                                                                   */
  1972. /*   Notes: This function allows the user to access all of the items */
  1973. /*          in a list, perform an operation on them, and then        */
  1974. /*          optionally delete ("remove") them from the DLIST.  The   */
  1975. /*          operation performed must not free any items in the list, */
  1976. /*          or perform any list operations on the list being         */
  1977. /*          processed.                                               */
  1978. /*                                                                   */
  1979. /*          If the KillItem function sets *Error to something other  */
  1980. /*          than DLIST_SUCCESS, then PruneList will terminate and    */
  1981. /*          return an error to whoever called it.  The single        */
  1982. /*          exception to this is if KillItem sets *Error to          */
  1983. /*          DLIST_SEARCH_COMPLETE, in which case KillItem            */
  1984. /*          terminates and sets *Error to DLIST_SUCCESS.  This is    */
  1985. /*          usefull for using KillItem to search a list and then     */
  1986. /*          terminating the search once the desired item is found.   */
  1987. /*                                                                   */
  1988. /*          A word about the Parameters parameter.  This parameter   */
  1989. /*          is passed through to *ProcessItem and is never looked at */
  1990. /*          by this function.  This means that the user can put any  */
  1991. /*          value they desire into Parameters as long as it is the   */
  1992. /*          same size (in bytes) as Parameters.  The intended use of */
  1993. /*          Parameters is to allow the user to pass information to   */
  1994. /*          *ProcessItem that *ProcessItem may need.  Either way,    */
  1995. /*          how Parameters is used is literally up to the user.      */
  1996. /*                                                                   */
  1997. /*********************************************************************/
  1998. void _System PruneList(DLIST        ListToProcess,
  1999. BOOLEAN      (* _System KillItem) (ADDRESS Object, TAG ObjectTag, CARDINAL32 ObjectSize, ADDRESS ObjectHandle, ADDRESS Parameters, BOOLEAN * FreeMemory, CARDINAL32 * Error),
  2000. ADDRESS      Parameters,
  2001. CARDINAL32 * Error);
  2002.  
  2003. /*********************************************************************/
  2004. /*                                                                   */
  2005. /*   Function Name:  AppendList                                      */
  2006. /*                                                                   */
  2007. /*   Descriptive Name: Removes the items in SourceList and appends   */
  2008. /*                     them to TargetList.                           */
  2009. /*                                                                   */
  2010. /*   Input:  DLIST TargetList : The DLIST which is to have the items */
  2011. /*                             from SourceList appended to it.       */
  2012. /*           DLIST SourceList : The DLIST whose items are to be      */
  2013. /*                              removed and appended to TargetList.  */
  2014. /*          CARDINAL32 * Error : The address of a variable to hold   */
  2015. /*                               the error return value.             */
  2016. /*                                                                   */
  2017. /*   Output: If successful, *Error will be set to DLIST_SUCCESS,     */
  2018. /*              SourceList will be empty, and TargetList will contain*/
  2019. /*              all of its original items and all of the items that  */
  2020. /*              were in SourceList.                                  */
  2021. /*           If unsuccessful, *Error will be set to a non-zero value */
  2022. /*              and SourceList and TargetList will be unmodified.    */
  2023. /*                                                                   */
  2024. /*   Error Handling:  This function will abort immediately upon      */
  2025. /*                    detection of an error.  All errors that can be */
  2026. /*                    detected are detected before the contents of   */
  2027. /*                    SourceList are appended to TargetList, so if an*/
  2028. /*                    error is detected and the function aborts,     */
  2029. /*                    SourceList and TargetList are unaltered.       */
  2030. /*                                                                   */
  2031. /*   Side Effects: None.                                             */
  2032. /*                                                                   */
  2033. /*   Notes: None.                                                    */
  2034. /*                                                                   */
  2035. /*********************************************************************/
  2036. void _System AppendList(DLIST        TargetList,
  2037. DLIST        SourceList,
  2038. CARDINAL32 * Error);
  2039.  
  2040. /*********************************************************************/
  2041. /*                                                                   */
  2042. /*   Function Name:  TransferItem                                    */
  2043. /*                                                                   */
  2044. /*   Descriptive Name: Removes an item in SourceList and places in   */
  2045. /*                     TargetList.                                   */
  2046. /*                                                                   */
  2047. /*   Input:  DLIST SourceList : The DLIST containing the item which  */
  2048. /*                              is to be transferred.                */
  2049. /*           ADDRESS SourceHandle : The handle of the item in        */
  2050. /*                                   SourceList which is to be       */
  2051. /*                                   transferred to another DLIST.   */
  2052. /*                                   If this is NULL, then the       */
  2053. /*                                   current item in SourceList will */
  2054. /*                                   be used.                        */
  2055. /*           DLIST TargetList : The DLIST which is to receive the    */
  2056. /*                              item being transferred.              */
  2057. /*           ADDRESS TargetHandle : The item in TargetList which     */
  2058. /*                                   is used to determine where      */
  2059. /*                                   the item being transferred will */
  2060. /*                                   be placed.  If this is NULL,    */
  2061. /*                                   then the current item in        */
  2062. /*                                   TargetList will be used.        */
  2063. /*           Insertion_Modes TransferMode : This indicates where,    */
  2064. /*                                   relative to the item in         */
  2065. /*                                   TargetList specified by         */
  2066. /*                                   Target_Handle, the item being   */
  2067. /*                                   transferred can be placed.      */
  2068. /*          BOOLEAN MakeCurrent : If TRUE, the item transferred to   */
  2069. /*                                 TargetList becomes the current    */
  2070. /*                                 item in TargetList.               */
  2071. /*          CARDINAL32 * Error : The address of a variable to hold   */
  2072. /*                               the error return value.             */
  2073. /*                                                                   */
  2074. /*   Output: If successful, *Error will be set to DLIST_SUCCESS,     */
  2075. /*              SourceList will be empty, and TargetList will contain*/
  2076. /*              all of its original items and all of the items that  */
  2077. /*              were in SourceList.                                  */
  2078. /*           If unsuccessful, *Error will be set to a non-zero value */
  2079. /*              and SourceList and TargetList will be unmodified.    */
  2080. /*                                                                   */
  2081. /*   Error Handling:  This function will abort immediately upon      */
  2082. /*                    detection of an error.  All errors that can be */
  2083. /*                    detected are detected before the contents of   */
  2084. /*                    SourceList are appended to TargetList, so if an*/
  2085. /*                    error is detected and the function aborts,     */
  2086. /*                    SourceList and TargetList are unaltered.       */
  2087. /*                                                                   */
  2088. /*   Side Effects: None.                                             */
  2089. /*                                                                   */
  2090. /*   Notes: None.                                                    */
  2091. /*                                                                   */
  2092. /*********************************************************************/
  2093. void _System TransferItem(DLIST             SourceList,
  2094. ADDRESS           SourceHandle,
  2095. DLIST             TargetList,
  2096. ADDRESS           TargetHandle,
  2097. Insertion_Modes   TransferMode,
  2098. BOOLEAN           MakeCurrent,
  2099. CARDINAL32 *      Error);
  2100.  
  2101. /*********************************************************************/
  2102. /*                                                                   */
  2103. /*   Function Name:  CheckListIntegrity                              */
  2104. /*                                                                   */
  2105. /*   Descriptive Name: Checks the integrity of a DLIST.  All link    */
  2106. /*                     nodes in the list are checked, as are all     */
  2107. /*                     fields in the list control block.             */
  2108. /*                                                                   */
  2109. /*   Input:  DLIST ListToCheck - The list whose integrity is to be   */
  2110. /*                               checked.                            */
  2111. /*                                                                   */
  2112. /*   Output: The function return value will be TRUE if all of the    */
  2113. /*           elements in the DLIST are correct.  If this function    */
  2114. /*           returns FALSE, then the DLIST being checked has been    */
  2115. /*           corrupted!                                              */
  2116. /*                                                                   */
  2117. /*   Error Handling: If this function encounters an error in a DLIST,*/
  2118. /*                   it will return FALSE.                           */
  2119. /*                                                                   */
  2120. /*   Side Effects: None.                                             */
  2121. /*                                                                   */
  2122. /*   Notes: None.                                                    */
  2123. /*                                                                   */
  2124. /*********************************************************************/
  2125. BOOLEAN _System CheckListIntegrity(DLIST ListToCheck);
  2126.  
  2127. #endif
  2128.  
  2129.