/*** glist.h - Definitions for Generic List Manager
*
* Microsoft Confidential
* Copyright (C) Microsoft Corporation 1994
* All Rights Reserved.
*
* Author:
* Benjamin W. Slivka
*
* History:
* 05-Apr-1994 bens Initial version
* 06-Apr-1994 bens Renamed from function manager
* 11-Apr-1994 bens Add pszDesc
* 22-Apr-1994 bens Add GLFindNext, GLSetValue, GLGetValue
*
* Exported Functions:
*/
#ifndef INCLUDED_GLIST
#define INCLUDED_GLIST 1
#include "types.h"
#include "asrt.h"
#include "error.h"
/*** ERRGLIST_Xxxx - GLIST error codes
*
*/
#define ERRGLIST_BASE 0x0100
#define ERRGLIST_NOT_UNIQUE (ERRGLIST_BASE+1)
typedef void * HGENLIST; /* hglist - generic list */
typedef void * HGENERIC; /* hgen - generic item handle */
/*** PFNGLDESTROYVALUE - Function type to destroy HGENERIC values
/*** FNGLDESTROYVALUE - Macro to help define PFNGLDESTROYVALUE functions
*
* Entry:
* pv - Value to destroy
*
* Exit:
* Value is destroyed.
*/
typedef void (*PFNGLDESTROYVALUE)(void *pv); /* pfngldv */
#define FNGLDESTROYVALUE(fn) void fn(void *pv)
/*** PFNGLDUPLICATEVALUE - Function type to duplicate HGENERIC values
/*** FNGLDUPLICATEVALUE - Macro to help define PFNGLDUPLICATEVALUE functions
*
* Entry:
* pv - Value to duplicate
*
* Exit:
* Returns duplicated value.
*/
typedef void * (*PFNGLDUPLICATEVALUE)(void *pv); /* pfngldup */
#define FNGLDUPLICATEVALUE(fn) void * fn(void *pv)
/*** GLAdd - Add an item to a list
*
* Entry:
* hglist - List to augment
* pszKey - Item key value (may be NULL)
* pv - Item value
* pszDesc - Item description (for error messages)
* fUnique - TRUE => Key must not already exist; FALSE => dups allowed
* perr - ERROR structure
*
* Exit-Success:
* Returns hgen, item is added to list
*
* Exit-Failure:
* Returns NULL, cannot add item to list
* ERROR structure filled in with details of error:
* perr->code == ERRGLIST_NOT_UNIQUE
* fUnique was TRUE, and pszKey already existed.
* perr->pv = HGENERIC of already existing item;
* Otherwise, some other error (out of memory, etc.)
*/
HGENERIC GLAdd(HGENLIST hglist,
char *pszKey,
void *pv,
char *pszDesc,
BOOL fUnique,
PERROR perr);
/*** GLDelete - Delete item from a list
*
* Entry:
* hgen - Item handle
*
* Exit-Success:
* Always works, since hgen is assumed to be valid.
*/
void GLDelete(HGENERIC hgen);
/*** GLCreateList - Create a list of
*
* Entry:
* pv - Item value for *default* item (NULL if not supplied)
* pfngldv - Function used to destroy values (NULL if not needed)
* pszDesc - Item description (for error messages)
* perr - ERROR structure
*
* Exit-Success:
* Returns hgenlist; list is created.
*
* Exit-Failure:
* Returns NULL, cannot create list; perror filled in with error.
*/
HGENLIST GLCreateList(void *pv,
PFNGLDESTROYVALUE pfngldv,
char *pszDesc,
PERROR perr);
/*** GLCopyToList - Copy items from one list to another
*
* Entry:
* phglistDst - Pointer to list to receive copy of items from hglistSrc
* (list is created if necessary).
* hglistSrc - Source list for copy (if NULL, *phglistDst is not
* modified, and this function returns immediately).
* pfngldup - Function used to dupliate item values (NULL if not needed)
* pszDesc - Item description (for error messages)
* perr - ERROR structure
*
* Exit-Success:
* Returns TRUE; hglistDst created if necessary, and items copied from
* hglistSrc to hglistDst;
*
* Exit-Failure:
* Returns FALSE; perror filled in with error.
*
* NOTES:
* If an item with the same key exists in both hglistSrc and hglistDst,
* then the item is *not* copied to hglistDst.
*/
BOOL GLCopyToList(HGENLIST *phglistDst,
HGENLIST hglistSrc,
PFNGLDUPLICATEVALUE pfngldup,
char *pszDesc,
PERROR perr);
/*** GLDestroyList - Destroy a list
*
* Entry:
* hglist - List to destroy
*
* Exit-Success:
* Always works, since hglist is assumed to be valid.
*/
void GLDestroyList(HGENLIST hglist);
/*** GLFind - Search for item in list
*
* Entry:
* hglist - Generic list
* pszKey - Key to look for (case-insensitive search)
* pszDesc - Item description (for error messages)
* perr - ERROR structure
*
* Exit-Success:
* Returns hgen, if item exists.
*
* Exit-Failure:
* Returns NULL, item does not exist; ERROR structure filled.
*/
HGENERIC GLFind(HGENLIST hglist,
char *pszKey,
char *pszDesc,
PERROR perr);
/*** GLFindNext - Search for next item in list
*
* Entry:
* hgen - Start search at *next* item after this item
* pszKey - Key to look for (case-insensitive search)
*
* Exit-Success:
* Returns hgen, if item exists.
*
* Exit-Failure:
* Returns NULL, item does not exist;
*/
HGENERIC GLFindNext(HGENERIC hgen,
char *pszKey);
/*** GLFirstItem - Get first item from a list
*
* Entry:
* hglist - List
*
* Exit-Success:
* Returns HGENERIC of first item in list.
*
* Exit-Failure:
* Returns NULL; hglist is bad or empty.
*/
HGENERIC GLFirstItem(HGENLIST hglist);
/*** GLNextItem - Get next item
*
* Entry:
* hgen - Item handle
*
* Exit-Success:
* Returns HGENERIC of next item following hgen in list.
*
* Exit-Failure:
* Returns NULL; no more items, or hgen is bad.
*/
HGENERIC GLNextItem(HGENERIC hgen);
/*** GLPreviousItem - Get previous item
*
* Entry:
* hgen - Item handle
*
* Exit-Success:
* Returns HGENERIC of item immediately preceding hgen.
*
* Exit-Failure:
* Returns NULL; no more items, or hgen is bad.
*/
HGENERIC GLPreviousItem(HGENERIC hgen);
/*** GLGetKey - Get the item key
*
* Entry:
* hgen - Item handle
*
* Exit:
* Returns pointer to item key (will be NULL if GLAdd() received NULL)
*/
char *GLGetKey(HGENERIC hgen);
/*** GLGetValue - Get the item value for a particular item
*
* Entry:
* hgen - Item handle
*
* Exit:
* Returns value of item;
*/
void *GLGetValue(HGENERIC hgen);
/*** GLSetValue - Set the item value for a particular item
*
* Entry:
* hgen - Item handle
* pv - Item value
*
* Exit:
* None.
*/
void GLSetValue(HGENERIC hgen, void *pv);
/*** GLFindAndGetValue - Get the item value for a particular item
*
* Entry:
* hglist - Generic list (may be NULL, in which case returns NULL)
* pszKey - Key to look for (case-insensitive search);
* Pass NULL to get default value;
*
* Exit-Success:
* Returns value of item if key exists.
* If the key was not found, but a default value was supplied on the
* GLGLCreateList() call, then that default value is returned.
*
* Exit-Failure:
* Returns NULL, item does not exist (key not found and no default
* value was supplied on the GLCreateList() call).
*/
void *GLFindAndGetValue(HGENLIST hglist,
char *pszKey);
#endif // INCLUDED_GLIST
