mirror of https://github.com/vitalif/e2fsprogs
2358 lines
150 KiB
C
2358 lines
150 KiB
C
/*
|
|
*
|
|
* Copyright (c) International Business Machines Corp., 2000
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
|
* the GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, write to the Free Software
|
|
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
*
|
|
* Module: dlist.h
|
|
*
|
|
* Functions: dlist_t CreateList
|
|
* int InsertItem
|
|
* int InsertObject
|
|
* int DeleteItem
|
|
* int DeleteAllItems
|
|
* int GetItem
|
|
* int GetNextItem
|
|
* int GetPreviousItem
|
|
* int GetObject
|
|
* int BlindGetObject
|
|
* int GetNextObject
|
|
* int GetPreviousObject
|
|
* int ExtractItem
|
|
* int ExtractObject
|
|
* int BlindExtractObject
|
|
* int ReplaceItem
|
|
* int ReplaceObject
|
|
* int GetTag
|
|
* int GetHandle
|
|
* int GetListSize
|
|
* BOOLEAN ListEmpty
|
|
* BOOLEAN AtEndOfList
|
|
* BOOLEAN AtStartOfList
|
|
* int DestroyList
|
|
* int NextItem
|
|
* int PreviousItem
|
|
* int GoToStartOfList
|
|
* int GoToEndOfList
|
|
* int GoToSpecifiedItem
|
|
* int SortList
|
|
* int ForEachItem
|
|
* int PruneList
|
|
* int AppendList
|
|
* int TransferItem
|
|
* int CopyList
|
|
* BOOLEAN CheckListIntegrity
|
|
*
|
|
* Description: This module implements a simple, generic, doubly linked list.
|
|
* Data objects of any type can be placed into a linked list
|
|
* created by this module. Furthermore, data objects of different
|
|
* types may be placed into the same linked list.
|
|
*
|
|
* Notes: This linked list implementation makes use of the concept of the
|
|
* current item. In any non-empty list, one item in the list will
|
|
* be designated as the current item. When any of the following
|
|
* functions are called, they will operate upon the current item
|
|
* only: GetItem, ReplaceItem, DeleteItem, GetTag, NextItem,
|
|
* PreviousItem, GetObject, ExtractItem, and ExtractObject. The
|
|
* user of this module may set the current item through the use of
|
|
* the GoToStartOfList, GoToEndOfList, NextItem, PreviousItem,
|
|
* and GoToSpecifiedItem functions.
|
|
*
|
|
* Since a linked list created by this module may contain items
|
|
* of different types, the user will need a way to identify items
|
|
* of different types which may be in the same list. To allow users
|
|
* to do this, the concept of an item tag is used. When an item is
|
|
* added to the list, the user must enter an item tag. The item
|
|
* tag is merely some identifier that the user wishes to associate
|
|
* with the item being placed into the list. When used as intended,
|
|
* each type of data item will have a unique tag associated with it.
|
|
* This way, all data items of the same type will have the same tag
|
|
* while data items of different types will have different tags.
|
|
* Thus, by using the GetTag function, the user can get the item
|
|
* tag for the current item without having to get the item from the
|
|
* list. This allows the user to differentiate between items of
|
|
* different types which reside in the same list.
|
|
*
|
|
* This module is single threaded. If used in a multi-threaded
|
|
* environment, the user must implement appropriate access controls.
|
|
*
|
|
* When an item is inserted or appended to a list, this module
|
|
* allocates memory on the heap to hold the item and then copies
|
|
* the item to the memory that it allocated. This allows local
|
|
* variables to be safely inserted or appended to a list. However,
|
|
* it should be noted that under certain circumstances a copy of the
|
|
* entire data item will NOT be made. Specifically, if the data item
|
|
* is a structure or array containing pointers, then the data pointed
|
|
* to by the pointers will NOT be copied even though the structure or
|
|
* array is! This results from the fact that, when an item is being
|
|
* inserted or appended to a list, the user provides just an address
|
|
* and size. This module assumes that the item to inserted or append
|
|
* lies in a contiguous block of memory at the address provided by the
|
|
* user. This module has no way of knowing the structure of the data
|
|
* at the specified address, and therefore can not know about any
|
|
* embedded pointers which may lie within that block of memory.
|
|
*
|
|
* This module now employs the concept of a handle. A handle is a
|
|
* reference to a specific item in a list which allows that item to
|
|
* be made the current item in the list quickly. Example: If you
|
|
* use the GetHandle function to get a handle for the current item
|
|
* (lets call the item B1), then, regardless of where you are in the
|
|
* list (or any reodering of the items in the list), you can make item
|
|
* B1 the current item by passing its handle to the GoToSpecifiedItem
|
|
* function. Alternatively, you could operate directly on B1 using
|
|
* the other handle based functions, such as GetItem_By_Handle, for
|
|
* example. GetItem_By_Handle gets the item associated with the
|
|
* specified handle without changing which item in the list is the
|
|
* current item in the list.
|
|
*
|
|
* The functions of this module refer to user data as either items or
|
|
* objects. The difference between the two is simple, yet subtle. It
|
|
* deals with who is responsible for the memory used to hold the data.
|
|
* In the case of an item, this module is responsible for the memory
|
|
* used to hold the user data. In the case of an object, the user
|
|
* is responsible for the memory used to hold the data.
|
|
*
|
|
* What this means is that, for functions adding ITEMS to a list,
|
|
* this module will be responsible for allocating memory to hold
|
|
* the user data and then copying the user data into the memory
|
|
* that was allocated. For functions which return items, this
|
|
* module will COPY the user data from the LIST into a buffer
|
|
* specified by the user. For functions which add objects to a
|
|
* list, the user provides a pointer to a block of memory holding
|
|
* user data. This block of memory was allocated by the user, and
|
|
* becomes the "property" of this module once it has been added to
|
|
* a LIST. For functions which return objects, a pointer to the
|
|
* memory where the data is stored is returned. As long as an item/object
|
|
* is in a LIST, this module will be responsible for the memory that
|
|
* is used to store the data associated with that item. This means that
|
|
* users of this module should not call free on an object returned by this
|
|
* module as long as that object is still within a list.
|
|
*
|
|
*
|
|
*/
|
|
|
|
#ifndef DLISTHANDLER
|
|
|
|
#define DLISTHANDLER 1
|
|
|
|
#include <linux/types.h> /* will pull in platform specific data type info from linux/include/asm */
|
|
#include <errno.h>
|
|
|
|
#ifndef BOOLEAN_DEFINED
|
|
#define BOOLEAN_DEFINED 1
|
|
typedef u_int8_t BOOLEAN;
|
|
#endif
|
|
|
|
typedef void * ADDRESS;
|
|
typedef ulong TAG;
|
|
|
|
struct LinkNodeRecord
|
|
{
|
|
ADDRESS DataLocation; /* Where the data associated with this LinkNode is */
|
|
uint DataSize; /* The size of the data associated with this LinkNode. */
|
|
TAG DataTag; /* The item tag the user gave to the data. */
|
|
struct MasterListRecord * ControlNodeLocation; /* The control node of the list containing this item. */
|
|
struct LinkNodeRecord * NextLinkNode; /* The LinkNode of the next item in the list. */
|
|
struct LinkNodeRecord * PreviousLinkNode; /* The LinkNode of the item preceding this one in the list. */
|
|
};
|
|
|
|
typedef struct LinkNodeRecord LinkNode;
|
|
|
|
struct MasterListRecord
|
|
{
|
|
uint ItemCount; /* The number of items in the list. */
|
|
LinkNode * StartOfList; /* The address of the LinkNode of the first item in the list. */
|
|
LinkNode * EndOfList; /* The address of the LinkNode of the last item in the list. */
|
|
LinkNode * CurrentItem; /* The address of the LinkNode of the current item in the list. */
|
|
#ifdef USE_POOLMAN
|
|
POOL NodePool; /* The pool of LinkNodes for this dlist_t. */
|
|
#endif
|
|
uint Verify; /* A field to contain the VerifyValue which marks this as a list created by this module. */
|
|
};
|
|
|
|
typedef struct MasterListRecord ControlNode;
|
|
|
|
|
|
typedef ControlNode * dlist_t;
|
|
|
|
|
|
#ifndef TRUE
|
|
#define TRUE 1
|
|
#endif
|
|
#ifndef FALSE
|
|
#define FALSE 0
|
|
#endif
|
|
|
|
|
|
typedef enum _Insertion_Modes {
|
|
InsertAtStart,
|
|
InsertBefore,
|
|
InsertAfter,
|
|
AppendToList,
|
|
} Insertion_Modes;
|
|
|
|
/* Update the IS_DLIST_ERROR() macro below if you add, remove, or change */
|
|
/* error codes. */
|
|
|
|
#define DLIST_SUCCESS 0
|
|
#define DLIST_OUT_OF_MEMORY ENOMEM
|
|
|
|
#define DLIST_CORRUPTED 201
|
|
#define DLIST_BAD 202
|
|
#define DLIST_NOT_INITIALIZED 203
|
|
#define DLIST_EMPTY 204
|
|
#define DLIST_ITEM_SIZE_WRONG 205
|
|
#define DLIST_BAD_ITEM_POINTER 206
|
|
#define DLIST_ITEM_SIZE_ZERO 207
|
|
#define DLIST_ITEM_TAG_WRONG 208
|
|
#define DLIST_END_OF_LIST 209
|
|
#define DLIST_ALREADY_AT_START 210
|
|
#define DLIST_BAD_HANDLE 211
|
|
#define DLIST_INVALID_INSERTION_MODE 212
|
|
#define DLIST_OBJECT_NOT_FOUND 213
|
|
#define DLIST_OBJECT_ALREADY_IN_LIST 214
|
|
|
|
/* Macro to determine if an error code is a dlist error code. */
|
|
|
|
#define IS_DLIST_ERROR(rc) ((abs(rc) >= DLIST_CORRUPTED) && (abs(rc) <= DLIST_OBJECT_ALREADY_IN_LIST))
|
|
|
|
/* The following code is special. It is for use with the PruneList and ForEachItem functions. Basically, these functions
|
|
can be thought of as "searching" a list. They present each item in the list to a user supplied function which can then
|
|
operate on the items. If the user supplied function returns a non-zero error code, ForEachItem and PruneList abort and
|
|
return an error to the caller. This may be undesirable. If the user supplied function used with PruneList and ForEachItem
|
|
returns the code below, PruneList/ForEachItem will abort and return DLIST_SUCCESS. This allows PruneList and ForEachItem
|
|
to be used to search a list and terminate the search when the desired item is found without having to traverse the
|
|
remaining items in the list. */
|
|
|
|
#define DLIST_SEARCH_COMPLETE 0xFF
|
|
|
|
#ifdef USE_POOLMAN
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: CreateList */
|
|
/* */
|
|
/* Descriptive Name: This function allocates and initializes the */
|
|
/* data structures associated with a list and */
|
|
/* then returns a pointer to these structures. */
|
|
/* */
|
|
/* Input: uint InitialPoolSize - Each List gets a pool of */
|
|
/* link nodes. When items are */
|
|
/* added to the List, a link node*/
|
|
/* is removed from the pool. */
|
|
/* When an item is removed from */
|
|
/* the List, the link node used */
|
|
/* for that item is returned to */
|
|
/* the pool. InitialPoolSize is */
|
|
/* the number of link nodes to */
|
|
/* place in the pool when the */
|
|
/* pool is created. */
|
|
/* uint MaximumPoolSize - When the pool runs out of */
|
|
/* link nodes, new nodes are */
|
|
/* allocated by the pool. When */
|
|
/* these links start being */
|
|
/* returned to the pool, the pool*/
|
|
/* will grow. This parameter */
|
|
/* puts a limit on how big the */
|
|
/* pool may grow to. Once the */
|
|
/* pool reaches this size, any */
|
|
/* link nodes being returned to */
|
|
/* the pool will be deallocated. */
|
|
/* uint PoolIncrement - When the pool runs out of link*/
|
|
/* nodes and more are required, */
|
|
/* the pool will allocate one or */
|
|
/* more link nodes. This tells the*/
|
|
/* pool how many link nodes to */
|
|
/* allocate at one time. */
|
|
/* */
|
|
/* Output: If Success : The function return value will be non-NULL */
|
|
/* */
|
|
/* If Failure : The function return value will be NULL. */
|
|
/* */
|
|
/* Error Handling: The function will only fail if it can not */
|
|
/* allocate enough memory to create the new list */
|
|
/* and its associated pool of link nodes. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
dlist_t CreateList(uint InitialPoolSize,
|
|
uint MaximumPoolSize,
|
|
uint PoolIncrement);
|
|
|
|
#else
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: CreateList */
|
|
/* */
|
|
/* Descriptive Name: This function allocates and initializes the */
|
|
/* data structures associated with a list and */
|
|
/* then returns a pointer to these structures. */
|
|
/* */
|
|
/* Input: None. */
|
|
/* */
|
|
/* Output: If Success : The function return value will be non-NULL */
|
|
/* */
|
|
/* If Failure : The function return value will be NULL. */
|
|
/* */
|
|
/* Error Handling: The function will only fail if it can not */
|
|
/* allocate enough memory to create the new list. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
dlist_t CreateList( void );
|
|
|
|
#endif
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: InsertItem */
|
|
/* */
|
|
/* Descriptive Name: This function inserts an item into a dlist_t.*/
|
|
/* The item can be placed either before or */
|
|
/* after the current item in the dlist_t. */
|
|
/* */
|
|
/* Input: dlist_t ListToAddTo : The list to which the */
|
|
/* data item is to be */
|
|
/* added. */
|
|
/* uint ItemSize : The size of the data item, in */
|
|
/* bytes. */
|
|
/* ADDRESS ItemLocation : The address of the data */
|
|
/* to append to the list */
|
|
/* TAG ItemTag : The item tag to associate with */
|
|
/* item being appended to the list */
|
|
/* ADDRESS TargetHandle : The item in ListToAddTo which */
|
|
/* is used to determine where */
|
|
/* the item being transferred will */
|
|
/* be placed. If this is NULL, */
|
|
/* then the current item in */
|
|
/* ListToAddTo will be used. */
|
|
/* Insertion_Modes InsertMode : This indicates where, */
|
|
/* relative to the item in */
|
|
/* ListToAddTo specified by */
|
|
/* Target_Handle, the item being */
|
|
/* inserted can be placed. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
|
|
/* into ListToAddTo becomes the */
|
|
/* current item in ListToAddTo. */
|
|
/* ADDRESS * Handle : The address of a variable to hold */
|
|
/* the handle for the item that was */
|
|
/* inserted into the list. */
|
|
/* */
|
|
/* Output: If all went well, the return value will be */
|
|
/* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
|
|
/* the new item. If errors were encountered, the . */
|
|
/* return value will be the error code and *Handle will */
|
|
/* be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToAddTo does not point to a valid */
|
|
/* list */
|
|
/* ItemSize is 0 */
|
|
/* ItemLocation is NULL */
|
|
/* The memory required to hold a copy of the */
|
|
/* item can not be allocated. */
|
|
/* The memory required to create a LINK NODE */
|
|
/* can not be allocated. */
|
|
/* TargetHandle is invalid or is for an item */
|
|
/* in another list. */
|
|
/* If this routine fails, an error code is returned*/
|
|
/* and any memory allocated by this function is */
|
|
/* freed. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The item to add is copied to the heap to */
|
|
/* avoid possible conflicts with the usage of */
|
|
/* local variables in functions which process */
|
|
/* dlist_ts. However, a pointer to a local variable */
|
|
/* should not be appended to the dlist_t. */
|
|
/* */
|
|
/* It is assumed that TargetHandle is valid, or is at least*/
|
|
/* the address of an accessible block of storage. If */
|
|
/* TargetHandle is invalid, or is not the address of an */
|
|
/* accessible block of storage, then a trap or exception */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int InsertItem (dlist_t ListToAddTo,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS TargetHandle,
|
|
Insertion_Modes Insert_Mode,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Handle);
|
|
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: InsertObject */
|
|
/* */
|
|
/* Descriptive Name: This function inserts an object into a */
|
|
/* dlist_t. The object can be inserted before */
|
|
/* or after the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToAddTo : The list to which the */
|
|
/* data object is to be */
|
|
/* inserted. */
|
|
/* uint ItemSize : The size of the data item, in */
|
|
/* bytes. */
|
|
/* ADDRESS ItemLocation : The address of the data */
|
|
/* to append to the list */
|
|
/* TAG ItemTag : The item tag to associate with */
|
|
/* the item being appended to the */
|
|
/* list */
|
|
/* ADDRESS TargetHandle : The item in ListToAddTo which */
|
|
/* is used to determine where */
|
|
/* the item being transferred will */
|
|
/* be placed. If this is NULL, */
|
|
/* then the current item in */
|
|
/* ListToAddTo will be used. */
|
|
/* Insertion_Modes Insert_Mode : This indicates where, */
|
|
/* relative to the item in */
|
|
/* ListToAddTo specified by */
|
|
/* Target_Handle, the item being */
|
|
/* inserted can be placed. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
|
|
/* into ListToAddTo becomes the */
|
|
/* current item in ListToAddTo. */
|
|
/* ADDRESS * Handle : The address of a variable to hold */
|
|
/* the handle for the item that was */
|
|
/* inserted into the list. */
|
|
/* */
|
|
/* Output: If all went well, the return value will be */
|
|
/* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
|
|
/* the new item. If errors were encountered, the . */
|
|
/* return value will be the error code and *Handle will */
|
|
/* be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToAddTo does not point to a valid */
|
|
/* list */
|
|
/* ItemSize is 0 */
|
|
/* ItemLocation is NULL */
|
|
/* The memory required for a LINK NODE can not */
|
|
/* be allocated. */
|
|
/* TargetHandle is invalid or is for an item */
|
|
/* in another list. */
|
|
/* If this routine fails, an error code is returned*/
|
|
/* and any memory allocated by this function is */
|
|
/* freed. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The item to insert is NOT copied to the heap. Instead, */
|
|
/* the location of the item is stored in the list. This */
|
|
/* is the major difference between InsertObject and */
|
|
/* InsertItem. InsertItem allocates memory on the heap, */
|
|
/* copies the item to the memory it allocated, and stores */
|
|
/* the address of the memory it allocated in the list. */
|
|
/* InsertObject stores the address provided by the user. */
|
|
/* */
|
|
/* It is assumed that TargetHandle is valid, or is at least*/
|
|
/* the address of an accessible block of storage. If */
|
|
/* TargetHandle is invalid, or is not the address of an */
|
|
/* accessible block of storage, then a trap or exception */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int InsertObject (dlist_t ListToAddTo,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS TargetHandle,
|
|
Insertion_Modes Insert_Mode,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Handle);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ExclusiveInsertObject */
|
|
/* */
|
|
/* Descriptive Name: This function inserts an object into a */
|
|
/* dlist_t. The object can be inserted before */
|
|
/* or after the current item in the list. If */
|
|
/* object is already in the list, it is not */
|
|
/* added again. */
|
|
/* */
|
|
/* Input: dlist_t ListToAddTo : The list to which the */
|
|
/* data object is to be */
|
|
/* inserted. */
|
|
/* uint ItemSize : The size of the data item, in */
|
|
/* bytes. */
|
|
/* ADDRESS ItemLocation : The address of the data */
|
|
/* to append to the list */
|
|
/* TAG ItemTag : The item tag to associate with */
|
|
/* the item being appended to the */
|
|
/* list */
|
|
/* ADDRESS TargetHandle : The item in ListToAddTo which */
|
|
/* is used to determine where */
|
|
/* the item being transferred will */
|
|
/* be placed. If this is NULL, */
|
|
/* then the current item in */
|
|
/* ListToAddTo will be used. */
|
|
/* Insertion_Modes Insert_Mode : This indicates where, */
|
|
/* relative to the item in */
|
|
/* ListToAddTo specified by */
|
|
/* Target_Handle, the item being */
|
|
/* inserted can be placed. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
|
|
/* into ListToAddTo becomes the */
|
|
/* current item in ListToAddTo. */
|
|
/* ADDRESS * Handle : The address of a variable to hold */
|
|
/* the handle for the item that was */
|
|
/* inserted into the list. */
|
|
/* */
|
|
/* Output: If all went well, the return value will be */
|
|
/* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
|
|
/* the new item. If errors were encountered, the . */
|
|
/* return value will be the error code and *Handle will */
|
|
/* be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToAddTo does not point to a valid */
|
|
/* list */
|
|
/* ItemSize is 0 */
|
|
/* ItemLocation is NULL */
|
|
/* The memory required for a LINK NODE can not */
|
|
/* be allocated. */
|
|
/* TargetHandle is invalid or is for an item */
|
|
/* in another list. */
|
|
/* If this routine fails, an error code is returned*/
|
|
/* and any memory allocated by this function is */
|
|
/* freed. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The item to insert is NOT copied to the heap. Instead, */
|
|
/* the location of the item is stored in the list. This */
|
|
/* is the major difference between InsertObject and */
|
|
/* InsertItem. InsertItem allocates memory on the heap, */
|
|
/* copies the item to the memory it allocated, and stores */
|
|
/* the address of the memory it allocated in the list. */
|
|
/* InsertObject stores the address provided by the user. */
|
|
/* */
|
|
/* It is assumed that TargetHandle is valid, or is at least*/
|
|
/* the address of an accessible block of storage. If */
|
|
/* TargetHandle is invalid, or is not the address of an */
|
|
/* accessible block of storage, then a trap or exception */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ExclusiveInsertObject (dlist_t ListToAddTo,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS TargetHandle,
|
|
Insertion_Modes Insert_Mode,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Handle);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: DeleteItem */
|
|
/* */
|
|
/* Descriptive Name: This function removes the specified item from*/
|
|
/* the list and optionally frees the memory */
|
|
/* associated with it. */
|
|
/* */
|
|
/* Input: dlist_t ListToDeleteFrom : The list whose current */
|
|
/* item is to be deleted. */
|
|
/* BOOLEAN FreeMemory : If TRUE, then the memory */
|
|
/* associated with the current */
|
|
/* item will be freed. If FALSE */
|
|
/* then the current item will be */
|
|
/* removed from the list but its */
|
|
/* memory will not be freed. */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToDeleteFrom, or NULL. If */
|
|
/* NULL is used, then the current item */
|
|
/* in ListToDeleteFrom will be deleted. */
|
|
/* */
|
|
/* Output: Return DLIST_SUCCESS if successful, else an error code.*/
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToDeleteFrom is */
|
|
/* not a valid list, or if ListToDeleteFrom is */
|
|
/* empty, or if Handle is invalid. */
|
|
/* If this routine fails, an error code is */
|
|
/* returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: Items in a list can be accessed in two ways: A copy of */
|
|
/* the item can be obtained using GetItem and its related */
|
|
/* calls, or a pointer to the item can be obtained using */
|
|
/* GetObject and its related calls. If you have a copy of */
|
|
/* the data and wish to remove the item from the list, set */
|
|
/* FreeMemory to TRUE. This will remove the item from the */
|
|
/* list and deallocate the memory used to hold it. If you */
|
|
/* have a pointer to the item in the list (from one of the */
|
|
/* GetObject style functions) and wish to remove the item */
|
|
/* from the list, set FreeMemory to FALSE. This removes */
|
|
/* the item from the list without freeing its memory, so */
|
|
/* that the pointer obtained with the GetObject style */
|
|
/* functions is still useable. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list, unless the handle specified belongs */
|
|
/* to the current item in the list, in which case this */
|
|
/* function behaves the same as DeleteItem. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int DeleteItem (dlist_t ListToDeleteFrom,
|
|
BOOLEAN FreeMemory,
|
|
ADDRESS Handle);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: DeleteAllItems */
|
|
/* */
|
|
/* Descriptive Name: This function deletes all of the items in the*/
|
|
/* specified list and optionally frees the */
|
|
/* memory associated with each item deleted. */
|
|
/* */
|
|
/* Input: dlist_t ListToDeleteFrom : The list whose items */
|
|
/* are to be deleted. */
|
|
/* BOOLEAN FreeMemory : If TRUE, then the memory */
|
|
/* associated with each item in the*/
|
|
/* list will be freed. If FALSE */
|
|
/* then the each item will be */
|
|
/* removed from the list but its */
|
|
/* memory will not be freed. */
|
|
/* */
|
|
/* Output: Return DLIST_SUCCESS if successful, else an error code.*/
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToDeleteFrom is */
|
|
/* not a valid list, or if ListToDeleteFrom is */
|
|
/* empty. */
|
|
/* If this routine fails, an error code is */
|
|
/* returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: Items in a list can be accessed in two ways: A copy of */
|
|
/* the item can be obtained using GetItem and its related */
|
|
/* calls, or a pointer to the item can be obtained using */
|
|
/* GetObject and its related calls. If you have a copy of */
|
|
/* the data and wish to remove the item from the list, set */
|
|
/* FreeMemory to TRUE. This will remove the item from the */
|
|
/* list and deallocate the memory used to hold it. If you */
|
|
/* have a pointer to the item in the list (from one of the */
|
|
/* GetObject style functions) and wish to remove the item */
|
|
/* from the list, set FreeMemory to FALSE. This removes */
|
|
/* the item from the list without freeing its memory, so */
|
|
/* that the pointer obtained with the GetObject style */
|
|
/* functions is still useable. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int DeleteAllItems (dlist_t ListToDeleteFrom,
|
|
BOOLEAN FreeMemory);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: DeleteObject */
|
|
/* */
|
|
/* Descriptive Name: This function removes the specified object */
|
|
/* from the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToDeleteFrom : The list whose current */
|
|
/* item is to be deleted. */
|
|
/* ADDRESS Object : The address of the object to be removed*/
|
|
/* from the list. */
|
|
/* */
|
|
/* Output: Return DLIST_SUCCESS if successful, else an error code.*/
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToDeleteFrom is */
|
|
/* not a valid list, or if ListToDeleteFrom is */
|
|
/* empty, or if Handle is invalid. */
|
|
/* If this routine fails, an error code is */
|
|
/* returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: This function does not alter which item is the current */
|
|
/* item in the list, unless the handle specified belongs */
|
|
/* to the current item in the list, in which case this */
|
|
/* function behaves the same as DeleteItem. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int DeleteObject (dlist_t ListToDeleteFrom,
|
|
ADDRESS Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetItem */
|
|
/* */
|
|
/* Descriptive Name: This function copies the specified item in */
|
|
/* the list to a buffer provided by the caller. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* ADDRESS ItemLocation : This is the location of the */
|
|
/* buffer into which the current*/
|
|
/* item is to be copied. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the list*/
|
|
/* will be used. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item to get will */
|
|
/* become the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* The buffer at ItemLocation will contain a copy of */
|
|
/* the current item from ListToGetItemFrom. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemLocation is NULL */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle corresponding to the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetItem( dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS Handle,
|
|
BOOLEAN MakeCurrent);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetNextItem */
|
|
/* */
|
|
/* Descriptive Name: This function advances the current item */
|
|
/* pointer and then copies the current item in */
|
|
/* the list to a buffer provided by the caller. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* ADDRESS ItemLocation : This is the location of the */
|
|
/* buffer into which the current*/
|
|
/* item is to be copied. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* The buffer at ItemLocation will contain a copy of */
|
|
/* the current item from ListToGetItemFrom. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* The current item pointer will NOT be advanced. */
|
|
/* The current item in the list will be the same */
|
|
/* as before the call to this function. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemLocation is NULL */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* The current item in the list before this */
|
|
/* function is called is the last item */
|
|
/* item in the list. */
|
|
/* If any of these conditions occur, an error */
|
|
/* code will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetNextItem(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetPreviousItem */
|
|
/* */
|
|
/* Descriptive Name: This function makes the previous item in the */
|
|
/* list the current item in the list and then */
|
|
/* copies that item to a buffer provided by the */
|
|
/* user. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* ADDRESS ItemLocation : This is the location of the */
|
|
/* buffer into which the current */
|
|
/* item is to be copied. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* The buffer at ItemLocation will contain a copy of */
|
|
/* the current item from ListToGetItemFrom. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* The current item pointer will NOT be advanced. */
|
|
/* The current item in the list will be the same */
|
|
/* as before the call to this function. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemLocation is NULL */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* The current item in the list before this */
|
|
/* function is called is the last item */
|
|
/* item in the list. */
|
|
/* If any of these conditions occur, an error */
|
|
/* code will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* this assumption is violated, an exception or trap may */
|
|
/* occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetPreviousItem(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetObject */
|
|
/* */
|
|
/* Descriptive Name: This function returns the address of the data*/
|
|
/* associated with the specified item in the */
|
|
/* list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to have its address */
|
|
/* returned to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the list*/
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item to get will */
|
|
/* become the current item in the */
|
|
/* list. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the current item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user should not free the memory associated with */
|
|
/* the address returned by this function as the object is */
|
|
/* still in the list. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle designating the current item in the list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetObject(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
TAG ItemTag,
|
|
ADDRESS Handle,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: BlindGetObject */
|
|
/* */
|
|
/* Descriptive Name: This function returns the address of the data*/
|
|
/* associated with the specified item in the */
|
|
/* list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current */
|
|
/* item is to have its address */
|
|
/* returned to the caller. */
|
|
/* uint * ItemSize : The size of the current item */
|
|
/* TAG * ItemTag : The tag of the current item */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the list*/
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item to get will */
|
|
/* become the current item in the */
|
|
/* list. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the current item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user should not free the memory associated with */
|
|
/* the address returned by this function as the object is */
|
|
/* still in the list. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle designating the current item in the list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int BlindGetObject(dlist_t ListToGetItemFrom,
|
|
uint * ItemSize,
|
|
TAG * ItemTag,
|
|
ADDRESS Handle,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetNextObject */
|
|
/* */
|
|
/* Descriptive Name: This function advances the current item */
|
|
/* pointer and then returns the address of the */
|
|
/* data associated with the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the next item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* The current item pointer will NOT be advanced. */
|
|
/* The current item in the list will be the same */
|
|
/* as before the call to this function. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* The current item in the list before this */
|
|
/* function is called is the last item */
|
|
/* item in the list. */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user should not free the memory associated with */
|
|
/* the address returned by this function as the object is */
|
|
/* still in the list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetNextObject(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
TAG ItemTag,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetPreviousObject */
|
|
/* */
|
|
/* Descriptive Name: This function makes the previous item in the */
|
|
/* list the current item and then returns the */
|
|
/* address of the data associated with the */
|
|
/* current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the previous item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* The current item pointer will NOT be advanced. */
|
|
/* The current item in the list will be the same */
|
|
/* as before the call to this function. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* The current item in the list before this */
|
|
/* function is called is the last item */
|
|
/* item in the list. */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user should not free the memory associated with */
|
|
/* the address returned by this function as the object is */
|
|
/* still in the list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetPreviousObject(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
TAG ItemTag,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ExtractItem */
|
|
/* */
|
|
/* Descriptive Name: This function copies the specified item in */
|
|
/* the list to a buffer provided by the caller */
|
|
/* and removes the item from the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* ADDRESS ItemLocation : This is the location of the */
|
|
/* buffer into which the current*/
|
|
/* item is to be copied. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the list*/
|
|
/* will be used. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* The buffer at ItemLocation will contain a copy of */
|
|
/* the current item from ListToGetItemFrom. */
|
|
/* The item will have been removed from the list and */
|
|
/* its memory deallocated. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemLocation is NULL */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, *Error will */
|
|
/* contain a non-zero error code. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* these assumptions are violated, an exception or trap */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle which refers to the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list, unless the handle specified belongs */
|
|
/* to the current item in the list, in which case the */
|
|
/* item following the current item becomes the current */
|
|
/* item in the list. If there is no item following the */
|
|
/* current item in the list, then the item preceding the */
|
|
/* current item will become the current item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ExtractItem(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS Handle);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ExtractObject */
|
|
/* */
|
|
/* Descriptive Name: This function returns the address of the data*/
|
|
/* associated with the specified item in the */
|
|
/* list and then removes that item from the list*/
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current item */
|
|
/* is to be copied and returned*/
|
|
/* to the caller. */
|
|
/* uint ItemSize : What the caller thinks the size of*/
|
|
/* the current item is. */
|
|
/* TAG ItemTag : What the caller thinks the item tag */
|
|
/* of the current item is. */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the */
|
|
/* list will be used. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the current item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user is responsible for the memory associated with */
|
|
/* the address returned by this function since this */
|
|
/* function removes that object from the list. This means */
|
|
/* that, when the user is through with the object, they */
|
|
/* should free it. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle which refers to the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list, unless the handle specified belongs */
|
|
/* to the current item in the list, in which case the */
|
|
/* item following the current item becomes the current */
|
|
/* item in the list. If there is no item following the */
|
|
/* current item in the list, then the item preceding the */
|
|
/* current item will become the current item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ExtractObject(dlist_t ListToGetItemFrom,
|
|
uint ItemSize,
|
|
TAG ItemTag,
|
|
ADDRESS Handle,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: BlindExtractObject */
|
|
/* */
|
|
/* Descriptive Name: This function returns the address of the data*/
|
|
/* associated with the specified item in the */
|
|
/* list and then removes that item from the list*/
|
|
/* */
|
|
/* Input: dlist_t ListToGetItemFrom : The list whose current */
|
|
/* item is to be copied and */
|
|
/* returned to the caller. */
|
|
/* uint * ItemSize : The size of the current item */
|
|
/* TAG * ItemTag : The tag of the current item */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides*/
|
|
/* in ListToGetItemFrom, or NULL. If */
|
|
/* NULL, then the current item in the */
|
|
/* list will be used. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of data associated */
|
|
/* with the current item. */
|
|
/* */
|
|
/* Output: If Successful : */
|
|
/* Return DLIST_SUCCESS. */
|
|
/* *Object will be the address of the data */
|
|
/* associated with the current item in the list. */
|
|
/* If Failure : */
|
|
/* Return an error code. */
|
|
/* *Object will be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under any of the */
|
|
/* following conditions: */
|
|
/* ListToGetItemFrom is not a valid list */
|
|
/* ItemSize does not match the size of the */
|
|
/* current item in the list */
|
|
/* ItemTag does not match the item tag */
|
|
/* of the current item in the list */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occur, an error code */
|
|
/* will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user is responsible for the memory associated with */
|
|
/* the address returned by this function since this */
|
|
/* function removes that object from the list. This means */
|
|
/* that, when the user is through with the object, they */
|
|
/* should free it. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is considered a valid */
|
|
/* handle which refers to the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list, unless the handle specified belongs */
|
|
/* to the current item in the list, in which case the */
|
|
/* item following the current item becomes the current */
|
|
/* item in the list. If there is no item following the */
|
|
/* current item in the list, then the item preceding the */
|
|
/* current item will become the current item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int BlindExtractObject(dlist_t ListToGetItemFrom,
|
|
uint * ItemSize,
|
|
TAG * ItemTag,
|
|
ADDRESS Handle,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ReplaceItem */
|
|
/* */
|
|
/* Descriptive Name: This function replaces the specified item in */
|
|
/* the list with the one provided as its */
|
|
/* argument. */
|
|
/* */
|
|
/* Input: dlist_t ListToReplaceItemIn : The list whose current item*/
|
|
/* is to be replaced */
|
|
/* uint ItemSize : The size, in bytes, of the */
|
|
/* replacement item */
|
|
/* ADDRESS ItemLocation : The address of the replacement */
|
|
/* item */
|
|
/* TAG ItemTag : The item tag that the user wishes to */
|
|
/* associate with the replacement item */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides */
|
|
/* in ListToGetItemFrom, or NULL. If NULL */
|
|
/* then the current item in the list will */
|
|
/* used. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item to get will */
|
|
/* become the current item in the */
|
|
/* list. */
|
|
/* */
|
|
/* Output: If Successful then return DLIST_SUCCESS. */
|
|
/* If Unsuccessful, then return an error code. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToReplaceItemIn is empty */
|
|
/* ItemSize is 0 */
|
|
/* ItemLocation is NULL */
|
|
/* The memory required can not be allocated. */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occurs, an error */
|
|
/* code will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* these assumptions are violated, an exception or trap */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is a valid handle which */
|
|
/* refers to the current item in the list. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ReplaceItem(dlist_t ListToReplaceItemIn,
|
|
uint ItemSize,
|
|
ADDRESS ItemLocation,
|
|
TAG ItemTag,
|
|
ADDRESS Handle,
|
|
BOOLEAN MakeCurrent);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ReplaceObject */
|
|
/* */
|
|
/* Descriptive Name: This function replaces the specified object */
|
|
/* in the list with the one provided as its */
|
|
/* argument. */
|
|
/* */
|
|
/* Input: dlist_t ListToReplaceItemIn : The list whose current */
|
|
/* object is to be replaced */
|
|
/* uint ItemSize : The size, in bytes, of the */
|
|
/* replacement object */
|
|
/* ADDRESS ItemLocation : The address of the replacement */
|
|
/* item */
|
|
/* TAG ItemTag : The item tag that the user wishes to */
|
|
/* associate with the replacement item */
|
|
/* ADDRESS Handle : The handle of the item to get. This */
|
|
/* handle must be of an item which resides */
|
|
/* in ListToGetItemFrom, or NULL. If NULL */
|
|
/* then the current item in the list will */
|
|
/* be used. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item to get will */
|
|
/* become the current item in the */
|
|
/* list. */
|
|
/* ADDRESS * Object : The address of a variable to hold */
|
|
/* the ADDRESS of the object that */
|
|
/* was replaced. */
|
|
/* */
|
|
/* Output: If Successful then return DLIST_SUCCESS and the */
|
|
/* *Object will contain the address of the object that */
|
|
/* was replaced. */
|
|
/* If Unsuccessful, then return an error code and */
|
|
/* *Object will be NULL. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToReplaceItemIn is empty */
|
|
/* ItemSize is 0 */
|
|
/* ItemLocation is NULL */
|
|
/* The memory required can not be allocated. */
|
|
/* Handle is invalid, or is for an item */
|
|
/* which is not in ListToGetItemFrom */
|
|
/* If any of these conditions occurs, an error */
|
|
/* code will be returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The user is responsible for the memory associated with */
|
|
/* the object returned by this function as that object is */
|
|
/* removed from the list. This means that, when the user */
|
|
/* is through with the object returned by this function, */
|
|
/* they should free it. */
|
|
/* */
|
|
/* It is assumed that if ItemLocation is not NULL, then */
|
|
/* it is a valid address that can be dereferenced. If */
|
|
/* these assumptions are violated, an exception or trap */
|
|
/* may occur. */
|
|
/* */
|
|
/* It is assumed that Handle is valid, or is at least the */
|
|
/* address of an accessible block of storage. If Handle */
|
|
/* is invalid, or is not the address of an accessible block*/
|
|
/* of storage, then a trap or exception may occur. */
|
|
/* NOTE: For this function, NULL is a valid handle for the */
|
|
/* current item in the list. */
|
|
/* */
|
|
/* It is assumed that Object is a valid address. If not, */
|
|
/* an exception or trap may occur. */
|
|
/* */
|
|
/* This function does not alter which item is the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ReplaceObject(dlist_t ListToReplaceItemIn,
|
|
uint * ItemSize, /* On input - size of new object. On return = size of old object. */
|
|
ADDRESS ItemLocation,
|
|
TAG * ItemTag, /* On input - TAG of new object. On return = TAG of old object. */
|
|
ADDRESS Handle,
|
|
BOOLEAN MakeCurrent,
|
|
ADDRESS * Object);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetTag */
|
|
/* */
|
|
/* Descriptive Name: This function returns the item tag associated*/
|
|
/* with the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetTagFrom : The list from which the item */
|
|
/* tag of the current item is to*/
|
|
/* be returned */
|
|
/* ADDRESS Handle : The handle of the item whose TAG and */
|
|
/* size we are to get. This handle must */
|
|
/* be of an item which resides in */
|
|
/* in ListToGetTagFrom, or NULL. If NULL */
|
|
/* then the current item in the list will */
|
|
/* be used. */
|
|
/* uint * ItemSize : The size, in bytes, of the */
|
|
/* current item in the list. */
|
|
/* TAG * Tag : The address of a variable to hold */
|
|
/* the returned tag. */
|
|
/* */
|
|
/* Output: If successful, the function returns DLIST_SUCCESS. */
|
|
/* *ItemSize contains the size of the item. *Tag */
|
|
/* contains the tag. */
|
|
/* If unsuccessful, an error code is returned. */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToGetTagFrom is */
|
|
/* not a valid list or is an empty list. In either*/
|
|
/* of these cases, an error code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetTag(dlist_t ListToGetTagFrom,
|
|
ADDRESS Handle,
|
|
uint * ItemSize,
|
|
TAG * Tag);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetHandle */
|
|
/* */
|
|
/* Descriptive Name: This function returns a handle for the */
|
|
/* current item in the list. This handle is */
|
|
/* then associated with that item regardless of */
|
|
/* its position in the list. This handle can be*/
|
|
/* used to make its associated item the current */
|
|
/* item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetHandleFrom : The list from which a */
|
|
/* handle is needed. */
|
|
/* ADDRESS * Handle : The address of a variable to hold */
|
|
/* the handle */
|
|
/* */
|
|
/* Output: If successful, the function returns DLIST_SUCCESS and */
|
|
/* *Handle is set to the handle for the current item */
|
|
/* in ListToGetHandleFrom. */
|
|
/* If unsuccessful, an error code is returned and *Handle */
|
|
/* is set to 0. */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToGetHandleFrom */
|
|
/* is not a valid list or is an empty list. In */
|
|
/* either of these cases, an error code is */
|
|
/* returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: The handle returned is a pointer to the LinkNode of the */
|
|
/* current item in the list. This allows the item to move */
|
|
/* around in the list without losing its associated handle.*/
|
|
/* However, if the item is deleted from the list, then the */
|
|
/* handle is invalid and its use could result in a trap. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetHandle (dlist_t ListToGetHandleFrom,
|
|
ADDRESS * Handle);
|
|
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GetListSize */
|
|
/* */
|
|
/* Descriptive Name: This function returns the number of items in */
|
|
/* a list. */
|
|
/* */
|
|
/* Input: dlist_t ListToGetSizeOf : The list whose size we wish to*/
|
|
/* know */
|
|
/* uint * Size : The address of a variable to hold */
|
|
/* the size of the list. */
|
|
/* */
|
|
/* Output: If successful, the function returns DLIST_SUCCESS and */
|
|
/* *Size contains the a count of the number of items */
|
|
/* in the list. */
|
|
/* If unsuccessful, an error code is returned and *Size */
|
|
/* is set to 0. */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToGetSizeOf is */
|
|
/* not a valid list. If this happens, then an */
|
|
/* error code is returned. . */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that Size contains a valid address. If */
|
|
/* this assumption is violated, an exception or trap */
|
|
/* may occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GetListSize(dlist_t ListToGetSizeOf,
|
|
uint * Size);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ListEmpty */
|
|
/* */
|
|
/* Descriptive Name: This function returns TRUE if the */
|
|
/* specified list is empty, otherwise it returns*/
|
|
/* FALSE. */
|
|
/* */
|
|
/* Input: dlist_t ListToCheck : The list to check to see if it*/
|
|
/* is empty */
|
|
/* */
|
|
/* Output: If successful, the function returns TRUE if the */
|
|
/* number of items in the list is 0, otherwise it */
|
|
/* returns FALSE. */
|
|
/* If unsuccessful, the function returns TRUE. */
|
|
/* */
|
|
/* Error Handling: This function will return TRUE if ListToCheck */
|
|
/* is not a valid list. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
BOOLEAN ListEmpty(dlist_t ListToCheck);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: AtEndOfList */
|
|
/* */
|
|
/* Descriptive Name: This function returns TRUE if the */
|
|
/* current item in the list is the last item */
|
|
/* in the list. Returns FALSE otherwise. */
|
|
/* */
|
|
/* Input: dlist_t ListToCheck : The list to check. */
|
|
/* */
|
|
/* Output: If successful, the function returns TRUE if the */
|
|
/* current item in the list is the last item in the */
|
|
/* list. If it is not the last item in the list, */
|
|
/* FALSE is returned. */
|
|
/* If unsuccessful, the function returns FALSE. */
|
|
/* */
|
|
/* Error Handling: This function will return FALSE ListToCheck is */
|
|
/* not a valid list. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
BOOLEAN AtEndOfList(dlist_t ListToCheck);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: AtStartOfList */
|
|
/* */
|
|
/* Descriptive Name: This function returns TRUE if the */
|
|
/* current item in the list is the first item */
|
|
/* in the list. Returns FALSE otherwise. */
|
|
/* */
|
|
/* Input: dlist_t ListToCheck : The list to check. */
|
|
/* */
|
|
/* Output: If successful, the function returns TRUE if the */
|
|
/* current item in the list is the first item in the */
|
|
/* list. If it is not the first item in the list, */
|
|
/* FALSE is returned. */
|
|
/* If unsuccessful, the function returns FALSE */
|
|
/* */
|
|
/* Error Handling: This function will return FALSE if ListToCheck */
|
|
/* is not a valid list. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
BOOLEAN AtStartOfList(dlist_t ListToCheck);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: DestroyList */
|
|
/* */
|
|
/* Descriptive Name: This function releases the memory associated */
|
|
/* with the internal data structures of a */
|
|
/* dlist_t. Once a dlist_t has been destroyed */
|
|
/* by this function, it must be reinitialized */
|
|
/* before it can be used again. */
|
|
/* */
|
|
/* Input: dlist_t ListToDestroy : The list to be eliminated */
|
|
/* from memory. */
|
|
/* BOOLEAN FreeItemMemory : If TRUE, all items in the list */
|
|
/* will be freed. If FALSE, all */
|
|
/* items in the list are not */
|
|
/* freed, only the list structures*/
|
|
/* associated with them are. */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS */
|
|
/* If unsuccessful, return an error code. */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToDestroy is not */
|
|
/* a valid list. If this happens, then an error */
|
|
/* code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: If FreeItemMemory is TRUE, then this function will try */
|
|
/* to delete any items which may be in the list. However, */
|
|
/* since this function has no way of knowing the internal */
|
|
/* structure of an item, items which contain embedded */
|
|
/* pointers will not be entirely freed. This can lead to */
|
|
/* memory leaks. The programmer should ensure that any */
|
|
/* list passed to this function when the FreeItemMemory */
|
|
/* parameter is TRUE is empty or does not contain any */
|
|
/* items with embedded pointers. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int DestroyList(dlist_t * ListToDestroy,
|
|
BOOLEAN FreeItemMemory);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: NextItem */
|
|
/* */
|
|
/* Descriptive Name: This function makes the next item in the list*/
|
|
/* the current item in the list (i.e. it */
|
|
/* advances the current item pointer). */
|
|
/* */
|
|
/* Input: dlist_t ListToAdvance : The list whose current item */
|
|
/* pointer is to be advanced */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return error code. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToAdvance is not a valid list */
|
|
/* ListToAdvance is empty */
|
|
/* The current item is the last item in the */
|
|
/* list */
|
|
/* If any of these conditions occurs, then an */
|
|
/* error code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int NextItem(dlist_t ListToAdvance);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: PreviousItem */
|
|
/* */
|
|
/* Descriptive Name: This function makes the previous item in the */
|
|
/* list the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToChange : The list whose current item */
|
|
/* pointer is to be changed */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code. */
|
|
/* */
|
|
/* Error Handling: This function will fail under the following */
|
|
/* conditions: */
|
|
/* ListToChange is not a valid list */
|
|
/* ListToChange is empty */
|
|
/* The current item is the first item in the */
|
|
/* list */
|
|
/* If any of these conditions occurs, then return */
|
|
/* an error code. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int PreviousItem(dlist_t ListToChange);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GoToStartOfList */
|
|
/* */
|
|
/* Descriptive Name: This function makes the first item in the */
|
|
/* list the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToReset : The list whose current item */
|
|
/* is to be set to the first */
|
|
/* item in the list */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToAdvance is not */
|
|
/* a valid list. If this occurs, then an error */
|
|
/* code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GoToStartOfList(dlist_t ListToReset);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GoToEndOfList */
|
|
/* */
|
|
/* Descriptive Name: This function makes the last item in the */
|
|
/* list the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToSet : The list whose current item */
|
|
/* is to be set to the last item */
|
|
/* in the list */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToAdvance is not */
|
|
/* a valid list. If this occurs, then an error */
|
|
/* code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GoToEndOfList(dlist_t ListToSet);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: GoToSpecifiedItem */
|
|
/* */
|
|
/* Descriptive Name: This function makes the item associated with */
|
|
/* Handle the current item in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToReposition: The list whose current item */
|
|
/* is to be set to the item */
|
|
/* associated with Handle. */
|
|
/* ADDRESS Handle : A handle obtained by using the */
|
|
/* GetHandle function. This handle */
|
|
/* identifies a unique item in the list. */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code */
|
|
/* */
|
|
/* Error Handling: This function will fail if ListToAdvance is not */
|
|
/* a valid list. If this occurs, then an error */
|
|
/* code is returned. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: It is assumed that Handle is a valid handle and that */
|
|
/* the item associated with Handle is still in the list. */
|
|
/* If these conditions are not met, an exception or trap */
|
|
/* may occur. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int GoToSpecifiedItem(dlist_t ListToReposition,
|
|
ADDRESS Handle);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: SortList */
|
|
/* */
|
|
/* Descriptive Name: This function sorts the contents of a list. */
|
|
/* The sorting algorithm used is a stable sort */
|
|
/* whose performance is not dependent upon the */
|
|
/* initial order of the items in the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToSort : The dlist_t that is to be sorted. */
|
|
/* */
|
|
/* int (*Compare) ( ... ) */
|
|
/* */
|
|
/* This is a pointer to a function that can compare any */
|
|
/* two items in the list. It should return -1 if */
|
|
/* Object1 is less than Object2, 0 if Object1 is equal */
|
|
/* to Object2, and 1 if Object1 is greater than Object2.*/
|
|
/* This function will be called during the sort whenever*/
|
|
/* the sorting algorithm needs to compare two objects. */
|
|
/* */
|
|
/* The Compare function takes the following parameters: */
|
|
/* */
|
|
/* ADDRESS Object1 : The address of the data for the */
|
|
/* first object to be compared. */
|
|
/* TAG Object1Tag : The user assigned TAG value for the */
|
|
/* first object to be compared. */
|
|
/* ADDRESS Object2 : The address of the data for the */
|
|
/* second object to be compared. */
|
|
/* TAG Object2Tag : The user assigned TAG value for the */
|
|
/* second object to be compared. */
|
|
/* uint * Error : The address of a variable to hold the */
|
|
/* error return value. */
|
|
/* */
|
|
/* If this function ever sets *Error to a non-zero value*/
|
|
/* the sort will terminate and the error code will be */
|
|
/* returned to the caller of the SortList function. */
|
|
/* */
|
|
/* */
|
|
/* Output: If successful, this function will return DLIST_SUCCESS */
|
|
/* and ListToSort will have been sorted. */
|
|
/* If unsuccessful, an error code will be returned. */
|
|
/* The order of the items in ListToSort is undefined */
|
|
/* and may have changed. */
|
|
/* */
|
|
/* Error Handling: This function will terminate if *Compare sets */
|
|
/* *Error to a non-zero value, or if ListToSort */
|
|
/* is invalid. If this function does terminate in */
|
|
/* the middle of a sort, the order of the items in */
|
|
/* ListToSort may be different than it was before */
|
|
/* the function was called. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: This function works by breaking the list into sublists */
|
|
/* and merging the sublists back into one list. The size */
|
|
/* of the sublists starts at 1, and with each pass, the */
|
|
/* of the sublists is doubled. The sort ends when the size*/
|
|
/* of a sublist is greater than the size of the original */
|
|
/* list. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int SortList(dlist_t ListToSort,
|
|
int (*Compare) (ADDRESS Object1,
|
|
TAG Object1Tag,
|
|
ADDRESS Object2,
|
|
TAG Object2Tag,
|
|
uint * Error));
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: ForEachItem */
|
|
/* */
|
|
/* Descriptive Name: This function passes a pointer to each item */
|
|
/* in a list to a user provided function for */
|
|
/* processing by the user provided function. */
|
|
/* */
|
|
/* Input: dlist_t ListToProcess : The dlist_t whose items are to */
|
|
/* be processed by the user */
|
|
/* provided function. */
|
|
/* */
|
|
/* int (*ProcessItem) (...) */
|
|
/* */
|
|
/* This is a pointer to the user provided function. */
|
|
/* This user provided function takes the following */
|
|
/* parameters: */
|
|
/* */
|
|
/* ADDRESS Object : A pointer to an item in */
|
|
/* ListToProcess. */
|
|
/* TAG Object1Tag : The user assigned TAG value for */
|
|
/* the item pointed to by Object. */
|
|
/* ADDRESS Parameter : The address of a block of */
|
|
/* memory containing any */
|
|
/* parameters that the user */
|
|
/* wishes to have passed to this*/
|
|
/* function. */
|
|
/* */
|
|
/* ADDRESS Parameters : This field is passed through to */
|
|
/* *ProcessItem. This function does */
|
|
/* not even look at the contents of */
|
|
/* this field. This field is here to */
|
|
/* provide the user a way to pass */
|
|
/* additional data to *ProcessItem */
|
|
/* that *ProcessItem may need to */
|
|
/* function correctly. */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code. */
|
|
/* */
|
|
/* Error Handling: This function aborts immediately when an error */
|
|
/* is detected, and any remaining items in the list*/
|
|
/* will not be processed. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: This function allows the user to access all of the items */
|
|
/* in a list and perform an operation on them. The */
|
|
/* operation performed must not free any items in the list, */
|
|
/* or perform any list operations on the list being */
|
|
/* processed. */
|
|
/* */
|
|
/* As an example of when this would be useful, consider a */
|
|
/* a list of graphic objects (rectangles, triangles, circles*/
|
|
/* etc.) which comprise a drawing. To draw the picture */
|
|
/* that these graphic objects represent, one could build a */
|
|
/* loop which gets and draws each item. Another way to */
|
|
/* do this would be to build a drawing function which can */
|
|
/* draw any of the graphic objects, and then use that */
|
|
/* function as the ProcessItem function in a call to */
|
|
/* ForEachItem. */
|
|
/* */
|
|
/* If the ProcessItem function returns an error code */
|
|
/* other than DLIST_SUCCESS, then ForEachItem will terminate*/
|
|
/* and return an error to whoever called it. The single */
|
|
/* exception to this is if ProcessItem returns */
|
|
/* DLIST_SEARCH_COMPLETE, in which case ForEachItem */
|
|
/* terminates and returns DLIST_SUCCESS. This is */
|
|
/* useful for using ForEachItem to search a list and then */
|
|
/* terminating the search once the desired item is found. */
|
|
/* */
|
|
/* A word about the Parameters parameter. This parameter */
|
|
/* is passed through to *ProcessItem and is never looked at */
|
|
/* by this function. This means that the user can put any */
|
|
/* value they desire into Parameters as long as it is the */
|
|
/* same size (in bytes) as Parameters. The intended use of */
|
|
/* Parameters is to allow the user to pass information to */
|
|
/* *ProcessItem that *ProcessItem may need. Either way, */
|
|
/* how Parameters is used is literally up to the user. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int ForEachItem(dlist_t ListToProcess,
|
|
int (*ProcessItem) (ADDRESS Object,
|
|
TAG ObjectTag,
|
|
uint ObjectSize,
|
|
ADDRESS ObjectHandle,
|
|
ADDRESS Parameters),
|
|
ADDRESS Parameters,
|
|
BOOLEAN Forward);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: PruneList */
|
|
/* */
|
|
/* Descriptive Name: This function allows the caller to examine */
|
|
/* each item in a list and optionally delete */
|
|
/* it from the list. */
|
|
/* */
|
|
/* Input: dlist_t ListToProcess : The dlist_t to be pruned. */
|
|
/* */
|
|
/* BOOLEAN (*KillItem) (...) */
|
|
/* */
|
|
/* This is a pointer to a user provided function. */
|
|
/* This user provided function takes the following */
|
|
/* parameters: */
|
|
/* */
|
|
/* ADDRESS Object : A pointer to an item in */
|
|
/* ListToProcess. */
|
|
/* TAG Object1Tag : The user assigned TAG value for */
|
|
/* the item pointed to by Object. */
|
|
/* ADDRESS Parameter : The address of a block of */
|
|
/* memory containing any */
|
|
/* parameters that the user */
|
|
/* wishes to have passed to this*/
|
|
/* function. */
|
|
/* BOOLEAN * FreeMemory : The address of a BOOLEAN */
|
|
/* variable which this */
|
|
/* function will set to */
|
|
/* either TRUE or FALSE. */
|
|
/* If the function return */
|
|
/* value is TRUE, then the */
|
|
/* value in *FreeMemory will */
|
|
/* be examined. If it is */
|
|
/* TRUE, then PruneList will */
|
|
/* free the memory associated*/
|
|
/* with the item being */
|
|
/* deleted. If *FreeMemory */
|
|
/* is FALSE, then the item */
|
|
/* being removed from the */
|
|
/* dlist_t will not be freed,*/
|
|
/* and it is up to the user */
|
|
/* to ensure that this memory*/
|
|
/* is handled properly. */
|
|
/* uint * Error : The address of a variable to*/
|
|
/* hold the error return value.*/
|
|
/* */
|
|
/* ADDRESS Parameters : This field is passed through to */
|
|
/* *KillItem. This function does */
|
|
/* not even look at the contents of */
|
|
/* this field. This field is here to */
|
|
/* provide the user a way to pass */
|
|
/* additional data to *ProcessItem */
|
|
/* that *ProcessItem may need to */
|
|
/* function correctly. */
|
|
/* */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* If unsuccessful, return an error code. */
|
|
/* */
|
|
/* Error Handling: This function aborts immediately when an error */
|
|
/* is detected, and any remaining items in the list*/
|
|
/* will not be processed. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: This function allows the user to access all of the items */
|
|
/* in a list, perform an operation on them, and then */
|
|
/* optionally delete ("remove") them from the dlist_t. The */
|
|
/* operation performed must not free any items in the list, */
|
|
/* or perform any list operations on the list being */
|
|
/* processed. */
|
|
/* */
|
|
/* If the KillItem function sets *Error to something other */
|
|
/* than DLIST_SUCCESS, then PruneList will terminate and */
|
|
/* return an error to whoever called it. The single */
|
|
/* exception to this is if KillItem sets *Error to */
|
|
/* DLIST_SEARCH_COMPLETE, in which case KillItem */
|
|
/* terminates and sets *Error to DLIST_SUCCESS. This is */
|
|
/* useful for using KillItem to search a list and then */
|
|
/* terminating the search once the desired item is found. */
|
|
/* */
|
|
/* A word about the Parameters parameter. This parameter */
|
|
/* is passed through to *ProcessItem and is never looked at */
|
|
/* by this function. This means that the user can put any */
|
|
/* value they desire into Parameters as long as it is the */
|
|
/* same size (in bytes) as Parameters. The intended use of */
|
|
/* Parameters is to allow the user to pass information to */
|
|
/* *ProcessItem that *ProcessItem may need. Either way, */
|
|
/* how Parameters is used is literally up to the user. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int PruneList(dlist_t ListToProcess,
|
|
BOOLEAN (*KillItem) (ADDRESS Object,
|
|
TAG ObjectTag,
|
|
uint ObjectSize,
|
|
ADDRESS ObjectHandle,
|
|
ADDRESS Parameters,
|
|
BOOLEAN * FreeMemory,
|
|
uint * Error),
|
|
ADDRESS Parameters);
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: AppendList */
|
|
/* */
|
|
/* Descriptive Name: Removes the items in SourceList and appends */
|
|
/* them to TargetList. */
|
|
/* */
|
|
/* Input: dlist_t TargetList : The dlist_t which is to have the */
|
|
/* items from SourceList appended to */
|
|
/* it. */
|
|
/* dlist_t SourceList : The dlist_t whose items are to be */
|
|
/* removed and appended to TargetList.*/
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* SourceList will be empty, and TargetList will contain*/
|
|
/* all of its original items and all of the items that */
|
|
/* were in SourceList. */
|
|
/* If unsuccessful, return an error code. SourceList and */
|
|
/* TargetList will be unmodified. */
|
|
/* */
|
|
/* Error Handling: This function will abort immediately upon */
|
|
/* detection of an error. All errors that can be */
|
|
/* detected are detected before the contents of */
|
|
/* SourceList are appended to TargetList, so if an*/
|
|
/* error is detected and the function aborts, */
|
|
/* SourceList and TargetList are unaltered. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int AppendList(dlist_t TargetList,
|
|
dlist_t SourceList);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: TransferItem */
|
|
/* */
|
|
/* Descriptive Name: Removes an item in SourceList and places in */
|
|
/* TargetList. */
|
|
/* */
|
|
/* Input: dlist_t SourceList : The dlist_t containing the item */
|
|
/* which is to be transferred. */
|
|
/* ADDRESS SourceHandle : The handle of the item in */
|
|
/* SourceList which is to be */
|
|
/* transferred to another dlist_t. */
|
|
/* If this is NULL, then the */
|
|
/* current item in SourceList will */
|
|
/* be used. */
|
|
/* dlist_t TargetList : The dlist_t which is to receive the*/
|
|
/* item being transferred. */
|
|
/* ADDRESS TargetHandle : The item in TargetList which */
|
|
/* is used to determine where */
|
|
/* the item being transferred will */
|
|
/* be placed. If this is NULL, */
|
|
/* then the current item in */
|
|
/* TargetList will be used. */
|
|
/* Insertion_Modes TransferMode : This indicates where, */
|
|
/* relative to the item in */
|
|
/* TargetList specified by */
|
|
/* Target_Handle, the item being */
|
|
/* transferred can be placed. */
|
|
/* BOOLEAN MakeCurrent : If TRUE, the item transferred to */
|
|
/* TargetList becomes the current */
|
|
/* item in TargetList. */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS, SourceList will be */
|
|
/* empty, and TargetList will contain all of its */
|
|
/* original items and all of the items that were in */
|
|
/* SourceList. */
|
|
/* If unsuccessful, an error code will be returned and */
|
|
/* SourceList and TargetList will be unmodified. */
|
|
/* */
|
|
/* Error Handling: This function will abort immediately upon */
|
|
/* detection of an error. All errors that can be */
|
|
/* detected are detected before the contents of */
|
|
/* SourceList are appended to TargetList, so if an*/
|
|
/* error is detected and the function aborts, */
|
|
/* SourceList and TargetList are unaltered. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int TransferItem(dlist_t SourceList,
|
|
ADDRESS SourceHandle,
|
|
dlist_t TargetList,
|
|
ADDRESS TargetHandle,
|
|
Insertion_Modes TransferMode,
|
|
BOOLEAN MakeCurrent);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: CopyList */
|
|
/* */
|
|
/* Descriptive Name: Copies the items in SourceList to the */
|
|
/* TargetList. */
|
|
/* */
|
|
/* Input: dlist_t TargetList : The dlist_t which is to have the */
|
|
/* items from SourceList copied to it.*/
|
|
/* dlist_t SourceList : The dlist_t whose items are to be */
|
|
/* copied to TargetList. */
|
|
/* */
|
|
/* Output: If successful, return DLIST_SUCCESS. */
|
|
/* SourceList will be unchanged and TargetList will */
|
|
/* contain all of its original items and all of the */
|
|
/* items that were in SourceList. */
|
|
/* If unsuccessful, return an error code. SourceList and */
|
|
/* TargetList will be unmodified. */
|
|
/* */
|
|
/* Error Handling: This function will abort immediately upon */
|
|
/* detection of an error. All errors that can be */
|
|
/* detected are detected before the contents of */
|
|
/* SourceList are appended to TargetList, so if an*/
|
|
/* error is detected and the function aborts, */
|
|
/* SourceList and TargetList are unaltered. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
int CopyList(dlist_t TargetList,
|
|
dlist_t SourceList,
|
|
Insertion_Modes Insert_Mode);
|
|
|
|
|
|
/*********************************************************************/
|
|
/* */
|
|
/* Function Name: CheckListIntegrity */
|
|
/* */
|
|
/* Descriptive Name: Checks the integrity of a dlist_t. All link */
|
|
/* nodes in the list are checked, as are all */
|
|
/* fields in the list control block. */
|
|
/* */
|
|
/* Input: dlist_t ListToCheck - The list whose integrity is to be */
|
|
/* checked. */
|
|
/* */
|
|
/* Output: The function return value will be TRUE if all of the */
|
|
/* elements in the dlist_t are correct. If this function */
|
|
/* returns FALSE, then the dlist_t being checked has been */
|
|
/* corrupted! */
|
|
/* */
|
|
/* Error Handling: If this function encounters an error in a */
|
|
/* dlist_t, it will return FALSE. */
|
|
/* */
|
|
/* Side Effects: None. */
|
|
/* */
|
|
/* Notes: None. */
|
|
/* */
|
|
/*********************************************************************/
|
|
BOOLEAN CheckListIntegrity(dlist_t ListToCheck);
|
|
|
|
|
|
#endif
|
|
|
|
|