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 NSSBASE_H
andre@0: #define NSSBASE_H
andre@0: 
andre@0: /*
andre@0:  * nssbase.h
andre@0:  *
andre@0:  * This header file contains the prototypes of the basic public
andre@0:  * NSS routines.
andre@0:  */
andre@0: 
andre@0: #ifndef NSSBASET_H
andre@0: #include "nssbaset.h"
andre@0: #endif /* NSSBASET_H */
andre@0: 
andre@0: PR_BEGIN_EXTERN_C
andre@0: 
andre@0: /*
andre@0:  * NSSArena
andre@0:  *
andre@0:  * The public methods relating to this type are:
andre@0:  *
andre@0:  *  NSSArena_Create  -- constructor
andre@0:  *  NSSArena_Destroy
andre@0:  *  NSS_ZAlloc
andre@0:  *  NSS_ZRealloc
andre@0:  *  NSS_ZFreeIf
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 created an error stack.
andre@0:  *
andre@0:  * The top-level 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: 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:  * create an error stack and return PR_FAILURE.
andre@0:  *
andre@0:  * The top-level error may be one of the following values:
andre@0:  *  NSS_ERROR_INVALID_ARENA
andre@0:  *
andre@0:  * Return value:
andre@0:  *  PR_SUCCESS upon success
andre@0:  *  PR_FAILURE upon 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:  * The error stack
andre@0:  *
andre@0:  * The public methods relating to the error stack are:
andre@0:  *
andre@0:  *  NSS_GetError
andre@0:  *  NSS_GetErrorStack
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * NSS_GetError
andre@0:  *
andre@0:  * This routine returns the highest-level (most general) error set
andre@0:  * by the most recent NSS library routine called by the same thread
andre@0:  * calling this routine.
andre@0:  *
andre@0:  * This routine cannot fail.  It may return NSS_ERROR_NO_ERROR, which
andre@0:  * indicates that the previous NSS library call did not set an error.
andre@0:  *
andre@0:  * Return value:
andre@0:  *  0 if no error has been set
andre@0:  *  A nonzero error number
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSError
andre@0: NSS_GetError
andre@0: (
andre@0:   void
andre@0: );
andre@0: 
andre@0: extern const NSSError NSS_ERROR_NO_ERROR;
andre@0: 
andre@0: /*
andre@0:  * NSS_GetErrorStack
andre@0:  *
andre@0:  * This routine returns a pointer to an array of NSSError values, 
andre@0:  * containingthe entire sequence or "stack" of errors set by the most 
andre@0:  * recent NSS library routine called by the same thread calling this 
andre@0:  * routine.  NOTE: the caller DOES NOT OWN the memory pointed to by 
andre@0:  * the return value.  The pointer will remain valid until the calling 
andre@0:  * thread calls another NSS routine.  The lowest-level (most specific) 
andre@0:  * error is first in the array, and the highest-level is last.  The 
andre@0:  * array is zero-terminated.  This routine may return NULL upon error; 
andre@0:  * this indicates a low-memory situation.
andre@0:  *
andre@0:  * Return value:
andre@0:  *  NULL upon error, which is an implied NSS_ERROR_NO_MEMORY
andre@0:  *  A NON-caller-owned pointer to an array of NSSError values
andre@0:  */
andre@0: 
andre@0: NSS_EXTERN NSSError *
andre@0: NSS_GetErrorStack
andre@0: (
andre@0:   void
andre@0: );
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 barfs if we 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 barfs if we split it. */
andre@0: #define NSS_ZNEWARRAY(arenaOpt, type, quantity) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
andre@0: 
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: /*
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: 
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: PR_END_EXTERN_C
andre@0: 
andre@0: #endif /* NSSBASE_H */