1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
/*** 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
|
