The Tor Browser / file revision

 /* This Source Code Form is subject to the terms of the Mozilla Public

  * License, v. 2.0. If a copy of the MPL was not distributed with this

  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

 #ifndef BASE_H

 #define BASE_H

 /*

  * base.h

  *

  * This header file contains basic prototypes and preprocessor 

  * definitions used throughout nss but not available publicly.

  */

 #ifndef BASET_H

 #include "baset.h"

 #endif /* BASET_H */

 #ifndef NSSBASE_H

 #include "nssbase.h"

 #endif /* NSSBASE_H */

 #include "plhash.h"

 PR_BEGIN_EXTERN_C

 /*

  * NSSArena

  *

  * The nonpublic methods relating to this type are:

  *

  *  nssArena_Create  -- constructor

  *  nssArena_Destroy

  *  nssArena_Mark

  *  nssArena_Release

  *  nssArena_Unmark

  *

  *  nss_ZAlloc

  *  nss_ZFreeIf

  *  nss_ZRealloc

  *

  * Additionally, there are some preprocessor macros:

  *

  *  nss_ZNEW

  *  nss_ZNEWARRAY

  *

  * In debug builds, the following calls are available:

  *

  *  nssArena_verifyPointer

  *  nssArena_registerDestructor

  *  nssArena_deregisterDestructor

  *

  * The following preprocessor macro is also always available:

  *

  *  nssArena_VERIFYPOINTER

  *

  * A constant PLHashAllocOps structure is available for users

  * of the NSPL PLHashTable routines.

  *

  *  nssArenaHashAllocOps

  */

 /*

  * nssArena_Create

  *

  * This routine creates a new memory arena.  This routine may return

  * NULL upon error, in which case it will have set an error on the 

  * error stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_NO_MEMORY

  *

  * Return value:

  *  NULL upon error

  *  A pointer to an NSSArena upon success

  */

 /*

  * XXX fgmr

  * Arenas can be named upon creation; this is mostly of use when

  * debugging.  Should we expose that here, allowing an optional

  * "const char *name" argument?  Should the public version of this

  * call (NSSArena_Create) have it too?

  */

 NSS_EXTERN NSSArena *

 nssArena_Create

 (

   void

 );

 extern const NSSError NSS_ERROR_NO_MEMORY;

 /*

  * nssArena_Destroy

  *

  * This routine will destroy the specified arena, freeing all memory

  * allocated from it.  This routine returns a PRStatus value; if 

  * successful, it will return PR_SUCCESS.  If unsuccessful, it will

  * set an error on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nssArena_Destroy

 (

   NSSArena *arena

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 /*

  * nssArena_Mark

  *

  * This routine "marks" the current state of an arena.  Space

  * allocated after the arena has been marked can be freed by

  * releasing the arena back to the mark with nssArena_Release,

  * or committed by calling nssArena_Unmark.  When successful, 

  * this routine returns a valid nssArenaMark pointer.  This 

  * routine may return NULL upon error, in which case it will 

  * have set an error on the error stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  NULL upon failure

  *  An nssArenaMark pointer upon success

  */

 NSS_EXTERN nssArenaMark *

 nssArena_Mark

 (

   NSSArena *arena

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_NO_MEMORY;

 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;

 /*

  * nssArena_Release

  *

  * This routine invalidates and releases all memory allocated from

  * the specified arena after the point at which the specified mark

  * was obtained.  This routine returns a PRStatus value; if successful,

  * it will return PR_SUCCESS.  If unsuccessful, it will set an error

  * on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_INVALID_ARENA_MARK

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nssArena_Release

 (

   NSSArena *arena,

   nssArenaMark *arenaMark

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;

 /*

  * nssArena_Unmark

  *

  * This routine "commits" the indicated mark and any marks after

  * it, making them unreleasable.  Note that any earlier marks can

  * still be released, and such a release will invalidate these

  * later unmarked regions.  If an arena is to be safely shared by

  * more than one thread, all marks must be either released or

  * unmarked.  This routine returns a PRStatus value; if successful,

  * it will return PR_SUCCESS.  If unsuccessful, it will set an error

  * on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_INVALID_ARENA_MARK

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nssArena_Unmark

 (

   NSSArena *arena,

   nssArenaMark *arenaMark

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;

 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;

 #ifdef ARENA_DESTRUCTOR_LIST

 /*

  * nssArena_registerDestructor

  *

  * This routine stores a pointer to a callback and an arbitrary

  * pointer-sized argument in the arena, at the current point in

  * the mark stack.  If the arena is destroyed, or an "earlier"

  * mark is released, then this destructor will be called at that

  * time.  Note that the destructor will be called with the arena

  * locked, which means the destructor may free memory in that

  * arena, but it may not allocate or cause to be allocated any

  * memory.  This callback facility was included to support our

  * debug-version pointer-tracker feature; overuse runs counter to

  * the the original intent of arenas.  This routine returns a 

  * PRStatus value; if successful, it will return PR_SUCCESS.  If 

  * unsuccessful, it will set an error on the error stack and 

  * return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nssArena_registerDestructor

 (

   NSSArena *arena,

   void (*destructor)(void *argument),

   void *arg

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_NO_MEMORY;

 /*

  * nssArena_deregisterDestructor

  *

  * This routine will remove the first destructor in the specified

  * arena which has the specified destructor and argument values.

  * The destructor will not be called.  This routine returns a

  * PRStatus value; if successful, it will return PR_SUCCESS.  If 

  * unsuccessful, it will set an error on the error stack and 

  * return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NOT_FOUND

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nssArena_deregisterDestructor

 (

   NSSArena *arena,

   void (*destructor)(void *argument),

   void *arg

 );

 extern const NSSError NSS_ERROR_INVALID_ITEM;

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_NOT_FOUND;

 #endif /* ARENA_DESTRUCTOR_LIST */

 /*

  * nss_ZAlloc

  *

  * This routine allocates and zeroes a section of memory of the 

  * size, and returns to the caller a pointer to that memory.  If

  * the optional arena argument is non-null, the memory will be

  * obtained from that arena; otherwise, the memory will be obtained

  * from the heap.  This routine may return NULL upon error, in

  * which case it will have set an error upon the error stack.  The

  * value specified for size may be zero; in which case a valid 

  * zero-length block of memory will be allocated.  This block may

  * be expanded by calling nss_ZRealloc.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  NULL upon error

  *  A pointer to the new segment of zeroed memory

  */

 NSS_EXTERN void *

 nss_ZAlloc

 (

   NSSArena *arenaOpt,

   PRUint32 size

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 extern const NSSError NSS_ERROR_NO_MEMORY;

 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;

 /*

  * nss_ZFreeIf

  *

  * If the specified pointer is non-null, then the region of memory 

  * to which it points -- which must have been allocated with 

  * nss_ZAlloc -- will be zeroed and released.  This routine 

  * returns a PRStatus value; if successful, it will return PR_SUCCESS.

  * If unsuccessful, it will set an error on the error stack and return 

  * PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 NSS_EXTERN PRStatus

 nss_ZFreeIf

 (

   void *pointer

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 /*

  * nss_ZRealloc

  *

  * This routine reallocates a block of memory obtained by calling

  * nss_ZAlloc or nss_ZRealloc.  The portion of memory 

  * between the new and old sizes -- which is either being newly

  * obtained or released -- is in either case zeroed.  This routine 

  * may return NULL upon failure, in which case it will have placed 

  * an error on the error stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  NULL upon error

  *  A pointer to the replacement segment of memory

  */

 NSS_EXTERN void *

 nss_ZRealloc

 (

   void *pointer,

   PRUint32 newSize

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 extern const NSSError NSS_ERROR_NO_MEMORY;

 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;

 /*

  * nss_ZNEW

  *

  * This preprocessor macro will allocate memory for a new object

  * of the specified type with nss_ZAlloc, and will cast the

  * return value appropriately.  If the optional arena argument is 

  * non-null, the memory will be obtained from that arena; otherwise, 

  * the memory will be obtained from the heap.  This routine may 

  * return NULL upon error, in which case it will have set an error 

  * upon the error stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  *

  * Return value:

  *  NULL upon error

  *  A pointer to the new segment of zeroed memory

  */

 /* The following line exceeds 72 characters, but emacs screws up if I split it. */

 #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type)))

 /*

  * nss_ZNEWARRAY

  *

  * This preprocessor macro will allocate memory for an array of

  * new objects, and will cast the return value appropriately.

  * If the optional arena argument is non-null, the memory will 

  * be obtained from that arena; otherwise, the memory will be 

  * obtained from the heap.  This routine may return NULL upon 

  * error, in which case it will have set an error upon the error 

  * stack.  The array size may be specified as zero.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  *

  * Return value:

  *  NULL upon error

  *  A pointer to the new segment of zeroed memory

  */

 /* The following line exceeds 72 characters, but emacs screws up if I split it. */

 #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity)))

 /*

  * nss_ZREALLOCARRAY

  *

  * This preprocessor macro will reallocate memory for an array of

  * new objects, and will cast the return value appropriately.

  * This routine may return NULL upon error, in which case it will 

  *  have set an error upon the error stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD

  *

  * Return value:

  *  NULL upon error

  *  A pointer to the replacement segment of memory

  */

 #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity)))

 /*

  * nssArena_verifyPointer

  *

  * This method is only present in debug builds.

  *

  * If the specified pointer is a valid pointer to an NSSArena object,

  * this routine will return PR_SUCCESS.  Otherwise, it will put an

  * error on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_ARENA

  *

  * Return value:

  *  PR_SUCCESS if the pointer is valid

  *  PR_FAILURE if it isn't

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssArena_verifyPointer

 (

   const NSSArena *arena

 );

 extern const NSSError NSS_ERROR_INVALID_ARENA;

 #endif /* DEBUG */

 /*

  * nssArena_VERIFYPOINTER

  *

  * This macro is always available.  In debug builds it will call

  * nssArena_verifyPointer; in non-debug builds, it will merely

  * check that the pointer is not null.  Note that in non-debug

  * builds it cannot place an error on the error stack.

  *

  * Return value:

  *  PR_SUCCESS if the pointer is valid

  *  PR_FAILURE if it isn't

  */

 #ifdef DEBUG

 #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p)

 #else /* DEBUG */

 /* The following line exceeds 72 characters, but emacs screws up if I split it. */

 #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS)

 #endif /* DEBUG */

 /*

  * Private function to be called by NSS_Shutdown to cleanup nssArena 

  * bookkeeping.

  */

 extern PRStatus

 nssArena_Shutdown(void);

 /*

  * nssArenaHashAllocOps

  *

  * This constant structure contains allocation callbacks designed for

  * use with the NSPL routine PL_NewHashTable.  For example:

  *

  *  NSSArena *hashTableArena = nssArena_Create();

  *  PLHashTable *t = PL_NewHashTable(n, hasher, key_compare, 

  *    value_compare, nssArenaHashAllocOps, hashTableArena);

  */

 NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps;

 /*

  * The error stack

  *

  * The nonpublic methods relating to the error stack are:

  *

  *  nss_SetError

  *  nss_ClearErrorStack

  */

 /*

  * nss_SetError

  *

  * This routine places a new error code on the top of the calling 

  * thread's error stack.  Calling this routine wiht an error code

  * of zero will clear the error stack.

  */

 NSS_EXTERN void

 nss_SetError

 (

   PRUint32 error

 );

 /*

  * nss_ClearErrorStack

  *

  * This routine clears the calling thread's error stack.

  */

 NSS_EXTERN void

 nss_ClearErrorStack

 (

   void

 );

 /*

  * nss_DestroyErrorStack

  *

  * This routine frees the calling thread's error stack.

  */

 NSS_EXTERN void

 nss_DestroyErrorStack

 (

   void

 );

 /*

  * NSSItem

  *

  * nssItem_Create

  * nssItem_Duplicate

  * nssItem_Equal

  */

 NSS_EXTERN NSSItem *

 nssItem_Create

 (

   NSSArena *arenaOpt,

   NSSItem *rvOpt,

   PRUint32 length,

   const void *data

 );

 NSS_EXTERN void

 nssItem_Destroy

 (

   NSSItem *item

 );

 NSS_EXTERN NSSItem *

 nssItem_Duplicate

 (

   NSSItem *obj,

   NSSArena *arenaOpt,

   NSSItem *rvOpt

 );

 NSS_EXTERN PRBool

 nssItem_Equal

 (

   const NSSItem *one,

   const NSSItem *two,

   PRStatus *statusOpt

 );

 /*

  * NSSUTF8

  *

  *  nssUTF8_CaseIgnoreMatch

  *  nssUTF8_Duplicate

  *  nssUTF8_Size

  *  nssUTF8_Length

  *  nssUTF8_CopyIntoFixedBuffer

  */

 /*

  * nssUTF8_CaseIgnoreMatch

  * 

  * Returns true if the two UTF8-encoded strings pointed to by the 

  * two specified NSSUTF8 pointers differ only in typcase.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  PR_TRUE if the strings match, ignoring case

  *  PR_FALSE if they don't

  *  PR_FALSE upon error

  */

 NSS_EXTERN PRBool

 nssUTF8_CaseIgnoreMatch

 (

   const NSSUTF8 *a,

   const NSSUTF8 *b,

   PRStatus *statusOpt

 );

 /*

  * nssUTF8_Duplicate

  *

  * This routine duplicates the UTF8-encoded string pointed to by the

  * specified NSSUTF8 pointer.  If the optional arenaOpt argument is

  * not null, the memory required will be obtained from that arena;

  * otherwise, the memory required will be obtained from the heap.

  * A pointer to the new string will be returned.  In case of error,

  * an error will be placed on the error stack and NULL will be 

  * returned.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_INVALID_ARENA

  *  NSS_ERROR_NO_MEMORY

  */

 NSS_EXTERN NSSUTF8 *

 nssUTF8_Duplicate

 (

   const NSSUTF8 *s,

   NSSArena *arenaOpt

 );

 /*

  * nssUTF8_PrintableMatch

  *

  * Returns true if the two Printable strings pointed to by the 

  * two specified NSSUTF8 pointers match when compared with the 

  * rules for Printable String (leading and trailing spaces are 

  * disregarded, extents of whitespace match irregardless of length, 

  * and case is not significant), then PR_TRUE will be returned.

  * Otherwise, PR_FALSE will be returned.  Upon failure, PR_FALSE

  * will be returned.  If the optional statusOpt argument is not

  * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that

  * location.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  PR_TRUE if the strings match, ignoring case

  *  PR_FALSE if they don't

  *  PR_FALSE upon error

  */

 NSS_EXTERN PRBool

 nssUTF8_PrintableMatch

 (

   const NSSUTF8 *a,

   const NSSUTF8 *b,

   PRStatus *statusOpt

 );

 /*

  * nssUTF8_Size

  *

  * This routine returns the length in bytes (including the terminating

  * null) of the UTF8-encoded string pointed to by the specified

  * NSSUTF8 pointer.  Zero is returned on error.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_VALUE_TOO_LARGE

  *

  * Return value:

  *  nonzero size of the string

  *  0 on error

  */

 NSS_EXTERN PRUint32

 nssUTF8_Size

 (

   const NSSUTF8 *s,

   PRStatus *statusOpt

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;

 /*

  * nssUTF8_Length

  *

  * This routine returns the length in characters (not including the

  * terminating null) of the UTF8-encoded string pointed to by the

  * specified NSSUTF8 pointer.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_VALUE_TOO_LARGE

  *  NSS_ERROR_INVALID_STRING

  *

  * Return value:

  *  length of the string (which may be zero)

  *  0 on error

  */

 NSS_EXTERN PRUint32

 nssUTF8_Length

 (

   const NSSUTF8 *s,

   PRStatus *statusOpt

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;

 extern const NSSError NSS_ERROR_INVALID_STRING;

 /*

  * nssUTF8_Create

  *

  * This routine creates a UTF8 string from a string in some other

  * format.  Some types of string may include embedded null characters,

  * so for them the length parameter must be used.  For string types

  * that are null-terminated, the length parameter is optional; if it

  * is zero, it will be ignored.  If the optional arena argument is

  * non-null, the memory used for the new string will be obtained from

  * that arena, otherwise it will be obtained from the heap.  This

  * routine may return NULL upon error, in which case it will have

  * placed an error on the error stack.

  *

  * The error may be one of the following:

  *  NSS_ERROR_INVALID_POINTER

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_UNSUPPORTED_TYPE

  *

  * Return value:

  *  NULL upon error

  *  A non-null pointer to a new UTF8 string otherwise

  */

 NSS_EXTERN NSSUTF8 *

 nssUTF8_Create

 (

   NSSArena *arenaOpt,

   nssStringType type,

   const void *inputString,

   PRUint32 size /* in bytes, not characters */

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 extern const NSSError NSS_ERROR_NO_MEMORY;

 extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE;

 NSS_EXTERN NSSItem *

 nssUTF8_GetEncoding

 (

   NSSArena *arenaOpt,

   NSSItem *rvOpt,

   nssStringType type,

   NSSUTF8 *string

 );

 /*

  * nssUTF8_CopyIntoFixedBuffer

  *

  * This will copy a UTF8 string into a fixed-length buffer, making 

  * sure that the all characters are valid.  Any remaining space will

  * be padded with the specified ASCII character, typically either 

  * null or space.

  *

  * Blah, blah, blah.

  */

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 extern const NSSError NSS_ERROR_INVALID_ARGUMENT;

 NSS_EXTERN PRStatus

 nssUTF8_CopyIntoFixedBuffer

 (

   NSSUTF8 *string,

   char *buffer,

   PRUint32 bufferSize,

   char pad

 );

 /*

  * nssUTF8_Equal

  *

  */

 NSS_EXTERN PRBool

 nssUTF8_Equal

 (

   const NSSUTF8 *a,

   const NSSUTF8 *b,

   PRStatus *statusOpt

 );

 /*

  * nssList

  *

  * The goal is to provide a simple, optionally threadsafe, linked list

  * class.  Since NSS did not seem to use the circularity of PRCList

  * much before, this provides a list that appears to be a linear,

  * NULL-terminated list.

  */

 /*

  * nssList_Create

  *

  * If threadsafe is true, the list will be locked during modifications

  * and traversals.

  */

 NSS_EXTERN nssList *

 nssList_Create

 (

   NSSArena *arenaOpt,

   PRBool threadSafe

 );

 /*

  * nssList_Destroy

  */

 NSS_EXTERN PRStatus

 nssList_Destroy

 (

   nssList *list

 );

 NSS_EXTERN void

 nssList_Clear

 (

   nssList *list, 

   nssListElementDestructorFunc destructor

 );

 /*

  * nssList_SetCompareFunction

  *

  * By default, two list elements will be compared by comparing their

  * data pointers.  By setting this function, the user can control

  * how elements are compared.

  */

 NSS_EXTERN void

 nssList_SetCompareFunction

 (

   nssList *list, 

   nssListCompareFunc compareFunc

 );

 /*

  * nssList_SetSortFunction

  *

  * Sort function to use for an ordered list.

  */

 NSS_EXTERN void

 nssList_SetSortFunction

 (

   nssList *list, 

   nssListSortFunc sortFunc

 );

 /*

  * nssList_Add

  */

 NSS_EXTERN PRStatus

 nssList_Add

 (

   nssList *list, 

   void *data

 );

 /*

  * nssList_AddUnique

  *

  * This will use the compare function to see if the element is already

  * in the list.

  */

 NSS_EXTERN PRStatus

 nssList_AddUnique

 (

   nssList *list, 

   void *data

 );

 /*

  * nssList_Remove

  *

  * Uses the compare function to locate the element and remove it.

  */

 NSS_EXTERN PRStatus

 nssList_Remove(nssList *list, void *data);

 /*

  * nssList_Get

  *

  * Uses the compare function to locate an element.  Also serves as

  * nssList_Exists.

  */

 NSS_EXTERN void *

 nssList_Get

 (

   nssList *list, 

   void *data

 );

 /*

  * nssList_Count

  */

 NSS_EXTERN PRUint32

 nssList_Count

 (

   nssList *list

 );

 /*

  * nssList_GetArray

  *

  * Fill rvArray, up to maxElements, with elements in the list.  The

  * array is NULL-terminated, so its allocated size must be maxElements + 1.

  */

 NSS_EXTERN PRStatus

 nssList_GetArray

 (

   nssList *list, 

   void **rvArray, 

   PRUint32 maxElements

 );

 /*

  * nssList_CreateIterator

  *

  * Create an iterator for list traversal.

  */

 NSS_EXTERN nssListIterator *

 nssList_CreateIterator

 (

   nssList *list

 );

 NSS_EXTERN nssList *

 nssList_Clone

 (

   nssList *list

 );

 /*

  * nssListIterator_Destroy

  */

 NSS_EXTERN void

 nssListIterator_Destroy

 (

   nssListIterator *iter

 );

 /*

  * nssListIterator_Start

  *

  * Begin a list iteration.  After this call, if the list is threadSafe,

  * the list is *locked*.

  */

 NSS_EXTERN void *

 nssListIterator_Start

 (

   nssListIterator *iter

 );

 /*

  * nssListIterator_Next

  *

  * Continue a list iteration.

  */

 NSS_EXTERN void *

 nssListIterator_Next

 (

   nssListIterator *iter

 );

 /*

  * nssListIterator_Finish

  *

  * Complete a list iteration.  This *must* be called in order for the

  * lock to be released.

  */

 NSS_EXTERN PRStatus

 nssListIterator_Finish

 (

   nssListIterator *iter

 );

 /*

  * nssHash

  *

  *  nssHash_Create

  *  nssHash_Destroy

  *  nssHash_Add

  *  nssHash_Remove

  *  nssHash_Count

  *  nssHash_Exists

  *  nssHash_Lookup

  *  nssHash_Iterate

  */

 /*

  * nssHash_Create

  *

  */

 NSS_EXTERN nssHash *

 nssHash_Create

 (

   NSSArena *arenaOpt,

   PRUint32 numBuckets,

   PLHashFunction keyHash,

   PLHashComparator keyCompare,

   PLHashComparator valueCompare

 );

 NSS_EXTERN nssHash *

 nssHash_CreatePointer

 (

   NSSArena *arenaOpt,

   PRUint32 numBuckets

 );

 NSS_EXTERN nssHash *

 nssHash_CreateString

 (

   NSSArena *arenaOpt,

   PRUint32 numBuckets

 );

 NSS_EXTERN nssHash *

 nssHash_CreateItem

 (

   NSSArena *arenaOpt,

   PRUint32 numBuckets

 );

 /*

  * nssHash_Destroy

  *

  */

 NSS_EXTERN void

 nssHash_Destroy

 (

   nssHash *hash

 );

 /*

  * nssHash_Add

  *

  */

 extern const NSSError NSS_ERROR_HASH_COLLISION;

 NSS_EXTERN PRStatus

 nssHash_Add

 (

   nssHash *hash,

   const void *key,

   const void *value

 );

 /*

  * nssHash_Remove

  *

  */

 NSS_EXTERN void

 nssHash_Remove

 (

   nssHash *hash,

   const void *it

 );

 /*

  * nssHash_Count

  *

  */

 NSS_EXTERN PRUint32

 nssHash_Count

 (

   nssHash *hash

 );

 /*

  * nssHash_Exists

  *

  */

 NSS_EXTERN PRBool

 nssHash_Exists

 (

   nssHash *hash,

   const void *it

 );

 /*

  * nssHash_Lookup

  *

  */

 NSS_EXTERN void *

 nssHash_Lookup

 (

   nssHash *hash,

   const void *it

 );

 /*

  * nssHash_Iterate

  *

  */

 NSS_EXTERN void

 nssHash_Iterate

 (

   nssHash *hash,

   nssHashIterator fcn,

   void *closure

 );

 /*

  * nssPointerTracker

  *

  * This type and these methods are only present in debug builds.

  * 

  * The nonpublic methods relating to this type are:

  *

  *  nssPointerTracker_initialize

  *  nssPointerTracker_finalize

  *  nssPointerTracker_add

  *  nssPointerTracker_remove

  *  nssPointerTracker_verify

  */

 /*

  * nssPointerTracker_initialize

  *

  * This method is only present in debug builds.

  * 

  * This routine initializes an nssPointerTracker object.  Note that

  * the object must have been declared *static* to guarantee that it

  * is in a zeroed state initially.  This routine is idempotent, and

  * may even be safely called by multiple threads simultaneously with 

  * the same argument.  This routine returns a PRStatus value; if 

  * successful, it will return PR_SUCCESS.  On failure it will set an 

  * error on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_NO_MEMORY

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssPointerTracker_initialize

 (

   nssPointerTracker *tracker

 );

 extern const NSSError NSS_ERROR_NO_MEMORY;

 #endif /* DEBUG */

 /*

  * nssPointerTracker_finalize

  *

  * This method is only present in debug builds.

  * 

  * This routine returns the nssPointerTracker object to the pre-

  * initialized state, releasing all resources used by the object.

  * It will *NOT* destroy the objects being tracked by the pointer

  * (should any remain), and therefore cannot be used to "sweep up"

  * remaining objects.  This routine returns a PRStatus value; if

  * successful, it will return PR_SUCCES.  On failure it will set an

  * error on the error stack and return PR_FAILURE.  If any objects

  * remain in the tracker when it is finalized, that will be treated

  * as an error.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_TRACKER_NOT_EMPTY

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssPointerTracker_finalize

 (

   nssPointerTracker *tracker

 );

 extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY;

 #endif /* DEBUG */

 /*

  * nssPointerTracker_add

  *

  * This method is only present in debug builds.

  *

  * This routine adds the specified pointer to the nssPointerTracker

  * object.  It should be called in constructor objects to register

  * new valid objects.  The nssPointerTracker is threadsafe, but this

  * call is not idempotent.  This routine returns a PRStatus value;

  * if successful it will return PR_SUCCESS.  On failure it will set

  * an error on the error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_NO_MEMORY

  *  NSS_ERROR_TRACKER_NOT_INITIALIZED

  *  NSS_ERROR_DUPLICATE_POINTER

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssPointerTracker_add

 (

   nssPointerTracker *tracker,

   const void *pointer

 );

 extern const NSSError NSS_ERROR_NO_MEMORY;

 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;

 extern const NSSError NSS_ERROR_DUPLICATE_POINTER;

 #endif /* DEBUG */

 /*

  * nssPointerTracker_remove

  *

  * This method is only present in debug builds.

  *

  * This routine removes the specified pointer from the 

  * nssPointerTracker object.  It does not call any destructor for the

  * object; rather, this should be called from the object's destructor.

  * The nssPointerTracker is threadsafe, but this call is not 

  * idempotent.  This routine returns a PRStatus value; if successful 

  * it will return PR_SUCCESS.  On failure it will set an error on the 

  * error stack and return PR_FAILURE.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_TRACKER_NOT_INITIALIZED

  *  NSS_ERROR_POINTER_NOT_REGISTERED

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILURE

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssPointerTracker_remove

 (

   nssPointerTracker *tracker,

   const void *pointer

 );

 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;

 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;

 #endif /* DEBUG */

 /*

  * nssPointerTracker_verify

  *

  * This method is only present in debug builds.

  *

  * This routine verifies that the specified pointer has been registered

  * with the nssPointerTracker object.  The nssPointerTracker object is

  * threadsafe, and this call may be safely called from multiple threads

  * simultaneously with the same arguments.  This routine returns a

  * PRStatus value; if the pointer is registered this will return 

  * PR_SUCCESS.  Otherwise it will set an error on the error stack and 

  * return PR_FAILURE.  Although the error is suitable for leaving on 

  * the stack, callers may wish to augment the information available by 

  * placing a more type-specific error on the stack.

  *

  * The error may be one of the following values:

  *  NSS_ERROR_POINTER_NOT_REGISTERED

  *

  * Return value:

  *  PR_SUCCESS

  *  PR_FAILRUE

  */

 #ifdef DEBUG

 NSS_EXTERN PRStatus

 nssPointerTracker_verify

 (

   nssPointerTracker *tracker,

   const void *pointer

 );

 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;

 #endif /* DEBUG */

 /*

  * libc

  *

  * nsslibc_memcpy

  * nsslibc_memset

  * nsslibc_offsetof

  */

 /*

  * nsslibc_memcpy

  *

  * Errors:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  NULL on error

  *  The destination pointer on success

  */

 NSS_EXTERN void *

 nsslibc_memcpy

 (

   void *dest,

   const void *source,

   PRUint32 n

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 /*

  * nsslibc_memset

  *

  * Errors:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  NULL on error

  *  The destination pointer on success

  */

 NSS_EXTERN void *

 nsslibc_memset

 (

   void *dest,

   PRUint8 byte,

   PRUint32 n

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 /*

  * nsslibc_memequal

  *

  * Errors:

  *  NSS_ERROR_INVALID_POINTER

  *

  * Return value:

  *  PR_TRUE if they match

  *  PR_FALSE if they don't

  *  PR_FALSE upon error

  */

 NSS_EXTERN PRBool

 nsslibc_memequal

 (

   const void *a,

   const void *b,

   PRUint32 len,

   PRStatus *statusOpt

 );

 extern const NSSError NSS_ERROR_INVALID_POINTER;

 #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb)))

 PR_END_EXTERN_C

 #endif /* BASE_H */