andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public
andre@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
andre@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
andre@0: /*
andre@0:  * This file defines several platform independent functions to make system
andre@0:  * calls in a portable manner.
andre@0:  *
andre@0:  */
andre@0: 
andre@0: #ifndef _PKIX_PL_SYSTEM_H
andre@0: #define _PKIX_PL_SYSTEM_H
andre@0: 
andre@0: #include "pkixt.h"
andre@0: 
andre@0: #ifdef __cplusplus
andre@0: extern "C" {
andre@0: #endif
andre@0: 
andre@0: /* General
andre@0:  *
andre@0:  * Please refer to the libpkix Programmer's Guide for detailed information
andre@0:  * about how to use the libpkix library. Certain key warnings and notices from
andre@0:  * that document are repeated here for emphasis.
andre@0:  *
andre@0:  * All identifiers in this file (and all public identifiers defined in
andre@0:  * libpkix) begin with "PKIX_". Private identifiers only intended for use
andre@0:  * within the library begin with "pkix_".
andre@0:  *
andre@0:  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
andre@0:  *
andre@0:  * Unless otherwise noted, for all accessor (gettor) functions that return a
andre@0:  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
andre@0:  * shared object. Therefore, the caller should treat this shared object as
andre@0:  * read-only and should not modify this shared object. When done using the
andre@0:  * shared object, the caller should release the reference to the object by
andre@0:  * using the PKIX_PL_Object_DecRef function.
andre@0:  *
andre@0:  * While a function is executing, if its arguments (or anything referred to by
andre@0:  * its arguments) are modified, free'd, or destroyed, the function's behavior
andre@0:  * is undefined.
andre@0:  *
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Initialize
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  XXX If this function is really only meant to be used by PKIX_Initialize,
andre@0:  *  why don't we just put it in a private header file rather than the public
andre@0:  *  API. I think it may confuse users.
andre@0:  *
andre@0:  *  This function should NOT be called by applications. It is only meant to
andre@0:  *  be used internally. The application needs only to call PKIX_Initialize,
andre@0:  *  which in turn will call this function.
andre@0:  *
andre@0:  *  This function initializes data structures critical to the operation of
andre@0:  *  libpkix. If initialization is not successful, an Error pointer is
andre@0:  *  returned. This function should only be called once. If it is called more
andre@0:  *  than once, the behavior is undefined.
andre@0:  *
andre@0:  *  No PKIX_* types and functions should be used before this function is
andre@0:  *  called and returns successfully.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "platformInitNeeded"
andre@0:  *      Boolean indicating whether platform initialization is to be called
andre@0:  *  "useArenas"
andre@0:  *      Boolean indicating whether allocation is to be done using arenas or
andre@0:  *      individual allocation (malloc).
andre@0:  *  "pPlContext"
andre@0:  *      Address at which platform-specific context pointer is stored. Must be
andre@0:  *      non-NULL.
andre@0:  * THREAD SAFETY:
andre@0:  *  Not Thread Safe
andre@0:  *
andre@0:  *  This function assumes that no other thread is calling this function while
andre@0:  *  it is executing.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Initialize(
andre@0:         PKIX_Boolean platformInitNeeded,
andre@0:         PKIX_Boolean useArenas,
andre@0:         void **pPlContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Shutdown
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  XXX If this function is really only meant to be used by PKIX_Shutdown,
andre@0:  *  why don't we just put it in a private header file rather than the public
andre@0:  *  API. I think it may confuse users.
andre@0:  *
andre@0:  *  This function should NOT be called by applications. It is only meant to
andre@0:  *  be used internally. The application needs only to call PKIX_Shutdown,
andre@0:  *  which in turn will call this function.
andre@0:  *
andre@0:  *  This function deallocates any memory used by the Portability Layer (PL)
andre@0:  *  component of the libpkix library and shuts down any ongoing operations.
andre@0:  *  This function should only be called once. If it is called more than once,
andre@0:  *  the behavior is undefined.
andre@0:  *
andre@0:  *  No PKIX_* types and functions should be used after this function is called
andre@0:  *  and returns successfully.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "platformInitNeeded"
andre@0:  *      Boolean value of whether PKIX initialized NSS: PKIX_TRUE if we
andre@0:  *      called nssInit, PKIX_FALSE otherwise
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Not Thread Safe
andre@0:  *
andre@0:  *  This function makes use of global variables and should only be called once.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Shutdown(void *plContext);
andre@0: 
andre@0: /* standard memory management operations (not reference-counted) */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Malloc
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Allocates a block of "size" bytes. The bytes are not initialized. A
andre@0:  *  pointer to the newly allocated memory will be stored at "pMemory". The
andre@0:  *  memory allocated by PKIX_PL_Malloc() may only be freed by PKIX_PL_Free().
andre@0:  *  If "size" equals zero, this function stores NULL at "pMemory".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "size"
andre@0:  *      Number of bytes to allocate.
andre@0:  *  "pMemory"
andre@0:  *      Address where newly allocated pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on underlying thread safety of platform used by PL.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Malloc(
andre@0:         PKIX_UInt32 size,
andre@0:         void **pMemory,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Calloc
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Allocates memory for an array of "nElem" elements, with each element
andre@0:  *  requiring "elSize" bytes, and with all the bits initialized to zero. A
andre@0:  *  pointer to the newly allocated memory will be stored at "pMemory". The
andre@0:  *  memory allocated by PKIX_PL_Calloc() may only be freed by PKIX_PL_Free().
andre@0:  *  If "nElem" equals zero or "elSize" equals zero, this function stores NULL
andre@0:  *  at "pMemory".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "nElem"
andre@0:  *      Number of elements needed.
andre@0:  *  "elSize"
andre@0:  *      Number of bytes needed per element.
andre@0:  *  "pMemory"
andre@0:  *      Address where newly allocated pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on underlying thread safety of platform used by PL.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Calloc(
andre@0:         PKIX_UInt32 nElem,
andre@0:         PKIX_UInt32 elSize,
andre@0:         void **pMemory,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Realloc
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Resizes an existing block of memory (pointed to by "ptr") to "size" bytes.
andre@0:  *  Stores a pointer to the resized memory at "pNewPtr". The "ptr" must
andre@0:  *  originate from either PKIX_PL_Malloc(), PKIX_PL_Realloc(), or
andre@0:  *  PKIX_PL_Calloc(). If "ptr" is NULL, this function behaves as if
andre@0:  *  PKIX_PL_Malloc were called. If "ptr" is not NULL and "size" equals zero,
andre@0:  *  the memory pointed to by "ptr" is deallocated and this function stores
andre@0:  *  NULL at "pPtr".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "ptr"
andre@0:  *      A pointer to an existing block of memory.
andre@0:  *  "size"
andre@0:  *      New size in bytes.
andre@0:  *  "pPtr"
andre@0:  *      Address where newly allocated pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on underlying thread safety of platform used by PL.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Realloc(
andre@0:         void *ptr,
andre@0:         PKIX_UInt32 size,
andre@0:         void **pNewPtr,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Free
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Frees a block of memory pointed to by "ptr". This value must originate with
andre@0:  *  either PKIX_PL_Malloc(), PKIX_PL_Calloc, or PKIX_PL_Realloc(). If "ptr" is
andre@0:  *  NULL, the function has no effect.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "ptr"
andre@0:  *      A pointer to an existing block of memory.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on underlying thread safety of platform used by PL.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL always.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Free(
andre@0:         void *ptr,
andre@0:         void *plContext);
andre@0: 
andre@0: /* Callback Types
andre@0:  *
andre@0:  * The next few typedefs define function pointer types for the standard
andre@0:  * functions associated with every object type. See the Implementation
andre@0:  * Guidelines or the comments below for more information.
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_DestructorCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function destroys (or DecRef's) any pointers contained in
andre@0:  *  the user data for the Object pointed to by "object" before the Object is
andre@0:  *  destroyed.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object to destroy. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts (as long as they're not operating on the same
andre@0:  *  object and nobody else is performing an operation on the object at the
andre@0:  *  same time). Both of these conditions should be guaranteed by the fact that
andre@0:  *  the object's ref count was reduced to 0 in a lock that's still held when
andre@0:  *  this callback is called.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_DestructorCallback)(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_EqualsCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function compares the Object pointed to by "firstObject" with
andre@0:  *  the Object pointed to by "secondObject" for equality and stores the result
andre@0:  *  at "pResult" (PKIX_TRUE if equal; PKIX_FALSE if not).
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "firstObject"
andre@0:  *      Address of first object to compare. Must be non-NULL.
andre@0:  *  "secondObject"
andre@0:  *      Address of second object to compare. Must be non-NULL.
andre@0:  *  "pResult"
andre@0:  *      Address where Boolean will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same objects.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_EqualsCallback)(
andre@0:         PKIX_PL_Object *firstObject,
andre@0:         PKIX_PL_Object *secondObject,
andre@0:         PKIX_Boolean *pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_HashcodeCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function computes the hashcode of the Object pointed to by
andre@0:  *  "object" and stores the result at "pValue".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose hashcode is desired. Must be non-NULL.
andre@0:  *  "pValue"
andre@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_HashcodeCallback)(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_UInt32 *pValue,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_ToStringCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function converts the Object pointed to by "object" to a
andre@0:  *  string representation and stores the result at "pString".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Object to get a string representation from. Must be non-NULL.
andre@0:  *  "pString"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_ToStringCallback)(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_PL_String **pString,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_ComparatorCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function determines how the Object pointed to by
andre@0:  *  "firstObject" compares to the Object pointed to by "secondObject" and
andre@0:  *  stores the result at "pResult".
andre@0:  *
andre@0:  *  Result is less than 0 if firstObject < secondObject
andre@0:  *  Result equals 0 if firstObject = secondObject
andre@0:  *  Result is greater than 0 if firstObject > secondObject
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "firstObject"
andre@0:  *      Address of the first Object to compare. Must be non-NULL.
andre@0:  *  "secondObject"
andre@0:  *      Address of the second Object to compare. Must be non-NULL.
andre@0:  *  "pResult"
andre@0:  *      Address where PKIX_Int32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same objects.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_ComparatorCallback)(
andre@0:         PKIX_PL_Object *firstObject,
andre@0:         PKIX_PL_Object *secondObject,
andre@0:         PKIX_Int32 *pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * TYPE: PKIX_PL_DuplicateCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function creates a copy of the Object pointed to by "object"
andre@0:  *  and stores it at "pNewObject". Changes to the copy will not affect the
andre@0:  *  original and vice versa.
andre@0:  *
andre@0:  *  Note that if "object" is immutable, the Duplicate callback function simply
andre@0:  *  needs to increment the reference count on "object" and return a reference
andre@0:  *  to "object".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of the object to be copied. Must be non-NULL.
andre@0:  *  "pNewObject"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_PL_DuplicateCallback)(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_PL_Object **pNewObject,
andre@0:         void *plContext);
andre@0: 
andre@0: /* reference-counted objects */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Alloc
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Allocates a new Object of type "type" with "size" bytes and stores the
andre@0:  *  resulting pointer at "pObject". The reference count of the newly
andre@0:  *  allocated object will be initialized to 1. To improve performance, each
andre@0:  *  object maintains a small cache for the results of Hashcode and ToString.
andre@0:  *  Mutable objects should call InvalidateCache whenever changes are made to
andre@0:  *  the object's state (after creation). If an error occurs during allocation,
andre@0:  *  "pObject" will be set to NULL. If "size" equals zero, this function creates
andre@0:  *  an Object with a reference count of 1, and places a pointer to unallocated
andre@0:  *  memory at "pMemory".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "type"
andre@0:  *      The type code of this object. See pkixt.h for codes. The type code
andre@0:  *      must be previously registered with PKIX_PL_Object_RegisterType().
andre@0:  *  "size"
andre@0:  *      The number of bytes needed for this object.
andre@0:  *  "pMemory"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Alloc(
andre@0:         PKIX_TYPENUM type,
andre@0:         PKIX_UInt32 size,
andre@0:         PKIX_PL_Object **pObject,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_IsTypeRegistered
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Checks whether "type" has been registered by a previous call to
andre@0:  *  PKIX_PL_Object_RegisterType() and stores the Boolean result at "pBool".
andre@0:  *  This function will typically only be called by constructors for specific
andre@0:  *  types.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "type"
andre@0:  *      The type code to check if valid.
andre@0:  *  "pBool"
andre@0:  *      Address where Boolean will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_IsTypeRegistered(
andre@0:         PKIX_UInt32 type,
andre@0:         PKIX_Boolean *pBool,
andre@0:         void *plContext);
andre@0: 
andre@0: #ifdef PKIX_USER_OBJECT_TYPE
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_RegisterType
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Registers a new Object with type value "type" and associates it with a set
andre@0:  *  of functions ("destructor", "equalsFunction", "hashcodeFunction",
andre@0:  *  "toStringFunction", "comparator", "duplicateFunction"). The new type value
andre@0:  *  is also associated with a string pointed to by "description", which is used
andre@0:  *  by the default ToStringCallback. This function may only be called with a
andre@0:  *  particular "type" value once. If "destructor", "equalsFunction",
andre@0:  *  "hashcodeFunction", or "toStringFunction" are NULL, default functions will
andre@0:  *  be registered. However, if "comparator" and "duplicateFunction" are NULL,
andre@0:  *  no functions will be registered and calls to PKIX_PL_Object_Compare and
andre@0:  *  PKIX_PL_Object_Duplicate will result in an error.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "type"
andre@0:  *      The type code.
andre@0:  *  "description"
andre@0:  *      The string used by the default ToStringCallback. Default used if NULL.
andre@0:  *  "destructor"
andre@0:  *      The DestructorCallback function to be set. Default used if NULL.
andre@0:  *  "equalsFunction"
andre@0:  *      The EqualsCallback function to be set. Default used if NULL.
andre@0:  *  "hashcodeFunction"
andre@0:  *      The HashcodeCallback function to be set. Default used if NULL.

andre@0:  *  "toStringFunction"
andre@0:  *      The ToStringCallback function to be set. Default used if NULL.
andre@0:  *  "comparator"
andre@0:  *      The ComparatorCallback function to be set. None set if NULL. If no
andre@0:  *      callback function is set in this field, calls to
andre@0:  *      PKIX_PL_Object_Compare() will result in an error.
andre@0:  *  "duplicateFunction"
andre@0:  *      The DuplicateCallback function to be set. None set if NULL. If no
andre@0:  *      callback function is set in this field, calls to
andre@0:  *      PKIX_PL_Object_Duplicate() will result in an error.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if "type" is already registered.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_RegisterType(
andre@0:         PKIX_UInt32 type,
andre@0:         char *description,
andre@0:         PKIX_PL_DestructorCallback destructor,
andre@0:         PKIX_PL_EqualsCallback equalsFunction,
andre@0:         PKIX_PL_HashcodeCallback hashcodeFunction,
andre@0:         PKIX_PL_ToStringCallback toStringFunction,
andre@0:         PKIX_PL_ComparatorCallback comparator,
andre@0:         PKIX_PL_DuplicateCallback duplicateFunction,
andre@0:         void *plContext);
andre@0: 
andre@0: #endif
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_InvalidateCache
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Invalidates the cache of the Object pointed to by "object". The cache
andre@0:  *  contains results of Hashcode and ToString. This function should be used by
andre@0:  *  mutable objects whenever changes are made to the Object's state (after
andre@0:  *  creation).
andre@0:  *
andre@0:  *  For example, if ToString is called on a mutable Object, the result will be
andre@0:  *  computed, cached, and returned. If the Object's state does not change, a
andre@0:  *  subsequent call to ToString will recognize that the relevant result is
andre@0:  *  cached and will simply return the result (without calling the Object's
andre@0:  *  ToStringCallback to recompute it). However, when the Object's state
andre@0:  *  changes, the cache needs to be invalidated in order to force a subsequent
andre@0:  *  call to ToString to recompute the result.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose cache is to be invalidated. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  *
andre@0:  * THREAD SAFETY
andre@0:  *  Thread Safe - Object Type Table is locked during modification.
andre@0:  *
andre@0:  *  Multiple threads can safely call this function without worrying about
andre@0:  *  conflicts, even if they're operating on the same object.
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_InvalidateCache(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_IncRef
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Increments the reference count of the Object pointed to by "object".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose reference count is to be incremented.
andre@0:  *      Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_IncRef(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_DecRef
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Decrements the reference count of the Object pointed to by "object". If the
andre@0:  *  resulting reference count is zero, the destructor (if any) registered for
andre@0:  *  the Object's type (by PKIX_PL_RegisterType) will be called and then the
andre@0:  *  Object will be destroyed.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose reference count is to be decremented.
andre@0:  *      Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  If destructor is not called, multiple threads can safely call this function
andre@0:  *  without worrying about conflicts, even if they're operating on the same
andre@0:  *  object. If destructor is called, thread safety depends on the callback
andre@0:  *  defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_DecRef(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Equals
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Compares the Object pointed to by "firstObject" with the Object pointed to
andre@0:  *  by "secondObject" for equality using the callback function registered for
andre@0:  *  "firstObject"'s type, and stores the Boolean result at "pResult". While
andre@0:  *  typical callbacks will return PKIX_FALSE if the objects are of different
andre@0:  *  types, other callbacks may be capable of comparing objects of different
andre@0:  *  types [which may correctly result in cases where Equals(first, second)
andre@0:  *  differs from Equals(second, first)].
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "firstObject"
andre@0:  *      Address of the first Object to compare. Must be non-NULL.
andre@0:  *      The EqualsCallback for this Object will be called.
andre@0:  *  "secondObject"
andre@0:  *      Address of the second Object to compare. Must be non-NULL.
andre@0:  *  "pResult"
andre@0:  *      Address where Boolean will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on the callback defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Equals(
andre@0:         PKIX_PL_Object *firstObject,
andre@0:         PKIX_PL_Object *secondObject,
andre@0:         PKIX_Boolean *pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Hashcode
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Computes a hashcode of the Object pointed to by "object" using the
andre@0:  *  callback registered for "object"'s type and stores it at "pValue". Two
andre@0:  *  objects which are equal should have the same hashcode. Once a call to
andre@0:  *  Hashcode has been made, the results are cached and subsequent calls to
andre@0:  *  Hashcode will return the cached value. For mutable objects, an
andre@0:  *  InvalidateCache function is provided, which should be called whenever
andre@0:  *  changes are made to the object's state (after creation).
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of the Object whose hashcode is desired. Must be non-NULL.
andre@0:  *      The HashcodeCallback for this object will be called.
andre@0:  *  "pValue"
andre@0:  *      Address where PKIX_Int32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  *
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on the callback defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Hashcode(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_UInt32 *pValue,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_ToString
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a string representation of the Object pointed to by "object" using
andre@0:  *  the callback registered for "object"'s type and stores it at "pString".
andre@0:  *  Once a call to ToString has been made, the results are cached and
andre@0:  *  subsequent calls to ToString will return the cached value. For mutable
andre@0:  *  objects, an InvalidateCache function is provided, which should be called
andre@0:  *  whenever changes are made to the object's state (after creation).
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose string representation is desired.
andre@0:  *      Must be non-NULL. The ToStringCallback for this object will be called.
andre@0:  *  "pString"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on the callback defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_ToString(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_PL_String **pString,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Compare
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Compares the Object pointed to by "firstObject" and the Object pointed to
andre@0:  *  by "secondObject" using the comparator registered for "firstObject"'s type
andre@0:  *  and stores the result at "pResult". Different types may be compared. This
andre@0:  *  may correctly result in cases where Compare(first, second) is not the
andre@0:  *  opposite of Compare(second, first). The PKIX_Int32 value stored at
andre@0:  *  "pResult" will be:
andre@0:  *   Less than 0 if "firstObject" < "secondObject"
andre@0:  *   Equals to 0 if "firstObject" = "secondObject"
andre@0:  *   Greater than 0 if "firstObject" > "secondObject"
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "firstObject"
andre@0:  *      Address of first Object to compare. Must be non-NULL.
andre@0:  *      The ComparatorCallback for this object will be called.
andre@0:  *  "secondObject"
andre@0:  *      Address of second object to compare. Must be non-NULL.
andre@0:  *  "pResult
andre@0:  *      Address where PKIX_Int32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on the comparator defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Compare(
andre@0:         PKIX_PL_Object *firstObject,
andre@0:         PKIX_PL_Object *secondObject,
andre@0:         PKIX_Int32 *pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Duplicate
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a duplicate copy of the Object pointed to by "object" using the
andre@0:  *  callback registered for "object"'s type and stores the copy at
andre@0:  *  "pNewObject". Changes to the new object will not affect the original and
andre@0:  *  vice versa.
andre@0:  *
andre@0:  *  Note that if "object" is immutable, the Duplicate callback function simply
andre@0:  *  needs to increment the reference count on "object" and return a reference
andre@0:  *  to "object".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object to be duplicated. Must be non-NULL.
andre@0:  *      The DuplicateCallback for this Object will be called.
andre@0:  *  "pNewObject"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread safety depends on the callback defined by PKIX_PL_RegisterType().
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an Object Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Duplicate(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_PL_Object **pNewObject,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_GetType
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the type code of the Object pointed to by "object" and stores it
andre@0:  *  at "pType". See pkixt.h for type codes.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose type is desired. Must be non-NULL.
andre@0:  *  "pType"
andre@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_GetType(
andre@0:         PKIX_PL_Object *object,
andre@0:         PKIX_UInt32 *pType,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Lock
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Locks the Mutex associated with the Object pointed to by "object". When an
andre@0:  *  object is created, it is associated with an object-specific Mutex to allow
andre@0:  *  for synchronization when the fields of the object are modified.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose Mutex is to be locked. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Lock(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Object_Unlock
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Unlocks the Mutex associated with the Object pointed to by "object". When
andre@0:  *  an object is created, it is associated with an object-specific Mutex to
andre@0:  *  allow for synchronization when the fields of the object are modified.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "object"
andre@0:  *      Address of Object whose Mutex is to be unlocked. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Object_Unlock(
andre@0:         PKIX_PL_Object *object,
andre@0:         void *plContext);
andre@0: 
andre@0: /* mutexes (locks) */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Mutex_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new Mutex and stores it at "pNewLock".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "pNewLock"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Mutex_Create(
andre@0:         PKIX_PL_Mutex **pNewLock,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Mutex_Lock
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Locks the Mutex pointed to by "lock". If the Mutex is already locked, this
andre@0:  *  function will block the current thread until the mutex can be locked by
andre@0:  *  this thread.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "lock"
andre@0:  *      Address of Mutex to lock. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Mutex_Lock(
andre@0:         PKIX_PL_Mutex *lock,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Mutex_Unlock
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Unlocks the Mutex pointed to by "lock" if the current thread holds the
andre@0:  *  Mutex.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "lock"
andre@0:  *      Address of Mutex to unlock. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Mutex_Unlock(
andre@0:         PKIX_PL_Mutex *lock,
andre@0:         void *plContext);
andre@0: 
andre@0: /* monitor (locks) */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_MonitorLock_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new PKIX_PL_MonitorLock and stores it at "pNewLock".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "pNewLock"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_MonitorLock_Create(
andre@0:         PKIX_PL_MonitorLock **pNewLock,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_MonitorLock_Enter
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Locks the MonitorLock pointed to by "lock". If the MonitorLock is already
andre@0:  *  locked by other thread, this function will block the current thread. If
andre@0:  *  the "lock" had been locked by current thread, this function will NOT block.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "lock"
andre@0:  *      Address of MonitorLock to lock. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_MonitorLock_Enter(
andre@0:         PKIX_PL_MonitorLock *lock,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_MonitorLock_Exit
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Unlocks the MonitorLock pointed to by "lock" if the lock counter of 
andre@0:  *  current thread holds the MonitorLock reach 0, the lock is released.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "lock"
andre@0:  *      Address of MonitorLock to unlock. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_MonitorLock_Exit(
andre@0:         PKIX_PL_MonitorLock *lock,
andre@0:         void *plContext);
andre@0: 
andre@0: /* strings and formatted printing */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_String_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new String using the data pointed to by "pString", the
andre@0:  *  PKIX_UInt32 pointed to by "stringLen", and the PKIX_UInt32 pointed to by
andre@0:  *  "fmtIndicator" and stores it at "pString". If the format is PKIX_ESCASCII
andre@0:  *  the "stringLen" parameter is ignored and the string extends until a zero
andre@0:  *  byte is  found. Once created, a String object is immutable.
andre@0:  *
andre@0:  *  Valid formats are:
andre@0:  *      PKIX_ESCASCII
andre@0:  *      PKIX_ESCASCII_DEBUG
andre@0:  *      PKIX_UTF8
andre@0:  *      PKIX_UTF8_NULL_TERM
andre@0:  *      PKIX_UTF16
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "fmtIndicator"
andre@0:  *      Format that "stringRep" is encoded with. Must be non-NULL.
andre@0:  *  "stringRep"
andre@0:  *      Address of encoded string representation. Must be non-NULL.
andre@0:  *  "stringLen"
andre@0:  *      Length of data stored at stringRep.
andre@0:  *  "pString"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a String Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_String_Create(
andre@0:         PKIX_UInt32 fmtIndicator,
andre@0:         const void *stringRep,
andre@0:         PKIX_UInt32 stringLen,
andre@0:         PKIX_PL_String **pString,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_Sprintf
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a formatted string at "pOut" using the given format "fmt" and a
andre@0:  *  variable length list of arguments. The format flags are identical to
andre@0:  *  standard C with the exception that %s expects a PKIX_PL_String*, rather
andre@0:  *  than a char *, and that {%d, %i, %o, %u, %x, %X} expect PKIX_UInt32 or
andre@0:  *  PKIX_Int32 instead of int or unsigned int.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "pOut"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  *  "fmt"
andre@0:  *      Address of format string. Must be non-NULL.
andre@0:  * THREAD SAFETY:
andre@0:  *  Not Thread Safe - Caller must have exclusive access to all arguments.
andre@0:  *  (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a String Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_Sprintf(
andre@0:         PKIX_PL_String **pOut,
andre@0:         void *plContext,
andre@0:         const PKIX_PL_String *fmt, ...);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_GetString
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the String associated with the value of "stringID" (if any) and
andre@0:  *  stores it at "pString". If no such string is associated with "stringID",
andre@0:  *  this function uses "defaultString" to create a String and stores it at
andre@0:  *  "pString".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "stringID"
andre@0:  *      PKIX_UInt32 valud of string identifier.
andre@0:  *  "defaultString"
andre@0:  *      Address of a PKIX_ESCASCII encoded string representation.
andre@0:  *      Must be non-NULL.
andre@0:  *  "pString"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a String Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_GetString(
andre@0:         PKIX_UInt32 stringID,
andre@0:         char *defaultString,
andre@0:         PKIX_PL_String **pString,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_String_GetEncoded
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the value of the String pointed to by "string" in the encoding
andre@0:  *  specified by "fmtIndicator" and stores the result in "pStringRep" and
andre@0:  *  "pLength", respectively. Note that "pStringRep" is not reference counted
andre@0:  *  and will need to be freed with PKIX_PL_Free().
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "string"
andre@0:  *      Address of String whose encoded value is desired. Must be non-NULL.
andre@0:  *  "fmtIndicator"
andre@0:  *      Format of encoding. Supported formats are:
andre@0:  *      PKIX_ESCASCII, PKIX_ESCASII_DEBUG, PKIX_UTF8, PKIX_UTF8_NULL_TERM, and
andre@0:  *      PKIX_UTF16. XXX Where are these documented?
andre@0:  *  "pStringRep"
andre@0:  *      Address where pointer to encoded value will be stored.
andre@0:  *      Must be non-NULL.
andre@0:  *  "pLength"
andre@0:  *      Address where byte length of encoded value will be stored.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a String Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_String_GetEncoded(
andre@0:         PKIX_PL_String *string,
andre@0:         PKIX_UInt32 fmtIndicator,
andre@0:         void **pStringRep,
andre@0:         PKIX_UInt32 *pLength,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * Hashtable
andre@0:  *
andre@0:  * A hashtable is a very efficient data structure used for mapping keys to
andre@0:  * values. Any non-null PKIX_PL_Object can be used as a key or as a value,
andre@0:  * provided that it correctly implements the PKIX_PL_EqualsCallback and the
andre@0:  * PKIX_PL_HashcodeCallback. A hashtable consists of several buckets, with
andre@0:  * each bucket capable of holding a linked list of key/value mappings. When
andre@0:  * adding, retrieving, or deleting a value, the hashcode of the key is used to
andre@0:  * determine which bucket's linked list is relevant. The corresponding
andre@0:  * key/value pair is then appended, retrieved, or deleted.
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_HashTable_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new Hashtable with an initial capacity of "numBuckets" buckets
andre@0:  *  and "maxEntriesPerBucket" of entries limit for each bucket and stores it
andre@0:  *  at "pResult".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "numBuckets"
andre@0:  *      The initial number of hash table buckets. Must be non-zero.
andre@0:  *  "maxEntriesPerBucket"
andre@0:  *      The limit of entries per bucket. Zero means no limit.
andre@0:  *  "pResult"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_HashTable_Create(
andre@0:         PKIX_UInt32 numBuckets,
andre@0:         PKIX_UInt32 maxEntriesPerBucket,
andre@0:         PKIX_PL_HashTable **pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_HashTable_Add
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Adds a key/value mapping using the Objects pointed to by "key" and "value"
andre@0:  *  to the Hashtable pointed to by "ht".
andre@0:  *
andre@0:  *  Function increments key/value reference counts. Caller is responsible to
andre@0:  *  to decrement(destroy) key/value ref counts(objects). 
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "ht"
andre@0:  *      Address of Hashtable to be added to. Must be non-NULL.
andre@0:  *  "key"
andre@0:  *      Address of Object to be associated with "value". Must be non-NULL.
andre@0:  *  "value"
andre@0:  *      Address of Object to be added to Hashtable. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Not Thread Safe - assumes exclusive access to "ht"
andre@0:  *  (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Hashtable Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_HashTable_Add(
andre@0:         PKIX_PL_HashTable *ht,
andre@0:         PKIX_PL_Object *key,
andre@0:         PKIX_PL_Object *value,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_HashTable_Remove
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Removes the Object value whose key is equal to the Object pointed to by
andre@0:  *  "key" from the Hashtable pointed to by "ht". If no such object exists,
andre@0:  *  this function throws an Error.
andre@0:  *
andre@0:  *  Function frees "value" object. Caller is responsible to free "key"
andre@0:  *  object.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "ht"
andre@0:  *      Address of Hashtable to remove object from. Must be non-NULL.
andre@0:  *  "key"
andre@0:  *      Address of Object used for lookup. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Not Thread Safe - assumes exclusive access to "ht"
andre@0:  *  (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Hashtable Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_HashTable_Remove(
andre@0:         PKIX_PL_HashTable *ht,
andre@0:         PKIX_PL_Object *key,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_HashTable_Lookup
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the Object whose key equals the Object pointed to by "key" from
andre@0:  *  the Hashtable associated with "ht" and stores it at "pResult". If no
andre@0:  *  Object is found, this function stores NULL at "pResult".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "ht"
andre@0:  *      Address of Hashtable to lookup Object from. Must be non-NULL.
andre@0:  *  "key"
andre@0:  *      Address of key Object used for lookup. Must be non-NULL.
andre@0:  *  "pResult"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Conditionally Thread Safe
andre@0:  *      (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Hashtable Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_HashTable_Lookup(
andre@0:         PKIX_PL_HashTable *ht,
andre@0:         PKIX_PL_Object *key,
andre@0:         PKIX_PL_Object **pResult,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_ByteArray_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new ByteArray using "length" bytes of data pointed to by "array"
andre@0:  *  and stores it at "pByteArray". Once created, a ByteArray is immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "array"
andre@0:  *      Address of source data.
andre@0:  *  "length"
andre@0:  *      Number of bytes to copy.
andre@0:  *  "pByteArray"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_ByteArray_Create(
andre@0:         void *array,
andre@0:         PKIX_UInt32 length,
andre@0:         PKIX_PL_ByteArray **pByteArray,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_ByteArray_GetPointer
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Allocates enough memory to hold the contents of the ByteArray pointed to
andre@0:  *  by "byteArray", copies the data from the ByteArray pointed to by
andre@0:  *  "byteArray" into the newly allocated memory, and stores a pointer to the
andre@0:  *  memory at "pArray". Note that "pArray" is not reference counted. It will
andre@0:  *  need to be freed with PKIX_PL_Free().
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "byteArray"
andre@0:  *      Address of ByteArray whose data is desired. Must be non-NULL.
andre@0:  *  "pArray"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_ByteArray_GetPointer(
andre@0:         PKIX_PL_ByteArray *byteArray,
andre@0:         void **pArray,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_ByteArray_GetLength
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the length of the ByteArray pointed to by "byteArray" and stores
andre@0:  *  the length at "pLength".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "byteArray"
andre@0:  *      Address of ByteArray whose length is desired. Must be non-NULL.
andre@0:  *  "pLength"
andre@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_ByteArray_GetLength(
andre@0:         PKIX_PL_ByteArray *byteArray,
andre@0:         PKIX_UInt32 *pLength,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_OID_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new OID using NSS oid tag.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "idtag"
andre@0:  *      nss oid id tag.
andre@0:  *  "pOID"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an OID Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_OID_Create(
andre@0:         SECOidTag idtag,
andre@0:         PKIX_PL_OID **pOID,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_OID_CreateBySECItem
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new OID using a DER encoded OID stored as SECItem.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "derOid"
andre@0:  *      Address of SECItem that holds DER encoded OID.
andre@0:  *  "pOID"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns an OID Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_OID_CreateBySECItem(
andre@0:         SECItem *derOid,
andre@0:         PKIX_PL_OID **pOID,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_BigInt_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new BigInt using the source String pointed to by "stringRep" and
andre@0:  *  stores it at "pBigInt". Valid source Strings consist of an even number of
andre@0:  *  hexadecimal digits, which are always interpreted as a positive number.
andre@0:  *  Once created, a BigInt is immutable.
andre@0:  *
andre@0:  *  The regexp format is:
andre@0:  *      HexDigit  ::= [0-9] | [A-F] | [a-f]
andre@0:  *      DoubleHex ::= HexDigit HexDigit
andre@0:  *      BigIntSrc ::= (DoubleHex)+
andre@0:  *
andre@0:  *  Note that since we are using DoubleHex, the number of characters in the
andre@0:  *  source MUST be even. Additionally, the first DoubleHex MUST NOT be "00"
andre@0:  *  unless it is the only DoubleHex.
andre@0:  *
andre@0:  *  Valid  :    "09"
andre@0:  *  Valid  :    "00"    (special case where first and only DoubleHex is "00")
andre@0:  *  Invalid:    "9"     (not DoubleHex: odd number of characters)
andre@0:  *  Invalid:    "0009"  (first DoubleHex is "00")
andre@0:  *
andre@0:  *  XXX Why does this take a String object while OID_Create takes a char* ?
andre@0:  *  Perhaps because OID_Create is often used with constant strings and
andre@0:  *  this function isn't. That's a good reason, but we should explain it
andre@0:  *  (if it's right)
andre@0:  * PARAMETERS:
andre@0:  *  "stringRep"
andre@0:  *      Address of String representing a BigInt. Must be non-NULL.
andre@0:  *  "pBigInt"
andre@0:  *      Address where object pointer will be stored. Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  Returns NULL if the function succeeds.
andre@0:  *  Returns a BigInt Error if the function fails in a non-fatal way.
andre@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_PL_BigInt_Create(
andre@0:         PKIX_PL_String *stringRep,
andre@0:         PKIX_PL_BigInt **pBigInt,
andre@0:         void *plContext);
andre@0: 
andre@0: #ifdef __cplusplus
andre@0: }
andre@0: #endif
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_PL_GetPLErrorCode
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Returns error code from PL layer.
andre@0:  *
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
andre@0:  * RETURNS:
andre@0:  *  PL layer error code. 
andre@0:  */
andre@0: int
andre@0: PKIX_PL_GetPLErrorCode();
andre@0: 
andre@0: #endif /* _LIBPKIX_SYSTEM_H */