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