The Tor Browser / file comparison

comparison: security/nss/lib/base/base.h

security/nss/lib/base/base.h

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:356e00dcee57
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 *
87 nssArena_Create
88 (
89 void
90 );
91
92 extern const NSSError NSS_ERROR_NO_MEMORY;
93
94 /*
95 * nssArena_Destroy
96 *
97 * This routine will destroy the specified arena, freeing all memory
98 * allocated from it. This routine returns a PRStatus value; if
99 * successful, it will return PR_SUCCESS. If unsuccessful, it will
100 * set an error on the error stack and return PR_FAILURE.
101 *
102 * The error may be one of the following values:
103 * NSS_ERROR_INVALID_ARENA
104 *
105 * Return value:
106 * PR_SUCCESS
107 * PR_FAILURE
108 */
109
110 NSS_EXTERN PRStatus
111 nssArena_Destroy
112 (
113 NSSArena *arena
114 );
115
116 extern const NSSError NSS_ERROR_INVALID_ARENA;
117
118 /*
119 * nssArena_Mark
120 *
121 * This routine "marks" the current state of an arena. Space
122 * allocated after the arena has been marked can be freed by
123 * releasing the arena back to the mark with nssArena_Release,
124 * or committed by calling nssArena_Unmark. When successful,
125 * this routine returns a valid nssArenaMark pointer. This
126 * routine may return NULL upon error, in which case it will
127 * have set an error on the error stack.
128 *
129 * The error may be one of the following values:
130 * NSS_ERROR_INVALID_ARENA
131 * NSS_ERROR_NO_MEMORY
132 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
133 *
134 * Return value:
135 * NULL upon failure
136 * An nssArenaMark pointer upon success
137 */
138
139 NSS_EXTERN nssArenaMark *
140 nssArena_Mark
141 (
142 NSSArena *arena
143 );
144
145 extern const NSSError NSS_ERROR_INVALID_ARENA;
146 extern const NSSError NSS_ERROR_NO_MEMORY;
147 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
148
149 /*
150 * nssArena_Release
151 *
152 * This routine invalidates and releases all memory allocated from
153 * the specified arena after the point at which the specified mark
154 * was obtained. This routine returns a PRStatus value; if successful,
155 * it will return PR_SUCCESS. If unsuccessful, it will set an error
156 * on the error stack and return PR_FAILURE.
157 *
158 * The error may be one of the following values:
159 * NSS_ERROR_INVALID_ARENA
160 * NSS_ERROR_INVALID_ARENA_MARK
161 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
162 *
163 * Return value:
164 * PR_SUCCESS
165 * PR_FAILURE
166 */
167
168 NSS_EXTERN PRStatus
169 nssArena_Release
170 (
171 NSSArena *arena,
172 nssArenaMark *arenaMark
173 );
174
175 extern const NSSError NSS_ERROR_INVALID_ARENA;
176 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
177
178 /*
179 * nssArena_Unmark
180 *
181 * This routine "commits" the indicated mark and any marks after
182 * it, making them unreleasable. Note that any earlier marks can
183 * still be released, and such a release will invalidate these
184 * later unmarked regions. If an arena is to be safely shared by
185 * more than one thread, all marks must be either released or
186 * unmarked. This routine returns a PRStatus value; if successful,
187 * it will return PR_SUCCESS. If unsuccessful, it will set an error
188 * on the error stack and return PR_FAILURE.
189 *
190 * The error may be one of the following values:
191 * NSS_ERROR_INVALID_ARENA
192 * NSS_ERROR_INVALID_ARENA_MARK
193 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
194 *
195 * Return value:
196 * PR_SUCCESS
197 * PR_FAILURE
198 */
199
200 NSS_EXTERN PRStatus
201 nssArena_Unmark
202 (
203 NSSArena *arena,
204 nssArenaMark *arenaMark
205 );
206
207 extern const NSSError NSS_ERROR_INVALID_ARENA;
208 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
209 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
210
211 #ifdef ARENA_DESTRUCTOR_LIST
212
213 /*
214 * nssArena_registerDestructor
215 *
216 * This routine stores a pointer to a callback and an arbitrary
217 * pointer-sized argument in the arena, at the current point in
218 * the mark stack. If the arena is destroyed, or an "earlier"
219 * mark is released, then this destructor will be called at that
220 * time. Note that the destructor will be called with the arena
221 * locked, which means the destructor may free memory in that
222 * arena, but it may not allocate or cause to be allocated any
223 * memory. This callback facility was included to support our
224 * debug-version pointer-tracker feature; overuse runs counter to
225 * the the original intent of arenas. This routine returns a
226 * PRStatus value; if successful, it will return PR_SUCCESS. If
227 * unsuccessful, it will set an error on the error stack and
228 * return PR_FAILURE.
229 *
230 * The error may be one of the following values:
231 * NSS_ERROR_INVALID_ARENA
232 * NSS_ERROR_NO_MEMORY
233 *
234 * Return value:
235 * PR_SUCCESS
236 * PR_FAILURE
237 */
238
239 NSS_EXTERN PRStatus
240 nssArena_registerDestructor
241 (
242 NSSArena *arena,
243 void (*destructor)(void *argument),
244 void *arg
245 );
246
247 extern const NSSError NSS_ERROR_INVALID_ARENA;
248 extern const NSSError NSS_ERROR_NO_MEMORY;
249
250 /*
251 * nssArena_deregisterDestructor
252 *
253 * This routine will remove the first destructor in the specified
254 * arena which has the specified destructor and argument values.
255 * The destructor will not be called. This routine returns a
256 * PRStatus value; if successful, it will return PR_SUCCESS. If
257 * unsuccessful, it will set an error on the error stack and
258 * return PR_FAILURE.
259 *
260 * The error may be one of the following values:
261 * NSS_ERROR_INVALID_ARENA
262 * NSS_ERROR_NOT_FOUND
263 *
264 * Return value:
265 * PR_SUCCESS
266 * PR_FAILURE
267 */
268
269 NSS_EXTERN PRStatus
270 nssArena_deregisterDestructor
271 (
272 NSSArena *arena,
273 void (*destructor)(void *argument),
274 void *arg
275 );
276
277 extern const NSSError NSS_ERROR_INVALID_ITEM;
278 extern const NSSError NSS_ERROR_INVALID_ARENA;
279 extern const NSSError NSS_ERROR_NOT_FOUND;
280
281 #endif /* ARENA_DESTRUCTOR_LIST */
282
283 /*
284 * nss_ZAlloc
285 *
286 * This routine allocates and zeroes a section of memory of the
287 * size, and returns to the caller a pointer to that memory. If
288 * the optional arena argument is non-null, the memory will be
289 * obtained from that arena; otherwise, the memory will be obtained
290 * from the heap. This routine may return NULL upon error, in
291 * which case it will have set an error upon the error stack. The
292 * value specified for size may be zero; in which case a valid
293 * zero-length block of memory will be allocated. This block may
294 * be expanded by calling nss_ZRealloc.
295 *
296 * The error may be one of the following values:
297 * NSS_ERROR_INVALID_ARENA
298 * NSS_ERROR_NO_MEMORY
299 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
300 *
301 * Return value:
302 * NULL upon error
303 * A pointer to the new segment of zeroed memory
304 */
305
306 NSS_EXTERN void *
307 nss_ZAlloc
308 (
309 NSSArena *arenaOpt,
310 PRUint32 size
311 );
312
313 extern const NSSError NSS_ERROR_INVALID_ARENA;
314 extern const NSSError NSS_ERROR_NO_MEMORY;
315 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
316
317 /*
318 * nss_ZFreeIf
319 *
320 * If the specified pointer is non-null, then the region of memory
321 * to which it points -- which must have been allocated with
322 * nss_ZAlloc -- will be zeroed and released. This routine
323 * returns a PRStatus value; if successful, it will return PR_SUCCESS.
324 * If unsuccessful, it will set an error on the error stack and return
325 * PR_FAILURE.
326 *
327 * The error may be one of the following values:
328 * NSS_ERROR_INVALID_POINTER
329 *
330 * Return value:
331 * PR_SUCCESS
332 * PR_FAILURE
333 */
334
335 NSS_EXTERN PRStatus
336 nss_ZFreeIf
337 (
338 void *pointer
339 );
340
341 extern const NSSError NSS_ERROR_INVALID_POINTER;
342
343 /*
344 * nss_ZRealloc
345 *
346 * This routine reallocates a block of memory obtained by calling
347 * nss_ZAlloc or nss_ZRealloc. The portion of memory
348 * between the new and old sizes -- which is either being newly
349 * obtained or released -- is in either case zeroed. This routine
350 * may return NULL upon failure, in which case it will have placed
351 * an error on the error stack.
352 *
353 * The error may be one of the following values:
354 * NSS_ERROR_INVALID_POINTER
355 * NSS_ERROR_NO_MEMORY
356 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
357 *
358 * Return value:
359 * NULL upon error
360 * A pointer to the replacement segment of memory
361 */
362
363 NSS_EXTERN void *
364 nss_ZRealloc
365 (
366 void *pointer,
367 PRUint32 newSize
368 );
369
370 extern const NSSError NSS_ERROR_INVALID_POINTER;
371 extern const NSSError NSS_ERROR_NO_MEMORY;
372 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
373
374 /*
375 * nss_ZNEW
376 *
377 * This preprocessor macro will allocate memory for a new object
378 * of the specified type with nss_ZAlloc, and will cast the
379 * return value appropriately. If the optional arena argument is
380 * non-null, the memory will be obtained from that arena; otherwise,
381 * the memory will be obtained from the heap. This routine may
382 * return NULL upon error, in which case it will have set an error
383 * upon the error stack.
384 *
385 * The error may be one of the following values:
386 * NSS_ERROR_INVALID_ARENA
387 * NSS_ERROR_NO_MEMORY
388 *
389 * Return value:
390 * NULL upon error
391 * A pointer to the new segment of zeroed memory
392 */
393
394 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
395 #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type)))
396
397 /*
398 * nss_ZNEWARRAY
399 *
400 * This preprocessor macro will allocate memory for an array of
401 * new objects, and will cast the return value appropriately.
402 * If the optional arena argument is non-null, the memory will
403 * be obtained from that arena; otherwise, the memory will be
404 * obtained from the heap. This routine may return NULL upon
405 * error, in which case it will have set an error upon the error
406 * stack. The array size may be specified as zero.
407 *
408 * The error may be one of the following values:
409 * NSS_ERROR_INVALID_ARENA
410 * NSS_ERROR_NO_MEMORY
411 *
412 * Return value:
413 * NULL upon error
414 * A pointer to the new segment of zeroed memory
415 */
416
417 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
418 #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
419
420 /*
421 * nss_ZREALLOCARRAY
422 *
423 * This preprocessor macro will reallocate memory for an array of
424 * new objects, and will cast the return value appropriately.
425 * This routine may return NULL upon error, in which case it will
426 * have set an error upon the error stack.
427 *
428 * The error may be one of the following values:
429 * NSS_ERROR_INVALID_POINTER
430 * NSS_ERROR_NO_MEMORY
431 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
432 *
433 * Return value:
434 * NULL upon error
435 * A pointer to the replacement segment of memory
436 */
437 #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity)))
438
439 /*
440 * nssArena_verifyPointer
441 *
442 * This method is only present in debug builds.
443 *
444 * If the specified pointer is a valid pointer to an NSSArena object,
445 * this routine will return PR_SUCCESS. Otherwise, it will put an
446 * error on the error stack and return PR_FAILURE.
447 *
448 * The error may be one of the following values:
449 * NSS_ERROR_INVALID_ARENA
450 *
451 * Return value:
452 * PR_SUCCESS if the pointer is valid
453 * PR_FAILURE if it isn't
454 */
455
456 #ifdef DEBUG
457 NSS_EXTERN PRStatus
458 nssArena_verifyPointer
459 (
460 const NSSArena *arena
461 );
462
463 extern const NSSError NSS_ERROR_INVALID_ARENA;
464 #endif /* DEBUG */
465
466 /*
467 * nssArena_VERIFYPOINTER
468 *
469 * This macro is always available. In debug builds it will call
470 * nssArena_verifyPointer; in non-debug builds, it will merely
471 * check that the pointer is not null. Note that in non-debug
472 * builds it cannot place an error on the error stack.
473 *
474 * Return value:
475 * PR_SUCCESS if the pointer is valid
476 * PR_FAILURE if it isn't
477 */
478
479 #ifdef DEBUG
480 #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p)
481 #else /* DEBUG */
482 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
483 #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS)
484 #endif /* DEBUG */
485
486 /*
487 * Private function to be called by NSS_Shutdown to cleanup nssArena
488 * bookkeeping.
489 */
490 extern PRStatus
491 nssArena_Shutdown(void);
492
493 /*
494 * nssArenaHashAllocOps
495 *
496 * This constant structure contains allocation callbacks designed for
497 * use with the NSPL routine PL_NewHashTable. For example:
498 *
499 * NSSArena *hashTableArena = nssArena_Create();
500 * PLHashTable *t = PL_NewHashTable(n, hasher, key_compare,
501 * value_compare, nssArenaHashAllocOps, hashTableArena);
502 */
503
504 NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps;
505
506 /*
507 * The error stack
508 *
509 * The nonpublic methods relating to the error stack are:
510 *
511 * nss_SetError
512 * nss_ClearErrorStack
513 */
514
515 /*
516 * nss_SetError
517 *
518 * This routine places a new error code on the top of the calling
519 * thread's error stack. Calling this routine wiht an error code
520 * of zero will clear the error stack.
521 */
522
523 NSS_EXTERN void
524 nss_SetError
525 (
526 PRUint32 error
527 );
528
529 /*
530 * nss_ClearErrorStack
531 *
532 * This routine clears the calling thread's error stack.
533 */
534
535 NSS_EXTERN void
536 nss_ClearErrorStack
537 (
538 void
539 );
540
541 /*
542 * nss_DestroyErrorStack
543 *
544 * This routine frees the calling thread's error stack.
545 */
546
547 NSS_EXTERN void
548 nss_DestroyErrorStack
549 (
550 void
551 );
552
553 /*
554 * NSSItem
555 *
556 * nssItem_Create
557 * nssItem_Duplicate
558 * nssItem_Equal
559 */
560
561 NSS_EXTERN NSSItem *
562 nssItem_Create
563 (
564 NSSArena *arenaOpt,
565 NSSItem *rvOpt,
566 PRUint32 length,
567 const void *data
568 );
569
570 NSS_EXTERN void
571 nssItem_Destroy
572 (
573 NSSItem *item
574 );
575
576 NSS_EXTERN NSSItem *
577 nssItem_Duplicate
578 (
579 NSSItem *obj,
580 NSSArena *arenaOpt,
581 NSSItem *rvOpt
582 );
583
584 NSS_EXTERN PRBool
585 nssItem_Equal
586 (
587 const NSSItem *one,
588 const NSSItem *two,
589 PRStatus *statusOpt
590 );
591
592 /*
593 * NSSUTF8
594 *
595 * nssUTF8_CaseIgnoreMatch
596 * nssUTF8_Duplicate
597 * nssUTF8_Size
598 * nssUTF8_Length
599 * nssUTF8_CopyIntoFixedBuffer
600 */
601
602 /*
603 * nssUTF8_CaseIgnoreMatch
604 *
605 * Returns true if the two UTF8-encoded strings pointed to by the
606 * two specified NSSUTF8 pointers differ only in typcase.
607 *
608 * The error may be one of the following values:
609 * NSS_ERROR_INVALID_POINTER
610 *
611 * Return value:
612 * PR_TRUE if the strings match, ignoring case
613 * PR_FALSE if they don't
614 * PR_FALSE upon error
615 */
616
617 NSS_EXTERN PRBool
618 nssUTF8_CaseIgnoreMatch
619 (
620 const NSSUTF8 *a,
621 const NSSUTF8 *b,
622 PRStatus *statusOpt
623 );
624
625 /*
626 * nssUTF8_Duplicate
627 *
628 * This routine duplicates the UTF8-encoded string pointed to by the
629 * specified NSSUTF8 pointer. If the optional arenaOpt argument is
630 * not null, the memory required will be obtained from that arena;
631 * otherwise, the memory required will be obtained from the heap.
632 * A pointer to the new string will be returned. In case of error,
633 * an error will be placed on the error stack and NULL will be
634 * returned.
635 *
636 * The error may be one of the following values:
637 * NSS_ERROR_INVALID_POINTER
638 * NSS_ERROR_INVALID_ARENA
639 * NSS_ERROR_NO_MEMORY
640 */
641
642 NSS_EXTERN NSSUTF8 *
643 nssUTF8_Duplicate
644 (
645 const NSSUTF8 *s,
646 NSSArena *arenaOpt
647 );
648
649 /*
650 * nssUTF8_PrintableMatch
651 *
652 * Returns true if the two Printable strings pointed to by the
653 * two specified NSSUTF8 pointers match when compared with the
654 * rules for Printable String (leading and trailing spaces are
655 * disregarded, extents of whitespace match irregardless of length,
656 * and case is not significant), then PR_TRUE will be returned.
657 * Otherwise, PR_FALSE will be returned. Upon failure, PR_FALSE
658 * will be returned. If the optional statusOpt argument is not
659 * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that
660 * location.
661 *
662 * The error may be one of the following values:
663 * NSS_ERROR_INVALID_POINTER
664 *
665 * Return value:
666 * PR_TRUE if the strings match, ignoring case
667 * PR_FALSE if they don't
668 * PR_FALSE upon error
669 */
670
671 NSS_EXTERN PRBool
672 nssUTF8_PrintableMatch
673 (
674 const NSSUTF8 *a,
675 const NSSUTF8 *b,
676 PRStatus *statusOpt
677 );
678
679 /*
680 * nssUTF8_Size
681 *
682 * This routine returns the length in bytes (including the terminating
683 * null) of the UTF8-encoded string pointed to by the specified
684 * NSSUTF8 pointer. Zero is returned on error.
685 *
686 * The error may be one of the following values:
687 * NSS_ERROR_INVALID_POINTER
688 * NSS_ERROR_VALUE_TOO_LARGE
689 *
690 * Return value:
691 * nonzero size of the string
692 * 0 on error
693 */
694
695 NSS_EXTERN PRUint32
696 nssUTF8_Size
697 (
698 const NSSUTF8 *s,
699 PRStatus *statusOpt
700 );
701
702 extern const NSSError NSS_ERROR_INVALID_POINTER;
703 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
704
705 /*
706 * nssUTF8_Length
707 *
708 * This routine returns the length in characters (not including the
709 * terminating null) of the UTF8-encoded string pointed to by the
710 * specified NSSUTF8 pointer.
711 *
712 * The error may be one of the following values:
713 * NSS_ERROR_INVALID_POINTER
714 * NSS_ERROR_VALUE_TOO_LARGE
715 * NSS_ERROR_INVALID_STRING
716 *
717 * Return value:
718 * length of the string (which may be zero)
719 * 0 on error
720 */
721
722 NSS_EXTERN PRUint32
723 nssUTF8_Length
724 (
725 const NSSUTF8 *s,
726 PRStatus *statusOpt
727 );
728
729 extern const NSSError NSS_ERROR_INVALID_POINTER;
730 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
731 extern const NSSError NSS_ERROR_INVALID_STRING;
732
733 /*
734 * nssUTF8_Create
735 *
736 * This routine creates a UTF8 string from a string in some other
737 * format. Some types of string may include embedded null characters,
738 * so for them the length parameter must be used. For string types
739 * that are null-terminated, the length parameter is optional; if it
740 * is zero, it will be ignored. If the optional arena argument is
741 * non-null, the memory used for the new string will be obtained from
742 * that arena, otherwise it will be obtained from the heap. This
743 * routine may return NULL upon error, in which case it will have
744 * placed an error on the error stack.
745 *
746 * The error may be one of the following:
747 * NSS_ERROR_INVALID_POINTER
748 * NSS_ERROR_NO_MEMORY
749 * NSS_ERROR_UNSUPPORTED_TYPE
750 *
751 * Return value:
752 * NULL upon error
753 * A non-null pointer to a new UTF8 string otherwise
754 */
755
756 NSS_EXTERN NSSUTF8 *
757 nssUTF8_Create
758 (
759 NSSArena *arenaOpt,
760 nssStringType type,
761 const void *inputString,
762 PRUint32 size /* in bytes, not characters */
763 );
764
765 extern const NSSError NSS_ERROR_INVALID_POINTER;
766 extern const NSSError NSS_ERROR_NO_MEMORY;
767 extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE;
768
769 NSS_EXTERN NSSItem *
770 nssUTF8_GetEncoding
771 (
772 NSSArena *arenaOpt,
773 NSSItem *rvOpt,
774 nssStringType type,
775 NSSUTF8 *string
776 );
777
778 /*
779 * nssUTF8_CopyIntoFixedBuffer
780 *
781 * This will copy a UTF8 string into a fixed-length buffer, making
782 * sure that the all characters are valid. Any remaining space will
783 * be padded with the specified ASCII character, typically either
784 * null or space.
785 *
786 * Blah, blah, blah.
787 */
788
789 extern const NSSError NSS_ERROR_INVALID_POINTER;
790 extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
791
792 NSS_EXTERN PRStatus
793 nssUTF8_CopyIntoFixedBuffer
794 (
795 NSSUTF8 *string,
796 char *buffer,
797 PRUint32 bufferSize,
798 char pad
799 );
800
801 /*
802 * nssUTF8_Equal
803 *
804 */
805
806 NSS_EXTERN PRBool
807 nssUTF8_Equal
808 (
809 const NSSUTF8 *a,
810 const NSSUTF8 *b,
811 PRStatus *statusOpt
812 );
813
814 /*
815 * nssList
816 *
817 * The goal is to provide a simple, optionally threadsafe, linked list
818 * class. Since NSS did not seem to use the circularity of PRCList
819 * much before, this provides a list that appears to be a linear,
820 * NULL-terminated list.
821 */
822
823 /*
824 * nssList_Create
825 *
826 * If threadsafe is true, the list will be locked during modifications
827 * and traversals.
828 */
829 NSS_EXTERN nssList *
830 nssList_Create
831 (
832 NSSArena *arenaOpt,
833 PRBool threadSafe
834 );
835
836 /*
837 * nssList_Destroy
838 */
839 NSS_EXTERN PRStatus
840 nssList_Destroy
841 (
842 nssList *list
843 );
844
845 NSS_EXTERN void
846 nssList_Clear
847 (
848 nssList *list,
849 nssListElementDestructorFunc destructor
850 );
851
852 /*
853 * nssList_SetCompareFunction
854 *
855 * By default, two list elements will be compared by comparing their
856 * data pointers. By setting this function, the user can control
857 * how elements are compared.
858 */
859 NSS_EXTERN void
860 nssList_SetCompareFunction
861 (
862 nssList *list,
863 nssListCompareFunc compareFunc
864 );
865
866 /*
867 * nssList_SetSortFunction
868 *
869 * Sort function to use for an ordered list.
870 */
871 NSS_EXTERN void
872 nssList_SetSortFunction
873 (
874 nssList *list,
875 nssListSortFunc sortFunc
876 );
877
878 /*
879 * nssList_Add
880 */
881 NSS_EXTERN PRStatus
882 nssList_Add
883 (
884 nssList *list,
885 void *data
886 );
887
888 /*
889 * nssList_AddUnique
890 *
891 * This will use the compare function to see if the element is already
892 * in the list.
893 */
894 NSS_EXTERN PRStatus
895 nssList_AddUnique
896 (
897 nssList *list,
898 void *data
899 );
900
901 /*
902 * nssList_Remove
903 *
904 * Uses the compare function to locate the element and remove it.
905 */
906 NSS_EXTERN PRStatus
907 nssList_Remove(nssList *list, void *data);
908
909 /*
910 * nssList_Get
911 *
912 * Uses the compare function to locate an element. Also serves as
913 * nssList_Exists.
914 */
915 NSS_EXTERN void *
916 nssList_Get
917 (
918 nssList *list,
919 void *data
920 );
921
922 /*
923 * nssList_Count
924 */
925 NSS_EXTERN PRUint32
926 nssList_Count
927 (
928 nssList *list
929 );
930
931 /*
932 * nssList_GetArray
933 *
934 * Fill rvArray, up to maxElements, with elements in the list. The
935 * array is NULL-terminated, so its allocated size must be maxElements + 1.
936 */
937 NSS_EXTERN PRStatus
938 nssList_GetArray
939 (
940 nssList *list,
941 void **rvArray,
942 PRUint32 maxElements
943 );
944
945 /*
946 * nssList_CreateIterator
947 *
948 * Create an iterator for list traversal.
949 */
950 NSS_EXTERN nssListIterator *
951 nssList_CreateIterator
952 (
953 nssList *list
954 );
955
956 NSS_EXTERN nssList *
957 nssList_Clone
958 (
959 nssList *list
960 );
961
962 /*
963 * nssListIterator_Destroy
964 */
965 NSS_EXTERN void
966 nssListIterator_Destroy
967 (
968 nssListIterator *iter
969 );
970
971 /*
972 * nssListIterator_Start
973 *
974 * Begin a list iteration. After this call, if the list is threadSafe,
975 * the list is *locked*.
976 */
977 NSS_EXTERN void *
978 nssListIterator_Start
979 (
980 nssListIterator *iter
981 );
982
983 /*
984 * nssListIterator_Next
985 *
986 * Continue a list iteration.
987 */
988 NSS_EXTERN void *
989 nssListIterator_Next
990 (
991 nssListIterator *iter
992 );
993
994 /*
995 * nssListIterator_Finish
996 *
997 * Complete a list iteration. This *must* be called in order for the
998 * lock to be released.
999 */
1000 NSS_EXTERN PRStatus
1001 nssListIterator_Finish
1002 (
1003 nssListIterator *iter
1004 );
1005
1006 /*
1007 * nssHash
1008 *
1009 * nssHash_Create
1010 * nssHash_Destroy
1011 * nssHash_Add
1012 * nssHash_Remove
1013 * nssHash_Count
1014 * nssHash_Exists
1015 * nssHash_Lookup
1016 * nssHash_Iterate
1017 */
1018
1019 /*
1020 * nssHash_Create
1021 *
1022 */
1023
1024 NSS_EXTERN nssHash *
1025 nssHash_Create
1026 (
1027 NSSArena *arenaOpt,
1028 PRUint32 numBuckets,
1029 PLHashFunction keyHash,
1030 PLHashComparator keyCompare,
1031 PLHashComparator valueCompare
1032 );
1033
1034 NSS_EXTERN nssHash *
1035 nssHash_CreatePointer
1036 (
1037 NSSArena *arenaOpt,
1038 PRUint32 numBuckets
1039 );
1040
1041 NSS_EXTERN nssHash *
1042 nssHash_CreateString
1043 (
1044 NSSArena *arenaOpt,
1045 PRUint32 numBuckets
1046 );
1047
1048 NSS_EXTERN nssHash *
1049 nssHash_CreateItem
1050 (
1051 NSSArena *arenaOpt,
1052 PRUint32 numBuckets
1053 );
1054
1055 /*
1056 * nssHash_Destroy
1057 *
1058 */
1059 NSS_EXTERN void
1060 nssHash_Destroy
1061 (
1062 nssHash *hash
1063 );
1064
1065 /*
1066 * nssHash_Add
1067 *
1068 */
1069
1070 extern const NSSError NSS_ERROR_HASH_COLLISION;
1071
1072 NSS_EXTERN PRStatus
1073 nssHash_Add
1074 (
1075 nssHash *hash,
1076 const void *key,
1077 const void *value
1078 );
1079
1080 /*
1081 * nssHash_Remove
1082 *
1083 */
1084 NSS_EXTERN void
1085 nssHash_Remove
1086 (
1087 nssHash *hash,
1088 const void *it
1089 );
1090
1091 /*
1092 * nssHash_Count
1093 *
1094 */
1095 NSS_EXTERN PRUint32
1096 nssHash_Count
1097 (
1098 nssHash *hash
1099 );
1100
1101 /*
1102 * nssHash_Exists
1103 *
1104 */
1105 NSS_EXTERN PRBool
1106 nssHash_Exists
1107 (
1108 nssHash *hash,
1109 const void *it
1110 );
1111
1112 /*
1113 * nssHash_Lookup
1114 *
1115 */
1116 NSS_EXTERN void *
1117 nssHash_Lookup
1118 (
1119 nssHash *hash,
1120 const void *it
1121 );
1122
1123 /*
1124 * nssHash_Iterate
1125 *
1126 */
1127 NSS_EXTERN void
1128 nssHash_Iterate
1129 (
1130 nssHash *hash,
1131 nssHashIterator fcn,
1132 void *closure
1133 );
1134
1135
1136 /*
1137 * nssPointerTracker
1138 *
1139 * This type and these methods are only present in debug builds.
1140 *
1141 * The nonpublic methods relating to this type are:
1142 *
1143 * nssPointerTracker_initialize
1144 * nssPointerTracker_finalize
1145 * nssPointerTracker_add
1146 * nssPointerTracker_remove
1147 * nssPointerTracker_verify
1148 */
1149
1150 /*
1151 * nssPointerTracker_initialize
1152 *
1153 * This method is only present in debug builds.
1154 *
1155 * This routine initializes an nssPointerTracker object. Note that
1156 * the object must have been declared *static* to guarantee that it
1157 * is in a zeroed state initially. This routine is idempotent, and
1158 * may even be safely called by multiple threads simultaneously with
1159 * the same argument. This routine returns a PRStatus value; if
1160 * successful, it will return PR_SUCCESS. On failure it will set an
1161 * error on the error stack and return PR_FAILURE.
1162 *
1163 * The error may be one of the following values:
1164 * NSS_ERROR_NO_MEMORY
1165 *
1166 * Return value:
1167 * PR_SUCCESS
1168 * PR_FAILURE
1169 */
1170
1171 #ifdef DEBUG
1172 NSS_EXTERN PRStatus
1173 nssPointerTracker_initialize
1174 (
1175 nssPointerTracker *tracker
1176 );
1177
1178 extern const NSSError NSS_ERROR_NO_MEMORY;
1179 #endif /* DEBUG */
1180
1181 /*
1182 * nssPointerTracker_finalize
1183 *
1184 * This method is only present in debug builds.
1185 *
1186 * This routine returns the nssPointerTracker object to the pre-
1187 * initialized state, releasing all resources used by the object.
1188 * It will *NOT* destroy the objects being tracked by the pointer
1189 * (should any remain), and therefore cannot be used to "sweep up"
1190 * remaining objects. This routine returns a PRStatus value; if
1191 * successful, it will return PR_SUCCES. On failure it will set an
1192 * error on the error stack and return PR_FAILURE. If any objects
1193 * remain in the tracker when it is finalized, that will be treated
1194 * as an error.
1195 *
1196 * The error may be one of the following values:
1197 * NSS_ERROR_TRACKER_NOT_EMPTY
1198 *
1199 * Return value:
1200 * PR_SUCCESS
1201 * PR_FAILURE
1202 */
1203
1204 #ifdef DEBUG
1205 NSS_EXTERN PRStatus
1206 nssPointerTracker_finalize
1207 (
1208 nssPointerTracker *tracker
1209 );
1210
1211 extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY;
1212 #endif /* DEBUG */
1213
1214 /*
1215 * nssPointerTracker_add
1216 *
1217 * This method is only present in debug builds.
1218 *
1219 * This routine adds the specified pointer to the nssPointerTracker
1220 * object. It should be called in constructor objects to register
1221 * new valid objects. The nssPointerTracker is threadsafe, but this
1222 * call is not idempotent. This routine returns a PRStatus value;
1223 * if successful it will return PR_SUCCESS. On failure it will set
1224 * an error on the error stack and return PR_FAILURE.
1225 *
1226 * The error may be one of the following values:
1227 * NSS_ERROR_NO_MEMORY
1228 * NSS_ERROR_TRACKER_NOT_INITIALIZED
1229 * NSS_ERROR_DUPLICATE_POINTER
1230 *
1231 * Return value:
1232 * PR_SUCCESS
1233 * PR_FAILURE
1234 */
1235
1236 #ifdef DEBUG
1237 NSS_EXTERN PRStatus
1238 nssPointerTracker_add
1239 (
1240 nssPointerTracker *tracker,
1241 const void *pointer
1242 );
1243
1244 extern const NSSError NSS_ERROR_NO_MEMORY;
1245 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
1246 extern const NSSError NSS_ERROR_DUPLICATE_POINTER;
1247 #endif /* DEBUG */
1248
1249 /*
1250 * nssPointerTracker_remove
1251 *
1252 * This method is only present in debug builds.
1253 *
1254 * This routine removes the specified pointer from the
1255 * nssPointerTracker object. It does not call any destructor for the
1256 * object; rather, this should be called from the object's destructor.
1257 * The nssPointerTracker is threadsafe, but this call is not
1258 * idempotent. This routine returns a PRStatus value; if successful
1259 * it will return PR_SUCCESS. On failure it will set an error on the
1260 * error stack and return PR_FAILURE.
1261 *
1262 * The error may be one of the following values:
1263 * NSS_ERROR_TRACKER_NOT_INITIALIZED
1264 * NSS_ERROR_POINTER_NOT_REGISTERED
1265 *
1266 * Return value:
1267 * PR_SUCCESS
1268 * PR_FAILURE
1269 */
1270
1271 #ifdef DEBUG
1272 NSS_EXTERN PRStatus
1273 nssPointerTracker_remove
1274 (
1275 nssPointerTracker *tracker,
1276 const void *pointer
1277 );
1278
1279 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
1280 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
1281 #endif /* DEBUG */
1282
1283 /*
1284 * nssPointerTracker_verify
1285 *
1286 * This method is only present in debug builds.
1287 *
1288 * This routine verifies that the specified pointer has been registered
1289 * with the nssPointerTracker object. The nssPointerTracker object is
1290 * threadsafe, and this call may be safely called from multiple threads
1291 * simultaneously with the same arguments. This routine returns a
1292 * PRStatus value; if the pointer is registered this will return
1293 * PR_SUCCESS. Otherwise it will set an error on the error stack and
1294 * return PR_FAILURE. Although the error is suitable for leaving on
1295 * the stack, callers may wish to augment the information available by
1296 * placing a more type-specific error on the stack.
1297 *
1298 * The error may be one of the following values:
1299 * NSS_ERROR_POINTER_NOT_REGISTERED
1300 *
1301 * Return value:
1302 * PR_SUCCESS
1303 * PR_FAILRUE
1304 */
1305
1306 #ifdef DEBUG
1307 NSS_EXTERN PRStatus
1308 nssPointerTracker_verify
1309 (
1310 nssPointerTracker *tracker,
1311 const void *pointer
1312 );
1313
1314 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
1315 #endif /* DEBUG */
1316
1317 /*
1318 * libc
1319 *
1320 * nsslibc_memcpy
1321 * nsslibc_memset
1322 * nsslibc_offsetof
1323 */
1324
1325 /*
1326 * nsslibc_memcpy
1327 *
1328 * Errors:
1329 * NSS_ERROR_INVALID_POINTER
1330 *
1331 * Return value:
1332 * NULL on error
1333 * The destination pointer on success
1334 */
1335
1336 NSS_EXTERN void *
1337 nsslibc_memcpy
1338 (
1339 void *dest,
1340 const void *source,
1341 PRUint32 n
1342 );
1343
1344 extern const NSSError NSS_ERROR_INVALID_POINTER;
1345
1346 /*
1347 * nsslibc_memset
1348 *
1349 * Errors:
1350 * NSS_ERROR_INVALID_POINTER
1351 *
1352 * Return value:
1353 * NULL on error
1354 * The destination pointer on success
1355 */
1356
1357 NSS_EXTERN void *
1358 nsslibc_memset
1359 (
1360 void *dest,
1361 PRUint8 byte,
1362 PRUint32 n
1363 );
1364
1365 extern const NSSError NSS_ERROR_INVALID_POINTER;
1366
1367 /*
1368 * nsslibc_memequal
1369 *
1370 * Errors:
1371 * NSS_ERROR_INVALID_POINTER
1372 *
1373 * Return value:
1374 * PR_TRUE if they match
1375 * PR_FALSE if they don't
1376 * PR_FALSE upon error
1377 */
1378
1379 NSS_EXTERN PRBool
1380 nsslibc_memequal
1381 (
1382 const void *a,
1383 const void *b,
1384 PRUint32 len,
1385 PRStatus *statusOpt
1386 );
1387
1388 extern const NSSError NSS_ERROR_INVALID_POINTER;
1389
1390 #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb)))
1391
1392 PR_END_EXTERN_C
1393
1394 #endif /* BASE_H */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial