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