michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef NSSBASE_H
michael@0: #define NSSBASE_H
michael@0: 
michael@0: /*
michael@0:  * nssbase.h
michael@0:  *
michael@0:  * This header file contains the prototypes of the basic public
michael@0:  * NSS routines.
michael@0:  */
michael@0: 
michael@0: #ifndef NSSBASET_H
michael@0: #include "nssbaset.h"
michael@0: #endif /* NSSBASET_H */
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: 
michael@0: /*
michael@0:  * NSSArena
michael@0:  *
michael@0:  * The public methods relating to this type are:
michael@0:  *
michael@0:  *  NSSArena_Create  -- constructor
michael@0:  *  NSSArena_Destroy
michael@0:  *  NSS_ZAlloc
michael@0:  *  NSS_ZRealloc
michael@0:  *  NSS_ZFreeIf
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * NSSArena_Create
michael@0:  *
michael@0:  * This routine creates a new memory arena.  This routine may return
michael@0:  * NULL upon error, in which case it will have created an error stack.
michael@0:  *
michael@0:  * The top-level error may be one of the following values:
michael@0:  *  NSS_ERROR_NO_MEMORY
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error
michael@0:  *  A pointer to an NSSArena upon success
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN NSSArena *
michael@0: NSSArena_Create
michael@0: (
michael@0:   void
michael@0: );
michael@0: 
michael@0: extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0: 
michael@0: /*
michael@0:  * NSSArena_Destroy
michael@0:  *
michael@0:  * This routine will destroy the specified arena, freeing all memory
michael@0:  * allocated from it.  This routine returns a PRStatus value; if 
michael@0:  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
michael@0:  * create an error stack and return PR_FAILURE.
michael@0:  *
michael@0:  * The top-level error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_ARENA
michael@0:  *
michael@0:  * Return value:
michael@0:  *  PR_SUCCESS upon success
michael@0:  *  PR_FAILURE upon failure
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN PRStatus
michael@0: NSSArena_Destroy
michael@0: (
michael@0:   NSSArena *arena
michael@0: );
michael@0: 
michael@0: extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0: 
michael@0: /*
michael@0:  * The error stack
michael@0:  *
michael@0:  * The public methods relating to the error stack are:
michael@0:  *
michael@0:  *  NSS_GetError
michael@0:  *  NSS_GetErrorStack
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * NSS_GetError
michael@0:  *
michael@0:  * This routine returns the highest-level (most general) error set
michael@0:  * by the most recent NSS library routine called by the same thread
michael@0:  * calling this routine.
michael@0:  *
michael@0:  * This routine cannot fail.  It may return NSS_ERROR_NO_ERROR, which
michael@0:  * indicates that the previous NSS library call did not set an error.
michael@0:  *
michael@0:  * Return value:
michael@0:  *  0 if no error has been set
michael@0:  *  A nonzero error number
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN NSSError
michael@0: NSS_GetError
michael@0: (
michael@0:   void
michael@0: );
michael@0: 
michael@0: extern const NSSError NSS_ERROR_NO_ERROR;
michael@0: 
michael@0: /*
michael@0:  * NSS_GetErrorStack
michael@0:  *
michael@0:  * This routine returns a pointer to an array of NSSError values, 
michael@0:  * containingthe entire sequence or "stack" of errors set by the most 
michael@0:  * recent NSS library routine called by the same thread calling this 
michael@0:  * routine.  NOTE: the caller DOES NOT OWN the memory pointed to by 
michael@0:  * the return value.  The pointer will remain valid until the calling 
michael@0:  * thread calls another NSS routine.  The lowest-level (most specific) 
michael@0:  * error is first in the array, and the highest-level is last.  The 
michael@0:  * array is zero-terminated.  This routine may return NULL upon error; 
michael@0:  * this indicates a low-memory situation.
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error, which is an implied NSS_ERROR_NO_MEMORY
michael@0:  *  A NON-caller-owned pointer to an array of NSSError values
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN NSSError *
michael@0: NSS_GetErrorStack
michael@0: (
michael@0:   void
michael@0: );
michael@0: 
michael@0: /*
michael@0:  * NSS_ZNEW
michael@0:  *
michael@0:  * This preprocessor macro will allocate memory for a new object
michael@0:  * of the specified type with nss_ZAlloc, and will cast the
michael@0:  * return value appropriately.  If the optional arena argument is 
michael@0:  * non-null, the memory will be obtained from that arena; otherwise, 
michael@0:  * the memory will be obtained from the heap.  This routine may 
michael@0:  * return NULL upon error, in which case it will have set an error 
michael@0:  * upon the error stack.
michael@0:  *
michael@0:  * The error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_ARENA
michael@0:  *  NSS_ERROR_NO_MEMORY
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error
michael@0:  *  A pointer to the new segment of zeroed memory
michael@0:  */
michael@0: 
michael@0: /* The following line exceeds 72 characters, but emacs barfs if we split it. */
michael@0: #define NSS_ZNEW(arenaOpt, type) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type)))
michael@0: 
michael@0: /*
michael@0:  * NSS_ZNEWARRAY
michael@0:  *
michael@0:  * This preprocessor macro will allocate memory for an array of
michael@0:  * new objects, and will cast the return value appropriately.
michael@0:  * If the optional arena argument is non-null, the memory will 
michael@0:  * be obtained from that arena; otherwise, the memory will be 
michael@0:  * obtained from the heap.  This routine may return NULL upon 
michael@0:  * error, in which case it will have set an error upon the error 
michael@0:  * stack.  The array size may be specified as zero.
michael@0:  *
michael@0:  * The error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_ARENA
michael@0:  *  NSS_ERROR_NO_MEMORY
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error
michael@0:  *  A pointer to the new segment of zeroed memory
michael@0:  */
michael@0: 
michael@0: /* The following line exceeds 72 characters, but emacs barfs if we split it. */
michael@0: #define NSS_ZNEWARRAY(arenaOpt, type, quantity) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
michael@0: 
michael@0: 
michael@0: /*
michael@0:  * NSS_ZAlloc
michael@0:  *
michael@0:  * This routine allocates and zeroes a section of memory of the 
michael@0:  * size, and returns to the caller a pointer to that memory.  If
michael@0:  * the optional arena argument is non-null, the memory will be
michael@0:  * obtained from that arena; otherwise, the memory will be obtained
michael@0:  * from the heap.  This routine may return NULL upon error, in
michael@0:  * which case it will have set an error upon the error stack.  The
michael@0:  * value specified for size may be zero; in which case a valid 
michael@0:  * zero-length block of memory will be allocated.  This block may
michael@0:  * be expanded by calling NSS_ZRealloc.
michael@0:  *
michael@0:  * The error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_ARENA
michael@0:  *  NSS_ERROR_NO_MEMORY
michael@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error
michael@0:  *  A pointer to the new segment of zeroed memory
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN void *
michael@0: NSS_ZAlloc
michael@0: (
michael@0:   NSSArena *arenaOpt,
michael@0:   PRUint32 size
michael@0: );
michael@0: 
michael@0: /*
michael@0:  * NSS_ZRealloc
michael@0:  *
michael@0:  * This routine reallocates a block of memory obtained by calling
michael@0:  * nss_ZAlloc or nss_ZRealloc.  The portion of memory 
michael@0:  * between the new and old sizes -- which is either being newly
michael@0:  * obtained or released -- is in either case zeroed.  This routine 
michael@0:  * may return NULL upon failure, in which case it will have placed 
michael@0:  * an error on the error stack.
michael@0:  *
michael@0:  * The error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_POINTER
michael@0:  *  NSS_ERROR_NO_MEMORY
michael@0:  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0:  *
michael@0:  * Return value:
michael@0:  *  NULL upon error
michael@0:  *  A pointer to the replacement segment of memory
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN void *
michael@0: NSS_ZRealloc
michael@0: (
michael@0:   void *pointer,
michael@0:   PRUint32 newSize
michael@0: );
michael@0: 
michael@0: 
michael@0: /*
michael@0:  * NSS_ZFreeIf
michael@0:  *
michael@0:  * If the specified pointer is non-null, then the region of memory
michael@0:  * to which it points -- which must have been allocated with
michael@0:  * nss_ZAlloc -- will be zeroed and released.  This routine
michael@0:  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
michael@0:  * If unsuccessful, it will set an error on the error stack and return
michael@0:  * PR_FAILURE.
michael@0:  *
michael@0:  * The error may be one of the following values:
michael@0:  *  NSS_ERROR_INVALID_POINTER
michael@0:  *
michael@0:  * Return value:
michael@0:  *  PR_SUCCESS
michael@0:  *  PR_FAILURE
michael@0:  */
michael@0: 
michael@0: NSS_EXTERN PRStatus
michael@0: NSS_ZFreeIf
michael@0: (
michael@0:   void *pointer
michael@0: );
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* NSSBASE_H */