← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/security/nss/lib/base/base.h

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

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