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