OLD | NEW |
| (Empty) |
1 /* This Source Code Form is subject to the terms of the Mozilla Public | |
2 * License, v. 2.0. If a copy of the MPL was not distributed with this | |
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | |
4 | |
5 #ifndef BASE_H | |
6 #define BASE_H | |
7 | |
8 /* | |
9 * base.h | |
10 * | |
11 * This header file contains basic prototypes and preprocessor | |
12 * definitions used throughout nss but not available publicly. | |
13 */ | |
14 | |
15 #ifndef BASET_H | |
16 #include "baset.h" | |
17 #endif /* BASET_H */ | |
18 | |
19 #ifndef NSSBASE_H | |
20 #include "nssbase.h" | |
21 #endif /* NSSBASE_H */ | |
22 | |
23 #include "plhash.h" | |
24 | |
25 PR_BEGIN_EXTERN_C | |
26 | |
27 /* | |
28 * NSSArena | |
29 * | |
30 * The nonpublic methods relating to this type are: | |
31 * | |
32 * nssArena_Create -- constructor | |
33 * nssArena_Destroy | |
34 * nssArena_Mark | |
35 * nssArena_Release | |
36 * nssArena_Unmark | |
37 * | |
38 * nss_ZAlloc | |
39 * nss_ZFreeIf | |
40 * nss_ZRealloc | |
41 * | |
42 * Additionally, there are some preprocessor macros: | |
43 * | |
44 * nss_ZNEW | |
45 * nss_ZNEWARRAY | |
46 * | |
47 * In debug builds, the following calls are available: | |
48 * | |
49 * nssArena_verifyPointer | |
50 * nssArena_registerDestructor | |
51 * nssArena_deregisterDestructor | |
52 * | |
53 * The following preprocessor macro is also always available: | |
54 * | |
55 * nssArena_VERIFYPOINTER | |
56 * | |
57 * A constant PLHashAllocOps structure is available for users | |
58 * of the NSPL PLHashTable routines. | |
59 * | |
60 * nssArenaHashAllocOps | |
61 */ | |
62 | |
63 /* | |
64 * nssArena_Create | |
65 * | |
66 * This routine creates a new memory arena. This routine may return | |
67 * NULL upon error, in which case it will have set an error on the | |
68 * error stack. | |
69 * | |
70 * The error may be one of the following values: | |
71 * NSS_ERROR_NO_MEMORY | |
72 * | |
73 * Return value: | |
74 * NULL upon error | |
75 * A pointer to an NSSArena upon success | |
76 */ | |
77 | |
78 /* | |
79 * XXX fgmr | |
80 * Arenas can be named upon creation; this is mostly of use when | |
81 * debugging. Should we expose that here, allowing an optional | |
82 * "const char *name" argument? Should the public version of this | |
83 * call (NSSArena_Create) have it too? | |
84 */ | |
85 | |
86 NSS_EXTERN NSSArena *nssArena_Create(void); | |
87 | |
88 extern const NSSError NSS_ERROR_NO_MEMORY; | |
89 | |
90 /* | |
91 * nssArena_Destroy | |
92 * | |
93 * This routine will destroy the specified arena, freeing all memory | |
94 * allocated from it. This routine returns a PRStatus value; if | |
95 * successful, it will return PR_SUCCESS. If unsuccessful, it will | |
96 * set an error on the error stack and return PR_FAILURE. | |
97 * | |
98 * The error may be one of the following values: | |
99 * NSS_ERROR_INVALID_ARENA | |
100 * | |
101 * Return value: | |
102 * PR_SUCCESS | |
103 * PR_FAILURE | |
104 */ | |
105 | |
106 NSS_EXTERN PRStatus nssArena_Destroy(NSSArena *arena); | |
107 | |
108 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
109 | |
110 /* | |
111 * nssArena_Mark | |
112 * | |
113 * This routine "marks" the current state of an arena. Space | |
114 * allocated after the arena has been marked can be freed by | |
115 * releasing the arena back to the mark with nssArena_Release, | |
116 * or committed by calling nssArena_Unmark. When successful, | |
117 * this routine returns a valid nssArenaMark pointer. This | |
118 * routine may return NULL upon error, in which case it will | |
119 * have set an error on the error stack. | |
120 * | |
121 * The error may be one of the following values: | |
122 * NSS_ERROR_INVALID_ARENA | |
123 * NSS_ERROR_NO_MEMORY | |
124 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
125 * | |
126 * Return value: | |
127 * NULL upon failure | |
128 * An nssArenaMark pointer upon success | |
129 */ | |
130 | |
131 NSS_EXTERN nssArenaMark *nssArena_Mark(NSSArena *arena); | |
132 | |
133 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
134 extern const NSSError NSS_ERROR_NO_MEMORY; | |
135 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; | |
136 | |
137 /* | |
138 * nssArena_Release | |
139 * | |
140 * This routine invalidates and releases all memory allocated from | |
141 * the specified arena after the point at which the specified mark | |
142 * was obtained. This routine returns a PRStatus value; if successful, | |
143 * it will return PR_SUCCESS. If unsuccessful, it will set an error | |
144 * on the error stack and return PR_FAILURE. | |
145 * | |
146 * The error may be one of the following values: | |
147 * NSS_ERROR_INVALID_ARENA | |
148 * NSS_ERROR_INVALID_ARENA_MARK | |
149 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
150 * | |
151 * Return value: | |
152 * PR_SUCCESS | |
153 * PR_FAILURE | |
154 */ | |
155 | |
156 NSS_EXTERN PRStatus nssArena_Release(NSSArena *arena, nssArenaMark *arenaMark); | |
157 | |
158 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
159 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK; | |
160 | |
161 /* | |
162 * nssArena_Unmark | |
163 * | |
164 * This routine "commits" the indicated mark and any marks after | |
165 * it, making them unreleasable. Note that any earlier marks can | |
166 * still be released, and such a release will invalidate these | |
167 * later unmarked regions. If an arena is to be safely shared by | |
168 * more than one thread, all marks must be either released or | |
169 * unmarked. This routine returns a PRStatus value; if successful, | |
170 * it will return PR_SUCCESS. If unsuccessful, it will set an error | |
171 * on the error stack and return PR_FAILURE. | |
172 * | |
173 * The error may be one of the following values: | |
174 * NSS_ERROR_INVALID_ARENA | |
175 * NSS_ERROR_INVALID_ARENA_MARK | |
176 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
177 * | |
178 * Return value: | |
179 * PR_SUCCESS | |
180 * PR_FAILURE | |
181 */ | |
182 | |
183 NSS_EXTERN PRStatus nssArena_Unmark(NSSArena *arena, nssArenaMark *arenaMark); | |
184 | |
185 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
186 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK; | |
187 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; | |
188 | |
189 #ifdef ARENA_DESTRUCTOR_LIST | |
190 | |
191 /* | |
192 * nssArena_registerDestructor | |
193 * | |
194 * This routine stores a pointer to a callback and an arbitrary | |
195 * pointer-sized argument in the arena, at the current point in | |
196 * the mark stack. If the arena is destroyed, or an "earlier" | |
197 * mark is released, then this destructor will be called at that | |
198 * time. Note that the destructor will be called with the arena | |
199 * locked, which means the destructor may free memory in that | |
200 * arena, but it may not allocate or cause to be allocated any | |
201 * memory. This callback facility was included to support our | |
202 * debug-version pointer-tracker feature; overuse runs counter to | |
203 * the the original intent of arenas. This routine returns a | |
204 * PRStatus value; if successful, it will return PR_SUCCESS. If | |
205 * unsuccessful, it will set an error on the error stack and | |
206 * return PR_FAILURE. | |
207 * | |
208 * The error may be one of the following values: | |
209 * NSS_ERROR_INVALID_ARENA | |
210 * NSS_ERROR_NO_MEMORY | |
211 * | |
212 * Return value: | |
213 * PR_SUCCESS | |
214 * PR_FAILURE | |
215 */ | |
216 | |
217 NSS_EXTERN PRStatus nssArena_registerDestructor( | |
218 NSSArena *arena, void (*destructor)(void *argument), void *arg); | |
219 | |
220 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
221 extern const NSSError NSS_ERROR_NO_MEMORY; | |
222 | |
223 /* | |
224 * nssArena_deregisterDestructor | |
225 * | |
226 * This routine will remove the first destructor in the specified | |
227 * arena which has the specified destructor and argument values. | |
228 * The destructor will not be called. This routine returns a | |
229 * PRStatus value; if successful, it will return PR_SUCCESS. If | |
230 * unsuccessful, it will set an error on the error stack and | |
231 * return PR_FAILURE. | |
232 * | |
233 * The error may be one of the following values: | |
234 * NSS_ERROR_INVALID_ARENA | |
235 * NSS_ERROR_NOT_FOUND | |
236 * | |
237 * Return value: | |
238 * PR_SUCCESS | |
239 * PR_FAILURE | |
240 */ | |
241 | |
242 NSS_EXTERN PRStatus nssArena_deregisterDestructor( | |
243 NSSArena *arena, void (*destructor)(void *argument), void *arg); | |
244 | |
245 extern const NSSError NSS_ERROR_INVALID_ITEM; | |
246 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
247 extern const NSSError NSS_ERROR_NOT_FOUND; | |
248 | |
249 #endif /* ARENA_DESTRUCTOR_LIST */ | |
250 | |
251 /* | |
252 * nss_ZAlloc | |
253 * | |
254 * This routine allocates and zeroes a section of memory of the | |
255 * size, and returns to the caller a pointer to that memory. If | |
256 * the optional arena argument is non-null, the memory will be | |
257 * obtained from that arena; otherwise, the memory will be obtained | |
258 * from the heap. This routine may return NULL upon error, in | |
259 * which case it will have set an error upon the error stack. The | |
260 * value specified for size may be zero; in which case a valid | |
261 * zero-length block of memory will be allocated. This block may | |
262 * be expanded by calling nss_ZRealloc. | |
263 * | |
264 * The error may be one of the following values: | |
265 * NSS_ERROR_INVALID_ARENA | |
266 * NSS_ERROR_NO_MEMORY | |
267 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
268 * | |
269 * Return value: | |
270 * NULL upon error | |
271 * A pointer to the new segment of zeroed memory | |
272 */ | |
273 | |
274 NSS_EXTERN void *nss_ZAlloc(NSSArena *arenaOpt, PRUint32 size); | |
275 | |
276 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
277 extern const NSSError NSS_ERROR_NO_MEMORY; | |
278 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; | |
279 | |
280 /* | |
281 * nss_ZFreeIf | |
282 * | |
283 * If the specified pointer is non-null, then the region of memory | |
284 * to which it points -- which must have been allocated with | |
285 * nss_ZAlloc -- will be zeroed and released. This routine | |
286 * returns a PRStatus value; if successful, it will return PR_SUCCESS. | |
287 * If unsuccessful, it will set an error on the error stack and return | |
288 * PR_FAILURE. | |
289 * | |
290 * The error may be one of the following values: | |
291 * NSS_ERROR_INVALID_POINTER | |
292 * | |
293 * Return value: | |
294 * PR_SUCCESS | |
295 * PR_FAILURE | |
296 */ | |
297 | |
298 NSS_EXTERN PRStatus nss_ZFreeIf(void *pointer); | |
299 | |
300 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
301 | |
302 /* | |
303 * nss_ZRealloc | |
304 * | |
305 * This routine reallocates a block of memory obtained by calling | |
306 * nss_ZAlloc or nss_ZRealloc. The portion of memory | |
307 * between the new and old sizes -- which is either being newly | |
308 * obtained or released -- is in either case zeroed. This routine | |
309 * may return NULL upon failure, in which case it will have placed | |
310 * an error on the error stack. | |
311 * | |
312 * The error may be one of the following values: | |
313 * NSS_ERROR_INVALID_POINTER | |
314 * NSS_ERROR_NO_MEMORY | |
315 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
316 * | |
317 * Return value: | |
318 * NULL upon error | |
319 * A pointer to the replacement segment of memory | |
320 */ | |
321 | |
322 NSS_EXTERN void *nss_ZRealloc(void *pointer, PRUint32 newSize); | |
323 | |
324 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
325 extern const NSSError NSS_ERROR_NO_MEMORY; | |
326 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD; | |
327 | |
328 /* | |
329 * nss_ZNEW | |
330 * | |
331 * This preprocessor macro will allocate memory for a new object | |
332 * of the specified type with nss_ZAlloc, and will cast the | |
333 * return value appropriately. If the optional arena argument is | |
334 * non-null, the memory will be obtained from that arena; otherwise, | |
335 * the memory will be obtained from the heap. This routine may | |
336 * return NULL upon error, in which case it will have set an error | |
337 * upon the error stack. | |
338 * | |
339 * The error may be one of the following values: | |
340 * NSS_ERROR_INVALID_ARENA | |
341 * NSS_ERROR_NO_MEMORY | |
342 * | |
343 * Return value: | |
344 * NULL upon error | |
345 * A pointer to the new segment of zeroed memory | |
346 */ | |
347 | |
348 #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type))) | |
349 | |
350 /* | |
351 * nss_ZNEWARRAY | |
352 * | |
353 * This preprocessor macro will allocate memory for an array of | |
354 * new objects, and will cast the return value appropriately. | |
355 * If the optional arena argument is non-null, the memory will | |
356 * be obtained from that arena; otherwise, the memory will be | |
357 * obtained from the heap. This routine may return NULL upon | |
358 * error, in which case it will have set an error upon the error | |
359 * stack. The array size may be specified as zero. | |
360 * | |
361 * The error may be one of the following values: | |
362 * NSS_ERROR_INVALID_ARENA | |
363 * NSS_ERROR_NO_MEMORY | |
364 * | |
365 * Return value: | |
366 * NULL upon error | |
367 * A pointer to the new segment of zeroed memory | |
368 */ | |
369 | |
370 #define nss_ZNEWARRAY(arenaOpt, type, quantity) \ | |
371 ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity))) | |
372 | |
373 /* | |
374 * nss_ZREALLOCARRAY | |
375 * | |
376 * This preprocessor macro will reallocate memory for an array of | |
377 * new objects, and will cast the return value appropriately. | |
378 * This routine may return NULL upon error, in which case it will | |
379 * have set an error upon the error stack. | |
380 * | |
381 * The error may be one of the following values: | |
382 * NSS_ERROR_INVALID_POINTER | |
383 * NSS_ERROR_NO_MEMORY | |
384 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | |
385 * | |
386 * Return value: | |
387 * NULL upon error | |
388 * A pointer to the replacement segment of memory | |
389 */ | |
390 #define nss_ZREALLOCARRAY(p, type, quantity) \ | |
391 ((type *)nss_ZRealloc((p), sizeof(type) * (quantity))) | |
392 | |
393 /* | |
394 * nssArena_verifyPointer | |
395 * | |
396 * This method is only present in debug builds. | |
397 * | |
398 * If the specified pointer is a valid pointer to an NSSArena object, | |
399 * this routine will return PR_SUCCESS. Otherwise, it will put an | |
400 * error on the error stack and return PR_FAILURE. | |
401 * | |
402 * The error may be one of the following values: | |
403 * NSS_ERROR_INVALID_ARENA | |
404 * | |
405 * Return value: | |
406 * PR_SUCCESS if the pointer is valid | |
407 * PR_FAILURE if it isn't | |
408 */ | |
409 | |
410 #ifdef DEBUG | |
411 NSS_EXTERN PRStatus nssArena_verifyPointer(const NSSArena *arena); | |
412 | |
413 extern const NSSError NSS_ERROR_INVALID_ARENA; | |
414 #endif /* DEBUG */ | |
415 | |
416 /* | |
417 * nssArena_VERIFYPOINTER | |
418 * | |
419 * This macro is always available. In debug builds it will call | |
420 * nssArena_verifyPointer; in non-debug builds, it will merely | |
421 * check that the pointer is not null. Note that in non-debug | |
422 * builds it cannot place an error on the error stack. | |
423 * | |
424 * Return value: | |
425 * PR_SUCCESS if the pointer is valid | |
426 * PR_FAILURE if it isn't | |
427 */ | |
428 | |
429 #ifdef DEBUG | |
430 #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p) | |
431 #else /* DEBUG */ | |
432 | |
433 #define nssArena_VERIFYPOINTER(p) \ | |
434 (((NSSArena *)NULL == (p)) ? PR_FAILURE : PR_SUCCESS) | |
435 #endif /* DEBUG */ | |
436 | |
437 /* | |
438 * Private function to be called by NSS_Shutdown to cleanup nssArena | |
439 * bookkeeping. | |
440 */ | |
441 extern PRStatus nssArena_Shutdown(void); | |
442 | |
443 /* | |
444 * nssArenaHashAllocOps | |
445 * | |
446 * This constant structure contains allocation callbacks designed for | |
447 * use with the NSPL routine PL_NewHashTable. For example: | |
448 * | |
449 * NSSArena *hashTableArena = nssArena_Create(); | |
450 * PLHashTable *t = PL_NewHashTable(n, hasher, key_compare, | |
451 * value_compare, nssArenaHashAllocOps, hashTableArena); | |
452 */ | |
453 | |
454 NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps; | |
455 | |
456 /* | |
457 * The error stack | |
458 * | |
459 * The nonpublic methods relating to the error stack are: | |
460 * | |
461 * nss_SetError | |
462 * nss_ClearErrorStack | |
463 */ | |
464 | |
465 /* | |
466 * nss_SetError | |
467 * | |
468 * This routine places a new error code on the top of the calling | |
469 * thread's error stack. Calling this routine wiht an error code | |
470 * of zero will clear the error stack. | |
471 */ | |
472 | |
473 NSS_EXTERN void nss_SetError(PRUint32 error); | |
474 | |
475 /* | |
476 * nss_ClearErrorStack | |
477 * | |
478 * This routine clears the calling thread's error stack. | |
479 */ | |
480 | |
481 NSS_EXTERN void nss_ClearErrorStack(void); | |
482 | |
483 /* | |
484 * nss_DestroyErrorStack | |
485 * | |
486 * This routine frees the calling thread's error stack. | |
487 */ | |
488 | |
489 NSS_EXTERN void nss_DestroyErrorStack(void); | |
490 | |
491 /* | |
492 * NSSItem | |
493 * | |
494 * nssItem_Create | |
495 * nssItem_Duplicate | |
496 * nssItem_Equal | |
497 */ | |
498 | |
499 NSS_EXTERN NSSItem *nssItem_Create(NSSArena *arenaOpt, NSSItem *rvOpt, | |
500 PRUint32 length, const void *data); | |
501 | |
502 NSS_EXTERN void nssItem_Destroy(NSSItem *item); | |
503 | |
504 NSS_EXTERN NSSItem *nssItem_Duplicate(NSSItem *obj, NSSArena *arenaOpt, | |
505 NSSItem *rvOpt); | |
506 | |
507 NSS_EXTERN PRBool nssItem_Equal(const NSSItem *one, const NSSItem *two, | |
508 PRStatus *statusOpt); | |
509 | |
510 /* | |
511 * NSSUTF8 | |
512 * | |
513 * nssUTF8_CaseIgnoreMatch | |
514 * nssUTF8_Duplicate | |
515 * nssUTF8_Size | |
516 * nssUTF8_Length | |
517 * nssUTF8_CopyIntoFixedBuffer | |
518 */ | |
519 | |
520 /* | |
521 * nssUTF8_CaseIgnoreMatch | |
522 * | |
523 * Returns true if the two UTF8-encoded strings pointed to by the | |
524 * two specified NSSUTF8 pointers differ only in typcase. | |
525 * | |
526 * The error may be one of the following values: | |
527 * NSS_ERROR_INVALID_POINTER | |
528 * | |
529 * Return value: | |
530 * PR_TRUE if the strings match, ignoring case | |
531 * PR_FALSE if they don't | |
532 * PR_FALSE upon error | |
533 */ | |
534 | |
535 NSS_EXTERN PRBool nssUTF8_CaseIgnoreMatch(const NSSUTF8 *a, const NSSUTF8 *b, | |
536 PRStatus *statusOpt); | |
537 | |
538 /* | |
539 * nssUTF8_Duplicate | |
540 * | |
541 * This routine duplicates the UTF8-encoded string pointed to by the | |
542 * specified NSSUTF8 pointer. If the optional arenaOpt argument is | |
543 * not null, the memory required will be obtained from that arena; | |
544 * otherwise, the memory required will be obtained from the heap. | |
545 * A pointer to the new string will be returned. In case of error, | |
546 * an error will be placed on the error stack and NULL will be | |
547 * returned. | |
548 * | |
549 * The error may be one of the following values: | |
550 * NSS_ERROR_INVALID_POINTER | |
551 * NSS_ERROR_INVALID_ARENA | |
552 * NSS_ERROR_NO_MEMORY | |
553 */ | |
554 | |
555 NSS_EXTERN NSSUTF8 *nssUTF8_Duplicate(const NSSUTF8 *s, NSSArena *arenaOpt); | |
556 | |
557 /* | |
558 * nssUTF8_PrintableMatch | |
559 * | |
560 * Returns true if the two Printable strings pointed to by the | |
561 * two specified NSSUTF8 pointers match when compared with the | |
562 * rules for Printable String (leading and trailing spaces are | |
563 * disregarded, extents of whitespace match irregardless of length, | |
564 * and case is not significant), then PR_TRUE will be returned. | |
565 * Otherwise, PR_FALSE will be returned. Upon failure, PR_FALSE | |
566 * will be returned. If the optional statusOpt argument is not | |
567 * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that | |
568 * location. | |
569 * | |
570 * The error may be one of the following values: | |
571 * NSS_ERROR_INVALID_POINTER | |
572 * | |
573 * Return value: | |
574 * PR_TRUE if the strings match, ignoring case | |
575 * PR_FALSE if they don't | |
576 * PR_FALSE upon error | |
577 */ | |
578 | |
579 NSS_EXTERN PRBool nssUTF8_PrintableMatch(const NSSUTF8 *a, const NSSUTF8 *b, | |
580 PRStatus *statusOpt); | |
581 | |
582 /* | |
583 * nssUTF8_Size | |
584 * | |
585 * This routine returns the length in bytes (including the terminating | |
586 * null) of the UTF8-encoded string pointed to by the specified | |
587 * NSSUTF8 pointer. Zero is returned on error. | |
588 * | |
589 * The error may be one of the following values: | |
590 * NSS_ERROR_INVALID_POINTER | |
591 * NSS_ERROR_VALUE_TOO_LARGE | |
592 * | |
593 * Return value: | |
594 * nonzero size of the string | |
595 * 0 on error | |
596 */ | |
597 | |
598 NSS_EXTERN PRUint32 nssUTF8_Size(const NSSUTF8 *s, PRStatus *statusOpt); | |
599 | |
600 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
601 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE; | |
602 | |
603 /* | |
604 * nssUTF8_Length | |
605 * | |
606 * This routine returns the length in characters (not including the | |
607 * terminating null) of the UTF8-encoded string pointed to by the | |
608 * specified NSSUTF8 pointer. | |
609 * | |
610 * The error may be one of the following values: | |
611 * NSS_ERROR_INVALID_POINTER | |
612 * NSS_ERROR_VALUE_TOO_LARGE | |
613 * NSS_ERROR_INVALID_STRING | |
614 * | |
615 * Return value: | |
616 * length of the string (which may be zero) | |
617 * 0 on error | |
618 */ | |
619 | |
620 NSS_EXTERN PRUint32 nssUTF8_Length(const NSSUTF8 *s, PRStatus *statusOpt); | |
621 | |
622 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
623 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE; | |
624 extern const NSSError NSS_ERROR_INVALID_STRING; | |
625 | |
626 /* | |
627 * nssUTF8_Create | |
628 * | |
629 * This routine creates a UTF8 string from a string in some other | |
630 * format. Some types of string may include embedded null characters, | |
631 * so for them the length parameter must be used. For string types | |
632 * that are null-terminated, the length parameter is optional; if it | |
633 * is zero, it will be ignored. If the optional arena argument is | |
634 * non-null, the memory used for the new string will be obtained from | |
635 * that arena, otherwise it will be obtained from the heap. This | |
636 * routine may return NULL upon error, in which case it will have | |
637 * placed an error on the error stack. | |
638 * | |
639 * The error may be one of the following: | |
640 * NSS_ERROR_INVALID_POINTER | |
641 * NSS_ERROR_NO_MEMORY | |
642 * NSS_ERROR_UNSUPPORTED_TYPE | |
643 * | |
644 * Return value: | |
645 * NULL upon error | |
646 * A non-null pointer to a new UTF8 string otherwise | |
647 */ | |
648 | |
649 NSS_EXTERN NSSUTF8 *nssUTF8_Create(NSSArena *arenaOpt, nssStringType type, | |
650 const void *inputString, | |
651 PRUint32 size /* in bytes, not characters */ | |
652 ); | |
653 | |
654 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
655 extern const NSSError NSS_ERROR_NO_MEMORY; | |
656 extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE; | |
657 | |
658 NSS_EXTERN NSSItem *nssUTF8_GetEncoding(NSSArena *arenaOpt, NSSItem *rvOpt, | |
659 nssStringType type, NSSUTF8 *string); | |
660 | |
661 /* | |
662 * nssUTF8_CopyIntoFixedBuffer | |
663 * | |
664 * This will copy a UTF8 string into a fixed-length buffer, making | |
665 * sure that the all characters are valid. Any remaining space will | |
666 * be padded with the specified ASCII character, typically either | |
667 * null or space. | |
668 * | |
669 * Blah, blah, blah. | |
670 */ | |
671 | |
672 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
673 extern const NSSError NSS_ERROR_INVALID_ARGUMENT; | |
674 | |
675 NSS_EXTERN PRStatus nssUTF8_CopyIntoFixedBuffer(NSSUTF8 *string, char *buffer, | |
676 PRUint32 bufferSize, char pad); | |
677 | |
678 /* | |
679 * nssUTF8_Equal | |
680 * | |
681 */ | |
682 | |
683 NSS_EXTERN PRBool nssUTF8_Equal(const NSSUTF8 *a, const NSSUTF8 *b, | |
684 PRStatus *statusOpt); | |
685 | |
686 /* | |
687 * nssList | |
688 * | |
689 * The goal is to provide a simple, optionally threadsafe, linked list | |
690 * class. Since NSS did not seem to use the circularity of PRCList | |
691 * much before, this provides a list that appears to be a linear, | |
692 * NULL-terminated list. | |
693 */ | |
694 | |
695 /* | |
696 * nssList_Create | |
697 * | |
698 * If threadsafe is true, the list will be locked during modifications | |
699 * and traversals. | |
700 */ | |
701 NSS_EXTERN nssList *nssList_Create(NSSArena *arenaOpt, PRBool threadSafe); | |
702 | |
703 /* | |
704 * nssList_Destroy | |
705 */ | |
706 NSS_EXTERN PRStatus nssList_Destroy(nssList *list); | |
707 | |
708 NSS_EXTERN void nssList_Clear(nssList *list, | |
709 nssListElementDestructorFunc destructor); | |
710 | |
711 /* | |
712 * nssList_SetCompareFunction | |
713 * | |
714 * By default, two list elements will be compared by comparing their | |
715 * data pointers. By setting this function, the user can control | |
716 * how elements are compared. | |
717 */ | |
718 NSS_EXTERN void nssList_SetCompareFunction(nssList *list, | |
719 nssListCompareFunc compareFunc); | |
720 | |
721 /* | |
722 * nssList_SetSortFunction | |
723 * | |
724 * Sort function to use for an ordered list. | |
725 */ | |
726 NSS_EXTERN void nssList_SetSortFunction(nssList *list, | |
727 nssListSortFunc sortFunc); | |
728 | |
729 /* | |
730 * nssList_Add | |
731 */ | |
732 NSS_EXTERN PRStatus nssList_Add(nssList *list, void *data); | |
733 | |
734 /* | |
735 * nssList_AddUnique | |
736 * | |
737 * This will use the compare function to see if the element is already | |
738 * in the list. | |
739 */ | |
740 NSS_EXTERN PRStatus nssList_AddUnique(nssList *list, void *data); | |
741 | |
742 /* | |
743 * nssList_Remove | |
744 * | |
745 * Uses the compare function to locate the element and remove it. | |
746 */ | |
747 NSS_EXTERN PRStatus nssList_Remove(nssList *list, void *data); | |
748 | |
749 /* | |
750 * nssList_Get | |
751 * | |
752 * Uses the compare function to locate an element. Also serves as | |
753 * nssList_Exists. | |
754 */ | |
755 NSS_EXTERN void *nssList_Get(nssList *list, void *data); | |
756 | |
757 /* | |
758 * nssList_Count | |
759 */ | |
760 NSS_EXTERN PRUint32 nssList_Count(nssList *list); | |
761 | |
762 /* | |
763 * nssList_GetArray | |
764 * | |
765 * Fill rvArray, up to maxElements, with elements in the list. The | |
766 * array is NULL-terminated, so its allocated size must be maxElements + 1. | |
767 */ | |
768 NSS_EXTERN PRStatus nssList_GetArray(nssList *list, void **rvArray, | |
769 PRUint32 maxElements); | |
770 | |
771 /* | |
772 * nssList_CreateIterator | |
773 * | |
774 * Create an iterator for list traversal. | |
775 */ | |
776 NSS_EXTERN nssListIterator *nssList_CreateIterator(nssList *list); | |
777 | |
778 NSS_EXTERN nssList *nssList_Clone(nssList *list); | |
779 | |
780 /* | |
781 * nssListIterator_Destroy | |
782 */ | |
783 NSS_EXTERN void nssListIterator_Destroy(nssListIterator *iter); | |
784 | |
785 /* | |
786 * nssListIterator_Start | |
787 * | |
788 * Begin a list iteration. After this call, if the list is threadSafe, | |
789 * the list is *locked*. | |
790 */ | |
791 NSS_EXTERN void *nssListIterator_Start(nssListIterator *iter); | |
792 | |
793 /* | |
794 * nssListIterator_Next | |
795 * | |
796 * Continue a list iteration. | |
797 */ | |
798 NSS_EXTERN void *nssListIterator_Next(nssListIterator *iter); | |
799 | |
800 /* | |
801 * nssListIterator_Finish | |
802 * | |
803 * Complete a list iteration. This *must* be called in order for the | |
804 * lock to be released. | |
805 */ | |
806 NSS_EXTERN PRStatus nssListIterator_Finish(nssListIterator *iter); | |
807 | |
808 /* | |
809 * nssHash | |
810 * | |
811 * nssHash_Create | |
812 * nssHash_Destroy | |
813 * nssHash_Add | |
814 * nssHash_Remove | |
815 * nssHash_Count | |
816 * nssHash_Exists | |
817 * nssHash_Lookup | |
818 * nssHash_Iterate | |
819 */ | |
820 | |
821 /* | |
822 * nssHash_Create | |
823 * | |
824 */ | |
825 | |
826 NSS_EXTERN nssHash *nssHash_Create(NSSArena *arenaOpt, PRUint32 numBuckets, | |
827 PLHashFunction keyHash, | |
828 PLHashComparator keyCompare, | |
829 PLHashComparator valueCompare); | |
830 | |
831 NSS_EXTERN nssHash *nssHash_CreatePointer(NSSArena *arenaOpt, | |
832 PRUint32 numBuckets); | |
833 | |
834 NSS_EXTERN nssHash *nssHash_CreateString(NSSArena *arenaOpt, | |
835 PRUint32 numBuckets); | |
836 | |
837 NSS_EXTERN nssHash *nssHash_CreateItem(NSSArena *arenaOpt, PRUint32 numBuckets); | |
838 | |
839 /* | |
840 * nssHash_Destroy | |
841 * | |
842 */ | |
843 NSS_EXTERN void nssHash_Destroy(nssHash *hash); | |
844 | |
845 /* | |
846 * nssHash_Add | |
847 * | |
848 */ | |
849 | |
850 extern const NSSError NSS_ERROR_HASH_COLLISION; | |
851 | |
852 NSS_EXTERN PRStatus nssHash_Add(nssHash *hash, const void *key, | |
853 const void *value); | |
854 | |
855 /* | |
856 * nssHash_Remove | |
857 * | |
858 */ | |
859 NSS_EXTERN void nssHash_Remove(nssHash *hash, const void *it); | |
860 | |
861 /* | |
862 * nssHash_Count | |
863 * | |
864 */ | |
865 NSS_EXTERN PRUint32 nssHash_Count(nssHash *hash); | |
866 | |
867 /* | |
868 * nssHash_Exists | |
869 * | |
870 */ | |
871 NSS_EXTERN PRBool nssHash_Exists(nssHash *hash, const void *it); | |
872 | |
873 /* | |
874 * nssHash_Lookup | |
875 * | |
876 */ | |
877 NSS_EXTERN void *nssHash_Lookup(nssHash *hash, const void *it); | |
878 | |
879 /* | |
880 * nssHash_Iterate | |
881 * | |
882 */ | |
883 NSS_EXTERN void nssHash_Iterate(nssHash *hash, nssHashIterator fcn, | |
884 void *closure); | |
885 | |
886 /* | |
887 * nssPointerTracker | |
888 * | |
889 * This type and these methods are only present in debug builds. | |
890 * | |
891 * The nonpublic methods relating to this type are: | |
892 * | |
893 * nssPointerTracker_initialize | |
894 * nssPointerTracker_finalize | |
895 * nssPointerTracker_add | |
896 * nssPointerTracker_remove | |
897 * nssPointerTracker_verify | |
898 */ | |
899 | |
900 /* | |
901 * nssPointerTracker_initialize | |
902 * | |
903 * This method is only present in debug builds. | |
904 * | |
905 * This routine initializes an nssPointerTracker object. Note that | |
906 * the object must have been declared *static* to guarantee that it | |
907 * is in a zeroed state initially. This routine is idempotent, and | |
908 * may even be safely called by multiple threads simultaneously with | |
909 * the same argument. This routine returns a PRStatus value; if | |
910 * successful, it will return PR_SUCCESS. On failure it will set an | |
911 * error on the error stack and return PR_FAILURE. | |
912 * | |
913 * The error may be one of the following values: | |
914 * NSS_ERROR_NO_MEMORY | |
915 * | |
916 * Return value: | |
917 * PR_SUCCESS | |
918 * PR_FAILURE | |
919 */ | |
920 | |
921 #ifdef DEBUG | |
922 NSS_EXTERN PRStatus nssPointerTracker_initialize(nssPointerTracker *tracker); | |
923 | |
924 extern const NSSError NSS_ERROR_NO_MEMORY; | |
925 #endif /* DEBUG */ | |
926 | |
927 /* | |
928 * nssPointerTracker_finalize | |
929 * | |
930 * This method is only present in debug builds. | |
931 * | |
932 * This routine returns the nssPointerTracker object to the pre- | |
933 * initialized state, releasing all resources used by the object. | |
934 * It will *NOT* destroy the objects being tracked by the pointer | |
935 * (should any remain), and therefore cannot be used to "sweep up" | |
936 * remaining objects. This routine returns a PRStatus value; if | |
937 * successful, it will return PR_SUCCES. On failure it will set an | |
938 * error on the error stack and return PR_FAILURE. If any objects | |
939 * remain in the tracker when it is finalized, that will be treated | |
940 * as an error. | |
941 * | |
942 * The error may be one of the following values: | |
943 * NSS_ERROR_TRACKER_NOT_EMPTY | |
944 * | |
945 * Return value: | |
946 * PR_SUCCESS | |
947 * PR_FAILURE | |
948 */ | |
949 | |
950 #ifdef DEBUG | |
951 NSS_EXTERN PRStatus nssPointerTracker_finalize(nssPointerTracker *tracker); | |
952 | |
953 extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY; | |
954 #endif /* DEBUG */ | |
955 | |
956 /* | |
957 * nssPointerTracker_add | |
958 * | |
959 * This method is only present in debug builds. | |
960 * | |
961 * This routine adds the specified pointer to the nssPointerTracker | |
962 * object. It should be called in constructor objects to register | |
963 * new valid objects. The nssPointerTracker is threadsafe, but this | |
964 * call is not idempotent. This routine returns a PRStatus value; | |
965 * if successful it will return PR_SUCCESS. On failure it will set | |
966 * an error on the error stack and return PR_FAILURE. | |
967 * | |
968 * The error may be one of the following values: | |
969 * NSS_ERROR_NO_MEMORY | |
970 * NSS_ERROR_TRACKER_NOT_INITIALIZED | |
971 * NSS_ERROR_DUPLICATE_POINTER | |
972 * | |
973 * Return value: | |
974 * PR_SUCCESS | |
975 * PR_FAILURE | |
976 */ | |
977 | |
978 #ifdef DEBUG | |
979 NSS_EXTERN PRStatus nssPointerTracker_add(nssPointerTracker *tracker, | |
980 const void *pointer); | |
981 | |
982 extern const NSSError NSS_ERROR_NO_MEMORY; | |
983 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED; | |
984 extern const NSSError NSS_ERROR_DUPLICATE_POINTER; | |
985 #endif /* DEBUG */ | |
986 | |
987 /* | |
988 * nssPointerTracker_remove | |
989 * | |
990 * This method is only present in debug builds. | |
991 * | |
992 * This routine removes the specified pointer from the | |
993 * nssPointerTracker object. It does not call any destructor for the | |
994 * object; rather, this should be called from the object's destructor. | |
995 * The nssPointerTracker is threadsafe, but this call is not | |
996 * idempotent. This routine returns a PRStatus value; if successful | |
997 * it will return PR_SUCCESS. On failure it will set an error on the | |
998 * error stack and return PR_FAILURE. | |
999 * | |
1000 * The error may be one of the following values: | |
1001 * NSS_ERROR_TRACKER_NOT_INITIALIZED | |
1002 * NSS_ERROR_POINTER_NOT_REGISTERED | |
1003 * | |
1004 * Return value: | |
1005 * PR_SUCCESS | |
1006 * PR_FAILURE | |
1007 */ | |
1008 | |
1009 #ifdef DEBUG | |
1010 NSS_EXTERN PRStatus nssPointerTracker_remove(nssPointerTracker *tracker, | |
1011 const void *pointer); | |
1012 | |
1013 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED; | |
1014 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED; | |
1015 #endif /* DEBUG */ | |
1016 | |
1017 /* | |
1018 * nssPointerTracker_verify | |
1019 * | |
1020 * This method is only present in debug builds. | |
1021 * | |
1022 * This routine verifies that the specified pointer has been registered | |
1023 * with the nssPointerTracker object. The nssPointerTracker object is | |
1024 * threadsafe, and this call may be safely called from multiple threads | |
1025 * simultaneously with the same arguments. This routine returns a | |
1026 * PRStatus value; if the pointer is registered this will return | |
1027 * PR_SUCCESS. Otherwise it will set an error on the error stack and | |
1028 * return PR_FAILURE. Although the error is suitable for leaving on | |
1029 * the stack, callers may wish to augment the information available by | |
1030 * placing a more type-specific error on the stack. | |
1031 * | |
1032 * The error may be one of the following values: | |
1033 * NSS_ERROR_POINTER_NOT_REGISTERED | |
1034 * | |
1035 * Return value: | |
1036 * PR_SUCCESS | |
1037 * PR_FAILRUE | |
1038 */ | |
1039 | |
1040 #ifdef DEBUG | |
1041 NSS_EXTERN PRStatus nssPointerTracker_verify(nssPointerTracker *tracker, | |
1042 const void *pointer); | |
1043 | |
1044 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED; | |
1045 #endif /* DEBUG */ | |
1046 | |
1047 /* | |
1048 * libc | |
1049 * | |
1050 * nsslibc_memcpy | |
1051 * nsslibc_memset | |
1052 * nsslibc_offsetof | |
1053 */ | |
1054 | |
1055 /* | |
1056 * nsslibc_memcpy | |
1057 * | |
1058 * Errors: | |
1059 * NSS_ERROR_INVALID_POINTER | |
1060 * | |
1061 * Return value: | |
1062 * NULL on error | |
1063 * The destination pointer on success | |
1064 */ | |
1065 | |
1066 NSS_EXTERN void *nsslibc_memcpy(void *dest, const void *source, PRUint32 n); | |
1067 | |
1068 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
1069 | |
1070 /* | |
1071 * nsslibc_memset | |
1072 * | |
1073 * Errors: | |
1074 * NSS_ERROR_INVALID_POINTER | |
1075 * | |
1076 * Return value: | |
1077 * NULL on error | |
1078 * The destination pointer on success | |
1079 */ | |
1080 | |
1081 NSS_EXTERN void *nsslibc_memset(void *dest, PRUint8 byte, PRUint32 n); | |
1082 | |
1083 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
1084 | |
1085 /* | |
1086 * nsslibc_memequal | |
1087 * | |
1088 * Errors: | |
1089 * NSS_ERROR_INVALID_POINTER | |
1090 * | |
1091 * Return value: | |
1092 * PR_TRUE if they match | |
1093 * PR_FALSE if they don't | |
1094 * PR_FALSE upon error | |
1095 */ | |
1096 | |
1097 NSS_EXTERN PRBool nsslibc_memequal(const void *a, const void *b, PRUint32 len, | |
1098 PRStatus *statusOpt); | |
1099 | |
1100 extern const NSSError NSS_ERROR_INVALID_POINTER; | |
1101 | |
1102 #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb))) | |
1103 | |
1104 PR_END_EXTERN_C | |
1105 | |
1106 #endif /* BASE_H */ | |
OLD | NEW |