path: root/mozilla/security/nss/lib/base/base.h

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is the Netscape security libraries.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1994-2000
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#ifndef BASE_H
#define BASE_H

#ifdef DEBUG
static const char BASE_CVS_ID[] = "@(#) $RCSfile: base.h,v $ $Revision: 1.20 $ $Date: 2008/05/10 01:03:14 $";
#endif /* DEBUG */

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