andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public
andre@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
andre@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
andre@0: 
andre@0: #ifndef BASE_H
andre@0: #define BASE_H
andre@0: 
andre@0: /*
andre@0:  * base.h
andre@0:  *
andre@0:  * This header file contains basic prototypes and preprocessor 
andre@0:  * definitions used throughout nss but not available publicly.
andre@0:  */
andre@0: 
andre@0: #ifndef BASET_H
andre@0: #include "baset.h"
andre@0: #endif /* BASET_H */
andre@0: 
andre@0: #ifndef NSSBASE_H
andre@0: #include "nssbase.h"
andre@0: #endif /* NSSBASE_H */
andre@0: 
andre@0: #include "plhash.h"
andre@0: 
andre@0: PR_BEGIN_EXTERN_C
andre@0: 
andre@0: /*
andre@0:  * NSSArena
andre@0:  *
andre@0:  * The nonpublic methods relating to this type are:
andre@0:  *
andre@0:  *  nssArena_Create  -- constructor
andre@0:  *  nssArena_Destroy
andre@0:  *  nssArena_Mark
andre@0:  *  nssArena_Release
andre@0:  *  nssArena_Unmark
andre@0:  *
andre@0:  *  nss_ZAlloc
andre@0:  *  nss_ZFreeIf
andre@0:  *  nss_ZRealloc
andre@0:  *
andre@0:  * Additionally, there are some preprocessor macros:
andre@0:  *
andre@0:  *  nss_ZNEW
andre@0:  *  nss_ZNEWARRAY
andre@0:  *
andre@0:  * In debug builds, the following calls are available:
andre@0:  *
andre@0:  *  nssArena_verifyPointer
andre@0:  *  nssArena_registerDestructor
andre@0:  *  nssArena_deregisterDestructor
andre@0:  *
andre@0:  * The following preprocessor macro is also always available:
andre@0:  *
andre@0:  *  nssArena_VERIFYPOINTER
andre@0:  *
andre@0:  * A constant PLHashAllocOps structure is available for users
andre@0:  * of the NSPL PLHashTable routines.
andre@0:  *
andre@0:  *  nssArenaHashAllocOps
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nssArena_Create
andre@0:  *
andre@0:  * This routine creates a new memory arena.  This routine may return
andre@0:  * NULL upon error, in which case it will have set an error on the 
andre@0:  * error stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to an NSSArena upon success
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * XXX fgmr
andre@0:  * Arenas can be named upon creation; this is mostly of use when
andre@0:  * debugging.  Should we expose that here, allowing an optional
andre@0:  * "const char *name" argument?  Should the public version of this
andre@0:  * call (NSSArena_Create) have it too?
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSArena *
andre@0: nssArena_Create
andre@0: (
andre@0:   void
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: 
andre@0: /*
andre@0:  * nssArena_Destroy
andre@0:  *
andre@0:  * This routine will destroy the specified arena, freeing all memory
andre@0:  * allocated from it.  This routine returns a PRStatus value; if 
andre@0:  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
andre@0:  * set an error on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_Destroy
andre@0: (
andre@0:   NSSArena *arena
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: 
andre@0: /*
andre@0:  * nssArena_Mark
andre@0:  *
andre@0:  * This routine "marks" the current state of an arena.  Space
andre@0:  * allocated after the arena has been marked can be freed by
andre@0:  * releasing the arena back to the mark with nssArena_Release,
andre@0:  * or committed by calling nssArena_Unmark.  When successful, 
andre@0:  * this routine returns a valid nssArenaMark pointer.  This 
andre@0:  * routine may return NULL upon error, in which case it will 
andre@0:  * have set an error on the error stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon failure
andre@0:  *  An nssArenaMark pointer upon success
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN nssArenaMark *
andre@0: nssArena_Mark
andre@0: (
andre@0:   NSSArena *arena
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
andre@0: 
andre@0: /*
andre@0:  * nssArena_Release
andre@0:  *
andre@0:  * This routine invalidates and releases all memory allocated from
andre@0:  * the specified arena after the point at which the specified mark
andre@0:  * was obtained.  This routine returns a PRStatus value; if successful,
andre@0:  * it will return PR_SUCCESS.  If unsuccessful, it will set an error
andre@0:  * on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_INVALID_ARENA_MARK
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_Release
andre@0: (
andre@0:   NSSArena *arena,
andre@0:   nssArenaMark *arenaMark
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
andre@0: 
andre@0: /*
andre@0:  * nssArena_Unmark
andre@0:  *
andre@0:  * This routine "commits" the indicated mark and any marks after
andre@0:  * it, making them unreleasable.  Note that any earlier marks can
andre@0:  * still be released, and such a release will invalidate these
andre@0:  * later unmarked regions.  If an arena is to be safely shared by
andre@0:  * more than one thread, all marks must be either released or
andre@0:  * unmarked.  This routine returns a PRStatus value; if successful,
andre@0:  * it will return PR_SUCCESS.  If unsuccessful, it will set an error
andre@0:  * on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_INVALID_ARENA_MARK
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_Unmark
andre@0: (
andre@0:   NSSArena *arena,
andre@0:   nssArenaMark *arenaMark
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
andre@0: extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
andre@0: 
andre@0: #ifdef ARENA_DESTRUCTOR_LIST
andre@0: 
andre@0: /*
andre@0:  * nssArena_registerDestructor
andre@0:  *
andre@0:  * This routine stores a pointer to a callback and an arbitrary
andre@0:  * pointer-sized argument in the arena, at the current point in
andre@0:  * the mark stack.  If the arena is destroyed, or an "earlier"
andre@0:  * mark is released, then this destructor will be called at that
andre@0:  * time.  Note that the destructor will be called with the arena
andre@0:  * locked, which means the destructor may free memory in that
andre@0:  * arena, but it may not allocate or cause to be allocated any
andre@0:  * memory.  This callback facility was included to support our
andre@0:  * debug-version pointer-tracker feature; overuse runs counter to
andre@0:  * the the original intent of arenas.  This routine returns a 
andre@0:  * PRStatus value; if successful, it will return PR_SUCCESS.  If 
andre@0:  * unsuccessful, it will set an error on the error stack and 
andre@0:  * return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_registerDestructor
andre@0: (
andre@0:   NSSArena *arena,
andre@0:   void (*destructor)(void *argument),
andre@0:   void *arg
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: 
andre@0: /*
andre@0:  * nssArena_deregisterDestructor
andre@0:  *
andre@0:  * This routine will remove the first destructor in the specified
andre@0:  * arena which has the specified destructor and argument values.
andre@0:  * The destructor will not be called.  This routine returns a
andre@0:  * PRStatus value; if successful, it will return PR_SUCCESS.  If 
andre@0:  * unsuccessful, it will set an error on the error stack and 
andre@0:  * return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NOT_FOUND
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_deregisterDestructor
andre@0: (
andre@0:   NSSArena *arena,
andre@0:   void (*destructor)(void *argument),
andre@0:   void *arg
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ITEM;
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_NOT_FOUND;
andre@0: 
andre@0: #endif /* ARENA_DESTRUCTOR_LIST */
andre@0: 
andre@0: /*
andre@0:  * nss_ZAlloc
andre@0:  *
andre@0:  * This routine allocates and zeroes a section of memory of the 
andre@0:  * size, and returns to the caller a pointer to that memory.  If
andre@0:  * the optional arena argument is non-null, the memory will be
andre@0:  * obtained from that arena; otherwise, the memory will be obtained
andre@0:  * from the heap.  This routine may return NULL upon error, in
andre@0:  * which case it will have set an error upon the error stack.  The
andre@0:  * value specified for size may be zero; in which case a valid 
andre@0:  * zero-length block of memory will be allocated.  This block may
andre@0:  * be expanded by calling nss_ZRealloc.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to the new segment of zeroed memory
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void *
andre@0: nss_ZAlloc
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRUint32 size
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
andre@0: 
andre@0: /*
andre@0:  * nss_ZFreeIf
andre@0:  *
andre@0:  * If the specified pointer is non-null, then the region of memory 
andre@0:  * to which it points -- which must have been allocated with 
andre@0:  * nss_ZAlloc -- will be zeroed and released.  This routine 
andre@0:  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
andre@0:  * If unsuccessful, it will set an error on the error stack and return 
andre@0:  * PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nss_ZFreeIf
andre@0: (
andre@0:   void *pointer
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: 
andre@0: /*
andre@0:  * nss_ZRealloc
andre@0:  *
andre@0:  * This routine reallocates a block of memory obtained by calling
andre@0:  * nss_ZAlloc or nss_ZRealloc.  The portion of memory 
andre@0:  * between the new and old sizes -- which is either being newly
andre@0:  * obtained or released -- is in either case zeroed.  This routine 
andre@0:  * may return NULL upon failure, in which case it will have placed 
andre@0:  * an error on the error stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to the replacement segment of memory
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void *
andre@0: nss_ZRealloc
andre@0: (
andre@0:   void *pointer,
andre@0:   PRUint32 newSize
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
andre@0: 
andre@0: /*
andre@0:  * nss_ZNEW
andre@0:  *
andre@0:  * This preprocessor macro will allocate memory for a new object
andre@0:  * of the specified type with nss_ZAlloc, and will cast the
andre@0:  * return value appropriately.  If the optional arena argument is 
andre@0:  * non-null, the memory will be obtained from that arena; otherwise, 
andre@0:  * the memory will be obtained from the heap.  This routine may 
andre@0:  * return NULL upon error, in which case it will have set an error 
andre@0:  * upon the error stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to the new segment of zeroed memory
andre@0:  */
andre@0: 
andre@0: /* The following line exceeds 72 characters, but emacs screws up if I split it. */
andre@0: #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type)))
andre@0: 
andre@0: /*
andre@0:  * nss_ZNEWARRAY
andre@0:  *
andre@0:  * This preprocessor macro will allocate memory for an array of
andre@0:  * new objects, and will cast the return value appropriately.
andre@0:  * If the optional arena argument is non-null, the memory will 
andre@0:  * be obtained from that arena; otherwise, the memory will be 
andre@0:  * obtained from the heap.  This routine may return NULL upon 
andre@0:  * error, in which case it will have set an error upon the error 
andre@0:  * stack.  The array size may be specified as zero.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to the new segment of zeroed memory
andre@0:  */
andre@0: 
andre@0: /* The following line exceeds 72 characters, but emacs screws up if I split it. */
andre@0: #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
andre@0: 
andre@0: /*
andre@0:  * nss_ZREALLOCARRAY
andre@0:  *
andre@0:  * This preprocessor macro will reallocate memory for an array of
andre@0:  * new objects, and will cast the return value appropriately.
andre@0:  * This routine may return NULL upon error, in which case it will 
andre@0:  *  have set an error upon the error stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A pointer to the replacement segment of memory
andre@0:  */
andre@0: #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity)))
andre@0: 
andre@0: /*
andre@0:  * nssArena_verifyPointer
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  *
andre@0:  * If the specified pointer is a valid pointer to an NSSArena object,
andre@0:  * this routine will return PR_SUCCESS.  Otherwise, it will put an
andre@0:  * error on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS if the pointer is valid
andre@0:  *  PR_FAILURE if it isn't
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssArena_verifyPointer
andre@0: (
andre@0:   const NSSArena *arena
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * nssArena_VERIFYPOINTER
andre@0:  *
andre@0:  * This macro is always available.  In debug builds it will call
andre@0:  * nssArena_verifyPointer; in non-debug builds, it will merely
andre@0:  * check that the pointer is not null.  Note that in non-debug
andre@0:  * builds it cannot place an error on the error stack.
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS if the pointer is valid
andre@0:  *  PR_FAILURE if it isn't
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p)
andre@0: #else /* DEBUG */
andre@0: /* The following line exceeds 72 characters, but emacs screws up if I split it. */
andre@0: #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS)
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * Private function to be called by NSS_Shutdown to cleanup nssArena 
andre@0:  * bookkeeping.
andre@0:  */
andre@0: extern PRStatus
andre@0: nssArena_Shutdown(void);
andre@0: 
andre@0: /*
andre@0:  * nssArenaHashAllocOps
andre@0:  *
andre@0:  * This constant structure contains allocation callbacks designed for
andre@0:  * use with the NSPL routine PL_NewHashTable.  For example:
andre@0:  *
andre@0:  *  NSSArena *hashTableArena = nssArena_Create();
andre@0:  *  PLHashTable *t = PL_NewHashTable(n, hasher, key_compare, 
andre@0:  *    value_compare, nssArenaHashAllocOps, hashTableArena);
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps;
andre@0: 
andre@0: /*
andre@0:  * The error stack
andre@0:  *
andre@0:  * The nonpublic methods relating to the error stack are:
andre@0:  *
andre@0:  *  nss_SetError
andre@0:  *  nss_ClearErrorStack
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nss_SetError
andre@0:  *
andre@0:  * This routine places a new error code on the top of the calling 
andre@0:  * thread's error stack.  Calling this routine wiht an error code
andre@0:  * of zero will clear the error stack.
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void
andre@0: nss_SetError
andre@0: (
andre@0:   PRUint32 error
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nss_ClearErrorStack
andre@0:  *
andre@0:  * This routine clears the calling thread's error stack.
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void
andre@0: nss_ClearErrorStack
andre@0: (
andre@0:   void
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nss_DestroyErrorStack
andre@0:  *
andre@0:  * This routine frees the calling thread's error stack.
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void
andre@0: nss_DestroyErrorStack
andre@0: (
andre@0:   void
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * NSSItem
andre@0:  *
andre@0:  * nssItem_Create
andre@0:  * nssItem_Duplicate
andre@0:  * nssItem_Equal
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSItem *
andre@0: nssItem_Create
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   NSSItem *rvOpt,
andre@0:   PRUint32 length,
andre@0:   const void *data
andre@0: );
andre@0: 
andre@0: NSS_EXTERN void
andre@0: nssItem_Destroy
andre@0: (
andre@0:   NSSItem *item
andre@0: );
andre@0: 
andre@0: NSS_EXTERN NSSItem *
andre@0: nssItem_Duplicate
andre@0: (
andre@0:   NSSItem *obj,
andre@0:   NSSArena *arenaOpt,
andre@0:   NSSItem *rvOpt
andre@0: );
andre@0: 
andre@0: NSS_EXTERN PRBool
andre@0: nssItem_Equal
andre@0: (
andre@0:   const NSSItem *one,
andre@0:   const NSSItem *two,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * NSSUTF8
andre@0:  *
andre@0:  *  nssUTF8_CaseIgnoreMatch
andre@0:  *  nssUTF8_Duplicate
andre@0:  *  nssUTF8_Size
andre@0:  *  nssUTF8_Length
andre@0:  *  nssUTF8_CopyIntoFixedBuffer
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_CaseIgnoreMatch
andre@0:  * 
andre@0:  * Returns true if the two UTF8-encoded strings pointed to by the 
andre@0:  * two specified NSSUTF8 pointers differ only in typcase.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_TRUE if the strings match, ignoring case
andre@0:  *  PR_FALSE if they don't
andre@0:  *  PR_FALSE upon error
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRBool
andre@0: nssUTF8_CaseIgnoreMatch
andre@0: (
andre@0:   const NSSUTF8 *a,
andre@0:   const NSSUTF8 *b,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_Duplicate
andre@0:  *
andre@0:  * This routine duplicates the UTF8-encoded string pointed to by the
andre@0:  * specified NSSUTF8 pointer.  If the optional arenaOpt argument is
andre@0:  * not null, the memory required will be obtained from that arena;
andre@0:  * otherwise, the memory required will be obtained from the heap.
andre@0:  * A pointer to the new string will be returned.  In case of error,
andre@0:  * an error will be placed on the error stack and NULL will be 
andre@0:  * returned.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSUTF8 *
andre@0: nssUTF8_Duplicate
andre@0: (
andre@0:   const NSSUTF8 *s,
andre@0:   NSSArena *arenaOpt
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_PrintableMatch
andre@0:  *
andre@0:  * Returns true if the two Printable strings pointed to by the 
andre@0:  * two specified NSSUTF8 pointers match when compared with the 
andre@0:  * rules for Printable String (leading and trailing spaces are 
andre@0:  * disregarded, extents of whitespace match irregardless of length, 
andre@0:  * and case is not significant), then PR_TRUE will be returned.
andre@0:  * Otherwise, PR_FALSE will be returned.  Upon failure, PR_FALSE
andre@0:  * will be returned.  If the optional statusOpt argument is not
andre@0:  * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that
andre@0:  * location.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_TRUE if the strings match, ignoring case
andre@0:  *  PR_FALSE if they don't
andre@0:  *  PR_FALSE upon error
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRBool
andre@0: nssUTF8_PrintableMatch
andre@0: (
andre@0:   const NSSUTF8 *a,
andre@0:   const NSSUTF8 *b,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_Size
andre@0:  *
andre@0:  * This routine returns the length in bytes (including the terminating
andre@0:  * null) of the UTF8-encoded string pointed to by the specified
andre@0:  * NSSUTF8 pointer.  Zero is returned on error.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_VALUE_TOO_LARGE
andre@0:  *
andre@0:  * Return value:
andre@0:  *  nonzero size of the string
andre@0:  *  0 on error
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRUint32
andre@0: nssUTF8_Size
andre@0: (
andre@0:   const NSSUTF8 *s,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_Length
andre@0:  *
andre@0:  * This routine returns the length in characters (not including the
andre@0:  * terminating null) of the UTF8-encoded string pointed to by the
andre@0:  * specified NSSUTF8 pointer.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_VALUE_TOO_LARGE
andre@0:  *  NSS_ERROR_INVALID_STRING
andre@0:  *
andre@0:  * Return value:
andre@0:  *  length of the string (which may be zero)
andre@0:  *  0 on error
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRUint32
andre@0: nssUTF8_Length
andre@0: (
andre@0:   const NSSUTF8 *s,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
andre@0: extern const NSSError NSS_ERROR_INVALID_STRING;
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_Create
andre@0:  *
andre@0:  * This routine creates a UTF8 string from a string in some other
andre@0:  * format.  Some types of string may include embedded null characters,
andre@0:  * so for them the length parameter must be used.  For string types
andre@0:  * that are null-terminated, the length parameter is optional; if it
andre@0:  * is zero, it will be ignored.  If the optional arena argument is
andre@0:  * non-null, the memory used for the new string will be obtained from
andre@0:  * that arena, otherwise it will be obtained from the heap.  This
andre@0:  * routine may return NULL upon error, in which case it will have
andre@0:  * placed an error on the error stack.
andre@0:  *
andre@0:  * The error may be one of the following:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_UNSUPPORTED_TYPE
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error
andre@0:  *  A non-null pointer to a new UTF8 string otherwise
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSUTF8 *
andre@0: nssUTF8_Create
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   nssStringType type,
andre@0:   const void *inputString,
andre@0:   PRUint32 size /* in bytes, not characters */
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE;
andre@0: 
andre@0: NSS_EXTERN NSSItem *
andre@0: nssUTF8_GetEncoding
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   NSSItem *rvOpt,
andre@0:   nssStringType type,
andre@0:   NSSUTF8 *string
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_CopyIntoFixedBuffer
andre@0:  *
andre@0:  * This will copy a UTF8 string into a fixed-length buffer, making 
andre@0:  * sure that the all characters are valid.  Any remaining space will
andre@0:  * be padded with the specified ASCII character, typically either 
andre@0:  * null or space.
andre@0:  *
andre@0:  * Blah, blah, blah.
andre@0:  */
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssUTF8_CopyIntoFixedBuffer
andre@0: (
andre@0:   NSSUTF8 *string,
andre@0:   char *buffer,
andre@0:   PRUint32 bufferSize,
andre@0:   char pad
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssUTF8_Equal
andre@0:  *
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRBool
andre@0: nssUTF8_Equal
andre@0: (
andre@0:   const NSSUTF8 *a,
andre@0:   const NSSUTF8 *b,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList
andre@0:  *
andre@0:  * The goal is to provide a simple, optionally threadsafe, linked list
andre@0:  * class.  Since NSS did not seem to use the circularity of PRCList
andre@0:  * much before, this provides a list that appears to be a linear,
andre@0:  * NULL-terminated list.
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nssList_Create
andre@0:  *
andre@0:  * If threadsafe is true, the list will be locked during modifications
andre@0:  * and traversals.
andre@0:  */
andre@0: NSS_EXTERN nssList *
andre@0: nssList_Create
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRBool threadSafe
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_Destroy
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssList_Destroy
andre@0: (
andre@0:   nssList *list
andre@0: );
andre@0: 
andre@0: NSS_EXTERN void
andre@0: nssList_Clear
andre@0: (
andre@0:   nssList *list, 
andre@0:   nssListElementDestructorFunc destructor
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_SetCompareFunction
andre@0:  *
andre@0:  * By default, two list elements will be compared by comparing their
andre@0:  * data pointers.  By setting this function, the user can control
andre@0:  * how elements are compared.
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssList_SetCompareFunction
andre@0: (
andre@0:   nssList *list, 
andre@0:   nssListCompareFunc compareFunc
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_SetSortFunction
andre@0:  *
andre@0:  * Sort function to use for an ordered list.
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssList_SetSortFunction
andre@0: (
andre@0:   nssList *list, 
andre@0:   nssListSortFunc sortFunc
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_Add
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssList_Add
andre@0: (
andre@0:   nssList *list, 
andre@0:   void *data
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_AddUnique
andre@0:  *
andre@0:  * This will use the compare function to see if the element is already
andre@0:  * in the list.
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssList_AddUnique
andre@0: (
andre@0:   nssList *list, 
andre@0:   void *data
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_Remove
andre@0:  *
andre@0:  * Uses the compare function to locate the element and remove it.
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssList_Remove(nssList *list, void *data);
andre@0: 
andre@0: /*
andre@0:  * nssList_Get
andre@0:  *
andre@0:  * Uses the compare function to locate an element.  Also serves as
andre@0:  * nssList_Exists.
andre@0:  */
andre@0: NSS_EXTERN void *
andre@0: nssList_Get
andre@0: (
andre@0:   nssList *list, 
andre@0:   void *data
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_Count
andre@0:  */
andre@0: NSS_EXTERN PRUint32
andre@0: nssList_Count
andre@0: (
andre@0:   nssList *list
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_GetArray
andre@0:  *
andre@0:  * Fill rvArray, up to maxElements, with elements in the list.  The
andre@0:  * array is NULL-terminated, so its allocated size must be maxElements + 1.
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssList_GetArray
andre@0: (
andre@0:   nssList *list, 
andre@0:   void **rvArray, 
andre@0:   PRUint32 maxElements
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssList_CreateIterator
andre@0:  *
andre@0:  * Create an iterator for list traversal.
andre@0:  */
andre@0: NSS_EXTERN nssListIterator *
andre@0: nssList_CreateIterator
andre@0: (
andre@0:   nssList *list
andre@0: );
andre@0: 
andre@0: NSS_EXTERN nssList *
andre@0: nssList_Clone
andre@0: (
andre@0:   nssList *list
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssListIterator_Destroy
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssListIterator_Destroy
andre@0: (
andre@0:   nssListIterator *iter
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssListIterator_Start
andre@0:  *
andre@0:  * Begin a list iteration.  After this call, if the list is threadSafe,
andre@0:  * the list is *locked*.
andre@0:  */
andre@0: NSS_EXTERN void *
andre@0: nssListIterator_Start
andre@0: (
andre@0:   nssListIterator *iter
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssListIterator_Next
andre@0:  *
andre@0:  * Continue a list iteration.
andre@0:  */
andre@0: NSS_EXTERN void *
andre@0: nssListIterator_Next
andre@0: (
andre@0:   nssListIterator *iter
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssListIterator_Finish
andre@0:  *
andre@0:  * Complete a list iteration.  This *must* be called in order for the
andre@0:  * lock to be released.
andre@0:  */
andre@0: NSS_EXTERN PRStatus
andre@0: nssListIterator_Finish
andre@0: (
andre@0:   nssListIterator *iter
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash
andre@0:  *
andre@0:  *  nssHash_Create
andre@0:  *  nssHash_Destroy
andre@0:  *  nssHash_Add
andre@0:  *  nssHash_Remove
andre@0:  *  nssHash_Count
andre@0:  *  nssHash_Exists
andre@0:  *  nssHash_Lookup
andre@0:  *  nssHash_Iterate
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nssHash_Create
andre@0:  *
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN nssHash *
andre@0: nssHash_Create
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRUint32 numBuckets,
andre@0:   PLHashFunction keyHash,
andre@0:   PLHashComparator keyCompare,
andre@0:   PLHashComparator valueCompare
andre@0: );
andre@0: 
andre@0: NSS_EXTERN nssHash *
andre@0: nssHash_CreatePointer
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRUint32 numBuckets
andre@0: );
andre@0: 
andre@0: NSS_EXTERN nssHash *
andre@0: nssHash_CreateString
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRUint32 numBuckets
andre@0: );
andre@0: 
andre@0: NSS_EXTERN nssHash *
andre@0: nssHash_CreateItem
andre@0: (
andre@0:   NSSArena *arenaOpt,
andre@0:   PRUint32 numBuckets
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Destroy
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssHash_Destroy
andre@0: (
andre@0:   nssHash *hash
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Add
andre@0:  *
andre@0:  */
andre@0: 
andre@0: extern const NSSError NSS_ERROR_HASH_COLLISION;
andre@0: 
andre@0: NSS_EXTERN PRStatus
andre@0: nssHash_Add
andre@0: (
andre@0:   nssHash *hash,
andre@0:   const void *key,
andre@0:   const void *value
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Remove
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssHash_Remove
andre@0: (
andre@0:   nssHash *hash,
andre@0:   const void *it
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Count
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN PRUint32
andre@0: nssHash_Count
andre@0: (
andre@0:   nssHash *hash
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Exists
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN PRBool
andre@0: nssHash_Exists
andre@0: (
andre@0:   nssHash *hash,
andre@0:   const void *it
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Lookup
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN void *
andre@0: nssHash_Lookup
andre@0: (
andre@0:   nssHash *hash,
andre@0:   const void *it
andre@0: );
andre@0: 
andre@0: /*
andre@0:  * nssHash_Iterate
andre@0:  *
andre@0:  */
andre@0: NSS_EXTERN void
andre@0: nssHash_Iterate
andre@0: (
andre@0:   nssHash *hash,
andre@0:   nssHashIterator fcn,
andre@0:   void *closure
andre@0: );
andre@0: 
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker
andre@0:  *
andre@0:  * This type and these methods are only present in debug builds.
andre@0:  * 
andre@0:  * The nonpublic methods relating to this type are:
andre@0:  *
andre@0:  *  nssPointerTracker_initialize
andre@0:  *  nssPointerTracker_finalize
andre@0:  *  nssPointerTracker_add
andre@0:  *  nssPointerTracker_remove
andre@0:  *  nssPointerTracker_verify
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker_initialize
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  * 
andre@0:  * This routine initializes an nssPointerTracker object.  Note that
andre@0:  * the object must have been declared *static* to guarantee that it
andre@0:  * is in a zeroed state initially.  This routine is idempotent, and
andre@0:  * may even be safely called by multiple threads simultaneously with 
andre@0:  * the same argument.  This routine returns a PRStatus value; if 
andre@0:  * successful, it will return PR_SUCCESS.  On failure it will set an 
andre@0:  * error on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssPointerTracker_initialize
andre@0: (
andre@0:   nssPointerTracker *tracker
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker_finalize
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  * 
andre@0:  * This routine returns the nssPointerTracker object to the pre-
andre@0:  * initialized state, releasing all resources used by the object.
andre@0:  * It will *NOT* destroy the objects being tracked by the pointer
andre@0:  * (should any remain), and therefore cannot be used to "sweep up"
andre@0:  * remaining objects.  This routine returns a PRStatus value; if
andre@0:  * successful, it will return PR_SUCCES.  On failure it will set an
andre@0:  * error on the error stack and return PR_FAILURE.  If any objects
andre@0:  * remain in the tracker when it is finalized, that will be treated
andre@0:  * as an error.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_TRACKER_NOT_EMPTY
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssPointerTracker_finalize
andre@0: (
andre@0:   nssPointerTracker *tracker
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker_add
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  *
andre@0:  * This routine adds the specified pointer to the nssPointerTracker
andre@0:  * object.  It should be called in constructor objects to register
andre@0:  * new valid objects.  The nssPointerTracker is threadsafe, but this
andre@0:  * call is not idempotent.  This routine returns a PRStatus value;
andre@0:  * if successful it will return PR_SUCCESS.  On failure it will set
andre@0:  * an error on the error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_NO_MEMORY
andre@0:  *  NSS_ERROR_TRACKER_NOT_INITIALIZED
andre@0:  *  NSS_ERROR_DUPLICATE_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssPointerTracker_add
andre@0: (
andre@0:   nssPointerTracker *tracker,
andre@0:   const void *pointer
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_NO_MEMORY;
andre@0: extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
andre@0: extern const NSSError NSS_ERROR_DUPLICATE_POINTER;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker_remove
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  *
andre@0:  * This routine removes the specified pointer from the 
andre@0:  * nssPointerTracker object.  It does not call any destructor for the
andre@0:  * object; rather, this should be called from the object's destructor.
andre@0:  * The nssPointerTracker is threadsafe, but this call is not 
andre@0:  * idempotent.  This routine returns a PRStatus value; if successful 
andre@0:  * it will return PR_SUCCESS.  On failure it will set an error on the 
andre@0:  * error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_TRACKER_NOT_INITIALIZED
andre@0:  *  NSS_ERROR_POINTER_NOT_REGISTERED
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILURE
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssPointerTracker_remove
andre@0: (
andre@0:   nssPointerTracker *tracker,
andre@0:   const void *pointer
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
andre@0: extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * nssPointerTracker_verify
andre@0:  *
andre@0:  * This method is only present in debug builds.
andre@0:  *
andre@0:  * This routine verifies that the specified pointer has been registered
andre@0:  * with the nssPointerTracker object.  The nssPointerTracker object is
andre@0:  * threadsafe, and this call may be safely called from multiple threads
andre@0:  * simultaneously with the same arguments.  This routine returns a
andre@0:  * PRStatus value; if the pointer is registered this will return 
andre@0:  * PR_SUCCESS.  Otherwise it will set an error on the error stack and 
andre@0:  * return PR_FAILURE.  Although the error is suitable for leaving on 
andre@0:  * the stack, callers may wish to augment the information available by 
andre@0:  * placing a more type-specific error on the stack.
andre@0:  *
andre@0:  * The error may be one of the following values:
andre@0:  *  NSS_ERROR_POINTER_NOT_REGISTERED
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS
andre@0:  *  PR_FAILRUE
andre@0:  */
andre@0: 
andre@0: #ifdef DEBUG
andre@0: NSS_EXTERN PRStatus
andre@0: nssPointerTracker_verify
andre@0: (
andre@0:   nssPointerTracker *tracker,
andre@0:   const void *pointer
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
andre@0: #endif /* DEBUG */
andre@0: 
andre@0: /*
andre@0:  * libc
andre@0:  *
andre@0:  * nsslibc_memcpy
andre@0:  * nsslibc_memset
andre@0:  * nsslibc_offsetof
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * nsslibc_memcpy
andre@0:  *
andre@0:  * Errors:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL on error
andre@0:  *  The destination pointer on success
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void *
andre@0: nsslibc_memcpy
andre@0: (
andre@0:   void *dest,
andre@0:   const void *source,
andre@0:   PRUint32 n
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: 
andre@0: /*
andre@0:  * nsslibc_memset
andre@0:  *
andre@0:  * Errors:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL on error
andre@0:  *  The destination pointer on success
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN void *
andre@0: nsslibc_memset
andre@0: (
andre@0:   void *dest,
andre@0:   PRUint8 byte,
andre@0:   PRUint32 n
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: 
andre@0: /*
andre@0:  * nsslibc_memequal
andre@0:  *
andre@0:  * Errors:
andre@0:  *  NSS_ERROR_INVALID_POINTER
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_TRUE if they match
andre@0:  *  PR_FALSE if they don't
andre@0:  *  PR_FALSE upon error
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN PRBool
andre@0: nsslibc_memequal
andre@0: (
andre@0:   const void *a,
andre@0:   const void *b,
andre@0:   PRUint32 len,
andre@0:   PRStatus *statusOpt
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_INVALID_POINTER;
andre@0: 
andre@0: #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb)))
andre@0: 
andre@0: PR_END_EXTERN_C
andre@0: 
andre@0: #endif /* BASE_H */