/* 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

 */

#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

 */

#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 */

#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 */