diff options
Diffstat (limited to '')
| -rw-r--r-- | security/nss/lib/libpkix/include/pkix_pl_system.h | 1545 |
1 files changed, 1545 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_pl_system.h b/security/nss/lib/libpkix/include/pkix_pl_system.h new file mode 100644 index 0000000000..57d5df7cc0 --- /dev/null +++ b/security/nss/lib/libpkix/include/pkix_pl_system.h @@ -0,0 +1,1545 @@ +/* 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/. */ +/* + * This file defines several platform independent functions to make system + * calls in a portable manner. + * + */ + +#ifndef _PKIX_PL_SYSTEM_H +#define _PKIX_PL_SYSTEM_H + +#include "pkixt.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* General + * + * Please refer to the libpkix Programmer's Guide for detailed information + * about how to use the libpkix library. Certain key warnings and notices from + * that document are repeated here for emphasis. + * + * All identifiers in this file (and all public identifiers defined in + * libpkix) begin with "PKIX_". Private identifiers only intended for use + * within the library begin with "pkix_". + * + * A function returns NULL upon success, and a PKIX_Error pointer upon failure. + * + * Unless otherwise noted, for all accessor (gettor) functions that return a + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a + * shared object. Therefore, the caller should treat this shared object as + * read-only and should not modify this shared object. When done using the + * shared object, the caller should release the reference to the object by + * using the PKIX_PL_Object_DecRef function. + * + * While a function is executing, if its arguments (or anything referred to by + * its arguments) are modified, free'd, or destroyed, the function's behavior + * is undefined. + * + */ + +/* + * FUNCTION: PKIX_PL_Initialize + * DESCRIPTION: + * + * XXX If this function is really only meant to be used by PKIX_Initialize, + * why don't we just put it in a private header file rather than the public + * API. I think it may confuse users. + * + * This function should NOT be called by applications. It is only meant to + * be used internally. The application needs only to call PKIX_Initialize, + * which in turn will call this function. + * + * This function initializes data structures critical to the operation of + * libpkix. If initialization is not successful, an Error pointer is + * returned. This function should only be called once. If it is called more + * than once, the behavior is undefined. + * + * No PKIX_* types and functions should be used before this function is + * called and returns successfully. + * + * PARAMETERS: + * "platformInitNeeded" + * Boolean indicating whether platform initialization is to be called + * "useArenas" + * Boolean indicating whether allocation is to be done using arenas or + * individual allocation (malloc). + * "pPlContext" + * Address at which platform-specific context pointer is stored. Must be + * non-NULL. + * THREAD SAFETY: + * Not Thread Safe + * + * This function assumes that no other thread is calling this function while + * it is executing. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Initialize( + PKIX_Boolean platformInitNeeded, + PKIX_Boolean useArenas, + void **pPlContext); + +/* + * FUNCTION: PKIX_PL_Shutdown + * DESCRIPTION: + * + * XXX If this function is really only meant to be used by PKIX_Shutdown, + * why don't we just put it in a private header file rather than the public + * API. I think it may confuse users. + * + * This function should NOT be called by applications. It is only meant to + * be used internally. The application needs only to call PKIX_Shutdown, + * which in turn will call this function. + * + * This function deallocates any memory used by the Portability Layer (PL) + * component of the libpkix library and shuts down any ongoing operations. + * This function should only be called once. If it is called more than once, + * the behavior is undefined. + * + * No PKIX_* types and functions should be used after this function is called + * and returns successfully. + * + * PARAMETERS: + * "platformInitNeeded" + * Boolean value of whether PKIX initialized NSS: PKIX_TRUE if we + * called nssInit, PKIX_FALSE otherwise + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe + * + * This function makes use of global variables and should only be called once. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Shutdown(void *plContext); + +/* standard memory management operations (not reference-counted) */ + +/* + * FUNCTION: PKIX_PL_Malloc + * DESCRIPTION: + * + * Allocates a block of "size" bytes. The bytes are not initialized. A + * pointer to the newly allocated memory will be stored at "pMemory". The + * memory allocated by PKIX_PL_Malloc() may only be freed by PKIX_PL_Free(). + * If "size" equals zero, this function stores NULL at "pMemory". + * + * PARAMETERS: + * "size" + * Number of bytes to allocate. + * "pMemory" + * Address where newly allocated pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on underlying thread safety of platform used by PL. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Malloc( + PKIX_UInt32 size, + void **pMemory, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Calloc + * DESCRIPTION: + * + * Allocates memory for an array of "nElem" elements, with each element + * requiring "elSize" bytes, and with all the bits initialized to zero. A + * pointer to the newly allocated memory will be stored at "pMemory". The + * memory allocated by PKIX_PL_Calloc() may only be freed by PKIX_PL_Free(). + * If "nElem" equals zero or "elSize" equals zero, this function stores NULL + * at "pMemory". + * + * PARAMETERS: + * "nElem" + * Number of elements needed. + * "elSize" + * Number of bytes needed per element. + * "pMemory" + * Address where newly allocated pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on underlying thread safety of platform used by PL. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Calloc( + PKIX_UInt32 nElem, + PKIX_UInt32 elSize, + void **pMemory, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Realloc + * DESCRIPTION: + * + * Resizes an existing block of memory (pointed to by "ptr") to "size" bytes. + * Stores a pointer to the resized memory at "pNewPtr". The "ptr" must + * originate from either PKIX_PL_Malloc(), PKIX_PL_Realloc(), or + * PKIX_PL_Calloc(). If "ptr" is NULL, this function behaves as if + * PKIX_PL_Malloc were called. If "ptr" is not NULL and "size" equals zero, + * the memory pointed to by "ptr" is deallocated and this function stores + * NULL at "pPtr". + * + * PARAMETERS: + * "ptr" + * A pointer to an existing block of memory. + * "size" + * New size in bytes. + * "pPtr" + * Address where newly allocated pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on underlying thread safety of platform used by PL. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Realloc( + void *ptr, + PKIX_UInt32 size, + void **pNewPtr, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Free + * DESCRIPTION: + * + * Frees a block of memory pointed to by "ptr". This value must originate with + * either PKIX_PL_Malloc(), PKIX_PL_Calloc, or PKIX_PL_Realloc(). If "ptr" is + * NULL, the function has no effect. + * + * PARAMETERS: + * "ptr" + * A pointer to an existing block of memory. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on underlying thread safety of platform used by PL. + * RETURNS: + * Returns NULL always. + */ +PKIX_Error * +PKIX_PL_Free( + void *ptr, + void *plContext); + +/* Callback Types + * + * The next few typedefs define function pointer types for the standard + * functions associated with every object type. See the Implementation + * Guidelines or the comments below for more information. + */ + +/* + * TYPE: PKIX_PL_DestructorCallback + * DESCRIPTION: + * + * This callback function destroys (or DecRef's) any pointers contained in + * the user data for the Object pointed to by "object" before the Object is + * destroyed. + * + * PARAMETERS: + * "object" + * Address of Object to destroy. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts (as long as they're not operating on the same + * object and nobody else is performing an operation on the object at the + * same time). Both of these conditions should be guaranteed by the fact that + * the object's ref count was reduced to 0 in a lock that's still held when + * this callback is called. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_DestructorCallback)( + PKIX_PL_Object *object, + void *plContext); + +/* + * TYPE: PKIX_PL_EqualsCallback + * DESCRIPTION: + * + * This callback function compares the Object pointed to by "firstObject" with + * the Object pointed to by "secondObject" for equality and stores the result + * at "pResult" (PKIX_TRUE if equal; PKIX_FALSE if not). + * + * PARAMETERS: + * "firstObject" + * Address of first object to compare. Must be non-NULL. + * "secondObject" + * Address of second object to compare. Must be non-NULL. + * "pResult" + * Address where Boolean will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same objects. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_EqualsCallback)( + PKIX_PL_Object *firstObject, + PKIX_PL_Object *secondObject, + PKIX_Boolean *pResult, + void *plContext); + +/* + * TYPE: PKIX_PL_HashcodeCallback + * DESCRIPTION: + * + * This callback function computes the hashcode of the Object pointed to by + * "object" and stores the result at "pValue". + * + * PARAMETERS: + * "object" + * Address of Object whose hashcode is desired. Must be non-NULL. + * "pValue" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same object. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_HashcodeCallback)( + PKIX_PL_Object *object, + PKIX_UInt32 *pValue, + void *plContext); + +/* + * TYPE: PKIX_PL_ToStringCallback + * DESCRIPTION: + * + * This callback function converts the Object pointed to by "object" to a + * string representation and stores the result at "pString". + * + * PARAMETERS: + * "object" + * Object to get a string representation from. Must be non-NULL. + * "pString" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same object. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_ToStringCallback)( + PKIX_PL_Object *object, + PKIX_PL_String **pString, + void *plContext); + +/* + * TYPE: PKIX_PL_ComparatorCallback + * DESCRIPTION: + * + * This callback function determines how the Object pointed to by + * "firstObject" compares to the Object pointed to by "secondObject" and + * stores the result at "pResult". + * + * Result is less than 0 if firstObject < secondObject + * Result equals 0 if firstObject = secondObject + * Result is greater than 0 if firstObject > secondObject + * + * PARAMETERS: + * "firstObject" + * Address of the first Object to compare. Must be non-NULL. + * "secondObject" + * Address of the second Object to compare. Must be non-NULL. + * "pResult" + * Address where PKIX_Int32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same objects. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_ComparatorCallback)( + PKIX_PL_Object *firstObject, + PKIX_PL_Object *secondObject, + PKIX_Int32 *pResult, + void *plContext); + +/* + * TYPE: PKIX_PL_DuplicateCallback + * DESCRIPTION: + * + * This callback function creates a copy of the Object pointed to by "object" + * and stores it at "pNewObject". Changes to the copy will not affect the + * original and vice versa. + * + * Note that if "object" is immutable, the Duplicate callback function simply + * needs to increment the reference count on "object" and return a reference + * to "object". + * + * PARAMETERS: + * "object" + * Address of the object to be copied. Must be non-NULL. + * "pNewObject" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same object. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_PL_DuplicateCallback)( + PKIX_PL_Object *object, + PKIX_PL_Object **pNewObject, + void *plContext); + +/* reference-counted objects */ + +/* + * FUNCTION: PKIX_PL_Object_Alloc + * DESCRIPTION: + * + * Allocates a new Object of type "type" with "size" bytes and stores the + * resulting pointer at "pObject". The reference count of the newly + * allocated object will be initialized to 1. To improve performance, each + * object maintains a small cache for the results of Hashcode and ToString. + * Mutable objects should call InvalidateCache whenever changes are made to + * the object's state (after creation). If an error occurs during allocation, + * "pObject" will be set to NULL. If "size" equals zero, this function creates + * an Object with a reference count of 1, and places a pointer to unallocated + * memory at "pMemory". + * + * PARAMETERS: + * "type" + * The type code of this object. See pkixt.h for codes. The type code + * must be previously registered with PKIX_PL_Object_RegisterType(). + * "size" + * The number of bytes needed for this object. + * "pMemory" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Alloc( + PKIX_TYPENUM type, + PKIX_UInt32 size, + PKIX_PL_Object **pObject, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_IsTypeRegistered + * DESCRIPTION: + * + * Checks whether "type" has been registered by a previous call to + * PKIX_PL_Object_RegisterType() and stores the Boolean result at "pBool". + * This function will typically only be called by constructors for specific + * types. + * + * PARAMETERS: + * "type" + * The type code to check if valid. + * "pBool" + * Address where Boolean will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_IsTypeRegistered( + PKIX_UInt32 type, + PKIX_Boolean *pBool, + void *plContext); + +#ifdef PKIX_USER_OBJECT_TYPE +/* + * FUNCTION: PKIX_PL_Object_RegisterType + * DESCRIPTION: + * + * Registers a new Object with type value "type" and associates it with a set + * of functions ("destructor", "equalsFunction", "hashcodeFunction", + * "toStringFunction", "comparator", "duplicateFunction"). The new type value + * is also associated with a string pointed to by "description", which is used + * by the default ToStringCallback. This function may only be called with a + * particular "type" value once. If "destructor", "equalsFunction", + * "hashcodeFunction", or "toStringFunction" are NULL, default functions will + * be registered. However, if "comparator" and "duplicateFunction" are NULL, + * no functions will be registered and calls to PKIX_PL_Object_Compare and + * PKIX_PL_Object_Duplicate will result in an error. + * + * PARAMETERS: + * "type" + * The type code. + * "description" + * The string used by the default ToStringCallback. Default used if NULL. + * "destructor" + * The DestructorCallback function to be set. Default used if NULL. + * "equalsFunction" + * The EqualsCallback function to be set. Default used if NULL. + * "hashcodeFunction" + * The HashcodeCallback function to be set. Default used if NULL. + * "toStringFunction" + * The ToStringCallback function to be set. Default used if NULL. + * "comparator" + * The ComparatorCallback function to be set. None set if NULL. If no + * callback function is set in this field, calls to + * PKIX_PL_Object_Compare() will result in an error. + * "duplicateFunction" + * The DuplicateCallback function to be set. None set if NULL. If no + * callback function is set in this field, calls to + * PKIX_PL_Object_Duplicate() will result in an error. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if "type" is already registered. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_RegisterType( + PKIX_UInt32 type, + char *description, + PKIX_PL_DestructorCallback destructor, + PKIX_PL_EqualsCallback equalsFunction, + PKIX_PL_HashcodeCallback hashcodeFunction, + PKIX_PL_ToStringCallback toStringFunction, + PKIX_PL_ComparatorCallback comparator, + PKIX_PL_DuplicateCallback duplicateFunction, + void *plContext); + +#endif +/* + * FUNCTION: PKIX_PL_Object_InvalidateCache + * DESCRIPTION: + * + * Invalidates the cache of the Object pointed to by "object". The cache + * contains results of Hashcode and ToString. This function should be used by + * mutable objects whenever changes are made to the Object's state (after + * creation). + * + * For example, if ToString is called on a mutable Object, the result will be + * computed, cached, and returned. If the Object's state does not change, a + * subsequent call to ToString will recognize that the relevant result is + * cached and will simply return the result (without calling the Object's + * ToStringCallback to recompute it). However, when the Object's state + * changes, the cache needs to be invalidated in order to force a subsequent + * call to ToString to recompute the result. + * + * PARAMETERS: + * "object" + * Address of Object whose cache is to be invalidated. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * + * THREAD SAFETY + * Thread Safe - Object Type Table is locked during modification. + * + * Multiple threads can safely call this function without worrying about + * conflicts, even if they're operating on the same object. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_InvalidateCache( + PKIX_PL_Object *object, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_IncRef + * DESCRIPTION: + * + * Increments the reference count of the Object pointed to by "object". + * + * PARAMETERS: + * "object" + * Address of Object whose reference count is to be incremented. + * Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_IncRef( + PKIX_PL_Object *object, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_DecRef + * DESCRIPTION: + * + * Decrements the reference count of the Object pointed to by "object". If the + * resulting reference count is zero, the destructor (if any) registered for + * the Object's type (by PKIX_PL_RegisterType) will be called and then the + * Object will be destroyed. + * + * PARAMETERS: + * "object" + * Address of Object whose reference count is to be decremented. + * Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * If destructor is not called, multiple threads can safely call this function + * without worrying about conflicts, even if they're operating on the same + * object. If destructor is called, thread safety depends on the callback + * defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_DecRef( + PKIX_PL_Object *object, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Equals + * DESCRIPTION: + * + * Compares the Object pointed to by "firstObject" with the Object pointed to + * by "secondObject" for equality using the callback function registered for + * "firstObject"'s type, and stores the Boolean result at "pResult". While + * typical callbacks will return PKIX_FALSE if the objects are of different + * types, other callbacks may be capable of comparing objects of different + * types [which may correctly result in cases where Equals(first, second) + * differs from Equals(second, first)]. + * + * PARAMETERS: + * "firstObject" + * Address of the first Object to compare. Must be non-NULL. + * The EqualsCallback for this Object will be called. + * "secondObject" + * Address of the second Object to compare. Must be non-NULL. + * "pResult" + * Address where Boolean will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on the callback defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Equals( + PKIX_PL_Object *firstObject, + PKIX_PL_Object *secondObject, + PKIX_Boolean *pResult, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Hashcode + * DESCRIPTION: + * + * Computes a hashcode of the Object pointed to by "object" using the + * callback registered for "object"'s type and stores it at "pValue". Two + * objects which are equal should have the same hashcode. Once a call to + * Hashcode has been made, the results are cached and subsequent calls to + * Hashcode will return the cached value. For mutable objects, an + * InvalidateCache function is provided, which should be called whenever + * changes are made to the object's state (after creation). + * + * PARAMETERS: + * "object" + * Address of the Object whose hashcode is desired. Must be non-NULL. + * The HashcodeCallback for this object will be called. + * "pValue" + * Address where PKIX_Int32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * + * THREAD SAFETY: + * Thread safety depends on the callback defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Hashcode( + PKIX_PL_Object *object, + PKIX_UInt32 *pValue, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_ToString + * DESCRIPTION: + * + * Creates a string representation of the Object pointed to by "object" using + * the callback registered for "object"'s type and stores it at "pString". + * Once a call to ToString has been made, the results are cached and + * subsequent calls to ToString will return the cached value. For mutable + * objects, an InvalidateCache function is provided, which should be called + * whenever changes are made to the object's state (after creation). + * + * PARAMETERS: + * "object" + * Address of Object whose string representation is desired. + * Must be non-NULL. The ToStringCallback for this object will be called. + * "pString" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on the callback defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_ToString( + PKIX_PL_Object *object, + PKIX_PL_String **pString, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Compare + * DESCRIPTION: + * + * Compares the Object pointed to by "firstObject" and the Object pointed to + * by "secondObject" using the comparator registered for "firstObject"'s type + * and stores the result at "pResult". Different types may be compared. This + * may correctly result in cases where Compare(first, second) is not the + * opposite of Compare(second, first). The PKIX_Int32 value stored at + * "pResult" will be: + * Less than 0 if "firstObject" < "secondObject" + * Equals to 0 if "firstObject" = "secondObject" + * Greater than 0 if "firstObject" > "secondObject" + * + * PARAMETERS: + * "firstObject" + * Address of first Object to compare. Must be non-NULL. + * The ComparatorCallback for this object will be called. + * "secondObject" + * Address of second object to compare. Must be non-NULL. + * "pResult + * Address where PKIX_Int32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on the comparator defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Compare( + PKIX_PL_Object *firstObject, + PKIX_PL_Object *secondObject, + PKIX_Int32 *pResult, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Duplicate + * DESCRIPTION: + * + * Creates a duplicate copy of the Object pointed to by "object" using the + * callback registered for "object"'s type and stores the copy at + * "pNewObject". Changes to the new object will not affect the original and + * vice versa. + * + * Note that if "object" is immutable, the Duplicate callback function simply + * needs to increment the reference count on "object" and return a reference + * to "object". + * + * PARAMETERS: + * "object" + * Address of Object to be duplicated. Must be non-NULL. + * The DuplicateCallback for this Object will be called. + * "pNewObject" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread safety depends on the callback defined by PKIX_PL_RegisterType(). + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Object Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Duplicate( + PKIX_PL_Object *object, + PKIX_PL_Object **pNewObject, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_GetType + * DESCRIPTION: + * + * Retrieves the type code of the Object pointed to by "object" and stores it + * at "pType". See pkixt.h for type codes. + * + * PARAMETERS: + * "object" + * Address of Object whose type is desired. Must be non-NULL. + * "pType" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_GetType( + PKIX_PL_Object *object, + PKIX_UInt32 *pType, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Lock + * DESCRIPTION: + * + * Locks the Mutex associated with the Object pointed to by "object". When an + * object is created, it is associated with an object-specific Mutex to allow + * for synchronization when the fields of the object are modified. + * + * PARAMETERS: + * "object" + * Address of Object whose Mutex is to be locked. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Lock( + PKIX_PL_Object *object, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Object_Unlock + * DESCRIPTION: + * + * Unlocks the Mutex associated with the Object pointed to by "object". When + * an object is created, it is associated with an object-specific Mutex to + * allow for synchronization when the fields of the object are modified. + * + * PARAMETERS: + * "object" + * Address of Object whose Mutex is to be unlocked. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Object_Unlock( + PKIX_PL_Object *object, + void *plContext); + +/* mutexes (locks) */ + +/* + * FUNCTION: PKIX_PL_Mutex_Create + * DESCRIPTION: + * + * Creates a new Mutex and stores it at "pNewLock". + * + * PARAMETERS: + * "pNewLock" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Mutex_Create( + PKIX_PL_Mutex **pNewLock, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Mutex_Lock + * DESCRIPTION: + * + * Locks the Mutex pointed to by "lock". If the Mutex is already locked, this + * function will block the current thread until the mutex can be locked by + * this thread. + * + * PARAMETERS: + * "lock" + * Address of Mutex to lock. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Mutex_Lock( + PKIX_PL_Mutex *lock, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Mutex_Unlock + * DESCRIPTION: + * + * Unlocks the Mutex pointed to by "lock" if the current thread holds the + * Mutex. + * + * PARAMETERS: + * "lock" + * Address of Mutex to unlock. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Mutex_Unlock( + PKIX_PL_Mutex *lock, + void *plContext); + +/* monitor (locks) */ + +/* + * FUNCTION: PKIX_PL_MonitorLock_Create + * DESCRIPTION: + * + * Creates a new PKIX_PL_MonitorLock and stores it at "pNewLock". + * + * PARAMETERS: + * "pNewLock" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_MonitorLock_Create( + PKIX_PL_MonitorLock **pNewLock, + void *plContext); + +/* + * FUNCTION: PKIX_PL_MonitorLock_Enter + * DESCRIPTION: + * + * Locks the MonitorLock pointed to by "lock". If the MonitorLock is already + * locked by other thread, this function will block the current thread. If + * the "lock" had been locked by current thread, this function will NOT block. + * + * PARAMETERS: + * "lock" + * Address of MonitorLock to lock. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_MonitorLock_Enter( + PKIX_PL_MonitorLock *lock, + void *plContext); + +/* + * FUNCTION: PKIX_PL_MonitorLock_Exit + * DESCRIPTION: + * + * Unlocks the MonitorLock pointed to by "lock" if the lock counter of + * current thread holds the MonitorLock reach 0, the lock is released. + * + * PARAMETERS: + * "lock" + * Address of MonitorLock to unlock. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_MonitorLock_Exit( + PKIX_PL_MonitorLock *lock, + void *plContext); + +/* strings and formatted printing */ + +/* + * FUNCTION: PKIX_PL_String_Create + * DESCRIPTION: + * + * Creates a new String using the data pointed to by "pString", the + * PKIX_UInt32 pointed to by "stringLen", and the PKIX_UInt32 pointed to by + * "fmtIndicator" and stores it at "pString". If the format is PKIX_ESCASCII + * the "stringLen" parameter is ignored and the string extends until a zero + * byte is found. Once created, a String object is immutable. + * + * Valid formats are: + * PKIX_ESCASCII + * PKIX_ESCASCII_DEBUG + * PKIX_UTF8 + * PKIX_UTF8_NULL_TERM + * PKIX_UTF16 + * + * PARAMETERS: + * "fmtIndicator" + * Format that "stringRep" is encoded with. Must be non-NULL. + * "stringRep" + * Address of encoded string representation. Must be non-NULL. + * "stringLen" + * Length of data stored at stringRep. + * "pString" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a String Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_String_Create( + PKIX_UInt32 fmtIndicator, + const void *stringRep, + PKIX_UInt32 stringLen, + PKIX_PL_String **pString, + void *plContext); + +/* + * FUNCTION: PKIX_PL_Sprintf + * DESCRIPTION: + * + * Creates a formatted string at "pOut" using the given format "fmt" and a + * variable length list of arguments. The format flags are identical to + * standard C with the exception that %s expects a PKIX_PL_String*, rather + * than a char *, and that {%d, %i, %o, %u, %x, %X} expect PKIX_UInt32 or + * PKIX_Int32 instead of int or unsigned int. + * + * PARAMETERS: + * "pOut" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * "fmt" + * Address of format string. Must be non-NULL. + * THREAD SAFETY: + * Not Thread Safe - Caller must have exclusive access to all arguments. + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a String Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Sprintf( + PKIX_PL_String **pOut, + void *plContext, + const PKIX_PL_String *fmt, ...); + +/* + * FUNCTION: PKIX_PL_GetString + * DESCRIPTION: + * + * Retrieves the String associated with the value of "stringID" (if any) and + * stores it at "pString". If no such string is associated with "stringID", + * this function uses "defaultString" to create a String and stores it at + * "pString". + * + * PARAMETERS: + * "stringID" + * PKIX_UInt32 valud of string identifier. + * "defaultString" + * Address of a PKIX_ESCASCII encoded string representation. + * Must be non-NULL. + * "pString" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a String Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_GetString( + PKIX_UInt32 stringID, + char *defaultString, + PKIX_PL_String **pString, + void *plContext); + +/* + * FUNCTION: PKIX_PL_String_GetEncoded + * DESCRIPTION: + * + * Retrieves the value of the String pointed to by "string" in the encoding + * specified by "fmtIndicator" and stores the result in "pStringRep" and + * "pLength", respectively. Note that "pStringRep" is not reference counted + * and will need to be freed with PKIX_PL_Free(). + * + * PARAMETERS: + * "string" + * Address of String whose encoded value is desired. Must be non-NULL. + * "fmtIndicator" + * Format of encoding. Supported formats are: + * PKIX_ESCASCII, PKIX_ESCASII_DEBUG, PKIX_UTF8, PKIX_UTF8_NULL_TERM, and + * PKIX_UTF16. XXX Where are these documented? + * "pStringRep" + * Address where pointer to encoded value will be stored. + * Must be non-NULL. + * "pLength" + * Address where byte length of encoded value will be stored. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a String Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_String_GetEncoded( + PKIX_PL_String *string, + PKIX_UInt32 fmtIndicator, + void **pStringRep, + PKIX_UInt32 *pLength, + void *plContext); + +/* + * Hashtable + * + * A hashtable is a very efficient data structure used for mapping keys to + * values. Any non-null PKIX_PL_Object can be used as a key or as a value, + * provided that it correctly implements the PKIX_PL_EqualsCallback and the + * PKIX_PL_HashcodeCallback. A hashtable consists of several buckets, with + * each bucket capable of holding a linked list of key/value mappings. When + * adding, retrieving, or deleting a value, the hashcode of the key is used to + * determine which bucket's linked list is relevant. The corresponding + * key/value pair is then appended, retrieved, or deleted. + */ + +/* + * FUNCTION: PKIX_PL_HashTable_Create + * DESCRIPTION: + * + * Creates a new Hashtable with an initial capacity of "numBuckets" buckets + * and "maxEntriesPerBucket" of entries limit for each bucket and stores it + * at "pResult". + * + * PARAMETERS: + * "numBuckets" + * The initial number of hash table buckets. Must be non-zero. + * "maxEntriesPerBucket" + * The limit of entries per bucket. Zero means no limit. + * "pResult" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_HashTable_Create( + PKIX_UInt32 numBuckets, + PKIX_UInt32 maxEntriesPerBucket, + PKIX_PL_HashTable **pResult, + void *plContext); + +/* + * FUNCTION: PKIX_PL_HashTable_Add + * DESCRIPTION: + * + * Adds a key/value mapping using the Objects pointed to by "key" and "value" + * to the Hashtable pointed to by "ht". + * + * Function increments key/value reference counts. Caller is responsible to + * to decrement(destroy) key/value ref counts(objects). + * + * PARAMETERS: + * "ht" + * Address of Hashtable to be added to. Must be non-NULL. + * "key" + * Address of Object to be associated with "value". Must be non-NULL. + * "value" + * Address of Object to be added to Hashtable. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "ht" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Hashtable Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_HashTable_Add( + PKIX_PL_HashTable *ht, + PKIX_PL_Object *key, + PKIX_PL_Object *value, + void *plContext); + +/* + * FUNCTION: PKIX_PL_HashTable_Remove + * DESCRIPTION: + * + * Removes the Object value whose key is equal to the Object pointed to by + * "key" from the Hashtable pointed to by "ht". If no such object exists, + * this function throws an Error. + * + * Function frees "value" object. Caller is responsible to free "key" + * object. + * + * PARAMETERS: + * "ht" + * Address of Hashtable to remove object from. Must be non-NULL. + * "key" + * Address of Object used for lookup. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "ht" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Hashtable Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_HashTable_Remove( + PKIX_PL_HashTable *ht, + PKIX_PL_Object *key, + void *plContext); + +/* + * FUNCTION: PKIX_PL_HashTable_Lookup + * DESCRIPTION: + * + * Retrieves the Object whose key equals the Object pointed to by "key" from + * the Hashtable associated with "ht" and stores it at "pResult". If no + * Object is found, this function stores NULL at "pResult". + * + * PARAMETERS: + * "ht" + * Address of Hashtable to lookup Object from. Must be non-NULL. + * "key" + * Address of key Object used for lookup. Must be non-NULL. + * "pResult" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Hashtable Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_HashTable_Lookup( + PKIX_PL_HashTable *ht, + PKIX_PL_Object *key, + PKIX_PL_Object **pResult, + void *plContext); + +/* + * FUNCTION: PKIX_PL_ByteArray_Create + * DESCRIPTION: + * + * Creates a new ByteArray using "length" bytes of data pointed to by "array" + * and stores it at "pByteArray". Once created, a ByteArray is immutable. + * + * PARAMETERS: + * "array" + * Address of source data. + * "length" + * Number of bytes to copy. + * "pByteArray" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_ByteArray_Create( + void *array, + PKIX_UInt32 length, + PKIX_PL_ByteArray **pByteArray, + void *plContext); + +/* + * FUNCTION: PKIX_PL_ByteArray_GetPointer + * DESCRIPTION: + * + * Allocates enough memory to hold the contents of the ByteArray pointed to + * by "byteArray", copies the data from the ByteArray pointed to by + * "byteArray" into the newly allocated memory, and stores a pointer to the + * memory at "pArray". Note that "pArray" is not reference counted. It will + * need to be freed with PKIX_PL_Free(). + * + * PARAMETERS: + * "byteArray" + * Address of ByteArray whose data is desired. Must be non-NULL. + * "pArray" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_ByteArray_GetPointer( + PKIX_PL_ByteArray *byteArray, + void **pArray, + void *plContext); + +/* + * FUNCTION: PKIX_PL_ByteArray_GetLength + * DESCRIPTION: + * + * Retrieves the length of the ByteArray pointed to by "byteArray" and stores + * the length at "pLength". + * + * PARAMETERS: + * "byteArray" + * Address of ByteArray whose length is desired. Must be non-NULL. + * "pLength" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_ByteArray_GetLength( + PKIX_PL_ByteArray *byteArray, + PKIX_UInt32 *pLength, + void *plContext); + +/* + * FUNCTION: PKIX_PL_OID_Create + * DESCRIPTION: + * + * Creates a new OID using NSS oid tag. + * + * PARAMETERS: + * "idtag" + * nss oid id tag. + * "pOID" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an OID Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_OID_Create( + SECOidTag idtag, + PKIX_PL_OID **pOID, + void *plContext); + +/* + * FUNCTION: PKIX_PL_OID_CreateBySECItem + * DESCRIPTION: + * + * Creates a new OID using a DER encoded OID stored as SECItem. + * + * PARAMETERS: + * "derOid" + * Address of SECItem that holds DER encoded OID. + * "pOID" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an OID Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_OID_CreateBySECItem( + SECItem *derOid, + PKIX_PL_OID **pOID, + void *plContext); + +/* + * FUNCTION: PKIX_PL_BigInt_Create + * DESCRIPTION: + * + * Creates a new BigInt using the source String pointed to by "stringRep" and + * stores it at "pBigInt". Valid source Strings consist of an even number of + * hexadecimal digits, which are always interpreted as a positive number. + * Once created, a BigInt is immutable. + * + * The regexp format is: + * HexDigit ::= [0-9] | [A-F] | [a-f] + * DoubleHex ::= HexDigit HexDigit + * BigIntSrc ::= (DoubleHex)+ + * + * Note that since we are using DoubleHex, the number of characters in the + * source MUST be even. Additionally, the first DoubleHex MUST NOT be "00" + * unless it is the only DoubleHex. + * + * Valid : "09" + * Valid : "00" (special case where first and only DoubleHex is "00") + * Invalid: "9" (not DoubleHex: odd number of characters) + * Invalid: "0009" (first DoubleHex is "00") + * + * XXX Why does this take a String object while OID_Create takes a char* ? + * Perhaps because OID_Create is often used with constant strings and + * this function isn't. That's a good reason, but we should explain it + * (if it's right) + * PARAMETERS: + * "stringRep" + * Address of String representing a BigInt. Must be non-NULL. + * "pBigInt" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a BigInt Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_BigInt_Create( + PKIX_PL_String *stringRep, + PKIX_PL_BigInt **pBigInt, + void *plContext); + +#ifdef __cplusplus +} +#endif + +/* + * FUNCTION: PKIX_PL_GetPLErrorCode + * DESCRIPTION: + * + * Returns error code from PL layer. + * + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * PL layer error code. + */ +int +PKIX_PL_GetPLErrorCode(); + +#endif /* _LIBPKIX_SYSTEM_H */ |