michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: /*
michael@0:  * These functions provide support for a number of other functions
michael@0:  * by creating and manipulating data structures used by those functions.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: #ifndef _PKIX_UTIL_H
michael@0: #define _PKIX_UTIL_H
michael@0: 
michael@0: #include "pkixt.h"
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: /* General
michael@0:  *
michael@0:  * Please refer to the libpkix Programmer's Guide for detailed information
michael@0:  * about how to use the libpkix library. Certain key warnings and notices from
michael@0:  * that document are repeated here for emphasis.
michael@0:  *
michael@0:  * All identifiers in this file (and all public identifiers defined in
michael@0:  * libpkix) begin with "PKIX_". Private identifiers only intended for use
michael@0:  * within the library begin with "pkix_".
michael@0:  *
michael@0:  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
michael@0:  *
michael@0:  * Unless otherwise noted, for all accessor (gettor) functions that return a
michael@0:  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
michael@0:  * shared object. Therefore, the caller should treat this shared object as
michael@0:  * read-only and should not modify this shared object. When done using the
michael@0:  * shared object, the caller should release the reference to the object by
michael@0:  * using the PKIX_PL_Object_DecRef function.
michael@0:  *
michael@0:  * While a function is executing, if its arguments (or anything referred to by
michael@0:  * its arguments) are modified, free'd, or destroyed, the function's behavior
michael@0:  * is undefined.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: /* PKIX_Logger
michael@0:  *
michael@0:  * PKIX_Loggers provide a standard way for the caller to insert custom logging
michael@0:  * facilities. These are used by libpkix to log errors, debug information,
michael@0:  * status, etc. The LogCallback allows custom logging to take place.
michael@0:  * Additionally, a Logger can be initialized with a loggerContext, which is
michael@0:  * where the caller can specify configuration data such as the name of a
michael@0:  * logfile or database. Note that this loggerContext must be a PKIX_PL_Object,
michael@0:  * allowing it to be reference-counted and allowing it to provide the standard
michael@0:  * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
michael@0:  *
michael@0:  * Once the caller has created the Logger object(s) (and set the loggerContext
michael@0:  * (if any) and the Log callback), the caller then registers these Loggers
michael@0:  * with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log
michael@0:  * entries will then be logged using the specified Loggers. If multiple
michael@0:  * Loggers are specified, every log entry will be logged with each of them.
michael@0:  *
michael@0:  * XXX Maybe give some guidance somewhere on how much detail each logging
michael@0:  * level should have and where component boundaries should be. Maybe in
michael@0:  * Implementor's Guide or Programmer's Guide.
michael@0:  */
michael@0: 
michael@0: #define PKIX_LOGGER_LEVEL_TRACE                5
michael@0: #define PKIX_LOGGER_LEVEL_DEBUG                4
michael@0: #define PKIX_LOGGER_LEVEL_WARNING              3
michael@0: #define PKIX_LOGGER_LEVEL_ERROR                2
michael@0: #define PKIX_LOGGER_LEVEL_FATALERROR           1
michael@0: 
michael@0: #define PKIX_LOGGER_LEVEL_MAX                  5
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_LogCallback
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  This callback function logs a log entry containing the String pointed to
michael@0:  *  by "message", the integer value of logLevel, and the String pointed to by
michael@0:  *  "logComponent". A log entry can be associated with a particular log
michael@0:  *  level (i.e. level 3) and a particular log component (i.e. "CertStore").
michael@0:  *  For example, someone reading the log may only be interested in very general
michael@0:  *  log entries so they look only for log level 1. Similarly, they may only be
michael@0:  *  interested in log entries pertaining to the CertStore component so they
michael@0:  *  look only for that log component. This function can be used before calling
michael@0:  *  PKIX_Initialize.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of logger whose LogCallback is to be used. Must be non-NULL.
michael@0:  *  "message"
michael@0:  *      Address of String that is to be logged used "logger". Must be non-NULL.
michael@0:  *  "logLevel"
michael@0:  *      Integer value representing the log level for this entry. The higher the
michael@0:  *      level, the more detail. Must be non-NULL.
michael@0:  *  "logComponent"
michael@0:  *      PKIXERRORNUM value (defined in pkixt.h) designating the log component
michael@0:  *      for this entry.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe
michael@0:  *
michael@0:  *  Multiple threads must be able to safely call this function without
michael@0:  *  worrying about conflicts, even if they're operating on the same objects.
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: typedef PKIX_Error *
michael@0: (*PKIX_Logger_LogCallback)(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_PL_String *message,
michael@0:         PKIX_UInt32 logLevel,
michael@0:         PKIX_ERRORCLASS logComponent,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new Logger using the Object pointed to by "loggerContext"
michael@0:  *  (if any) and stores it at "pLogger". The new Logger uses the LogCallback
michael@0:  *  pointed to by "callback". The Logger's maximum logging level is initially
michael@0:  *  set to a very high level and its logging component is set to NULL (all
michael@0:  *  components).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "callback"
michael@0:  *      The LogCallback function to be used. Must be non-NULL.
michael@0:  *  "loggerContext"
michael@0:  *      Address of Object representing the Logger's context (if any).
michael@0:  *  "pLogger"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_Create(
michael@0:         PKIX_Logger_LogCallback callback,
michael@0:         PKIX_PL_Object *loggerContext,
michael@0:         PKIX_Logger **pLogger,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_GetLogCallback
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to "logger's" Log callback function and puts it in
michael@0:  *  "pCallback".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose Log callback is desired. Must be non-NULL.
michael@0:  *  "pCallback"
michael@0:  *      Address where Log callback function pointer will be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_GetLogCallback(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_Logger_LogCallback *pCallback,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_GetLoggerContext
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
michael@0:  *  of the Logger pointed to by "logger" and stores it at "pLoggerContext".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose context is to be stored. Must be non-NULL.
michael@0:  *  "pLoggerContext"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_GetLoggerContext(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_PL_Object **pLoggerContext,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_GetMaxLoggingLevel
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to a PKIX_UInt32 representing the maximum logging
michael@0:  *  level of the Logger pointed to by "logger" and stores it at "pLevel". Only
michael@0:  *  log entries whose log level is less than or equal to this maximum logging
michael@0:  *  level will be logged.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose maximum logging level is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pLevel"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_GetMaxLoggingLevel(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_UInt32 *pLevel,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_SetMaxLoggingLevel
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum logging level of the Logger pointed to by "logger" with
michael@0:  *  the integer value of "level".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose maximum logging level is to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "level"
michael@0:  *      Maximum logging level to be set
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "logger"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_SetMaxLoggingLevel(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_UInt32 level,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_GetLoggingComponent
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to a String representing the logging component of the
michael@0:  *  Logger pointed to by "logger" and stores it at "pComponent". Only log
michael@0:  *  entries whose log component matches the specified logging component will
michael@0:  *  be logged.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose logging component is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pComponent"
michael@0:  *      Address where PKIXERRORNUM will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_GetLoggingComponent(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_ERRORCLASS *pComponent,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Logger_SetLoggingComponent
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the logging component of the Logger pointed to by "logger" with the
michael@0:  *  PKIXERRORNUM pointed to by "component". To match a small set of components,
michael@0:  *  create a Logger for each.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger whose logging component is to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "component"
michael@0:  *      PKIXERRORNUM value representing logging component to be set.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "logger"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Logger_SetLoggingComponent(
michael@0:         PKIX_Logger *logger,
michael@0:         PKIX_ERRORCLASS component,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_GetLoggers
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of Loggers (if any) being used for logging
michael@0:  *  by libpkix and stores it at "pLoggers". If no loggers are being used, this
michael@0:  *  function stores an empty List at "pLoggers".
michael@0:  *
michael@0:  *  Note that the List returned by this function is immutable.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "pLoggers"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_GetLoggers(
michael@0:         PKIX_List **pLoggers,  /* list of PKIX_Logger */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_SetLoggers
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the Loggers to be used by libpkix to the List of Loggers pointed to
michael@0:  *  by "loggers". If "loggers" is NULL, no Loggers will be used.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "loggers"
michael@0:  *      Address of List of Loggers to be set. NULL for no Loggers.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_SetLoggers(
michael@0:         PKIX_List *loggers,  /* list of PKIX_Logger */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_AddLogger
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Adds the Logger pointed to by "logger" to the List of Loggers used by
michael@0:  *  libpkix.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "logger"
michael@0:  *      Address of Logger to be added. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Logger Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_AddLogger(
michael@0:         PKIX_Logger *logger,
michael@0:         void *plContext);
michael@0: 
michael@0: /* Functions pertaining to the PKIX_Error type */
michael@0: 
michael@0: /* Error
michael@0:  *
michael@0:  * An Error object is returned by a function upon encountering some error
michael@0:  * condition. Each Error is associated with an errorCode specified in pkixt.h.
michael@0:  * The remaining components of an Error are optional. An Error's description
michael@0:  * specifies a text message describing the Error. An Error's supplementary info
michael@0:  * specifies additional information that might be useful. Finally, an Error's
michael@0:  * cause specifies the underlying Error (if any) that resulted in this Error
michael@0:  * being returned, thereby allowing Errors to be chained so that an entire
michael@0:  * "error stack trace" can be represented. Once created, an Error is immutable.
michael@0:  *
michael@0:  * Note that the Error's supplementary info must be an Object (although any
michael@0:  * object type), allowing it to be reference-counted and allowing it to
michael@0:  * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
michael@0:  * Duplicate).
michael@0:  *
michael@0:  * Errors are classified as either being fatal or non-fatal. If a function
michael@0:  * fails in an unrecoverable way, it returns an Error whose errorCode is
michael@0:  * PKIX_FATAL_ERROR. If such an error is encountered, the caller should
michael@0:  * not attempt to recover since something seriously wrong has happened
michael@0:  * (e.g. corrupted memory, memory finished, etc.). All other errorCodes
michael@0:  * are considered non-fatal errors and can be handled by the caller as they
michael@0:  * see fit.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new Error using the value of "errorCode", the Error pointed to by
michael@0:  *  "cause" (if any), the Object pointed to by "info" (if any), and the String
michael@0:  *  pointed to by "desc" and stores it at "pError". If any error occurs during
michael@0:  *  error allocation, it will be returned without chaining, since new errors
michael@0:  *  cannot be created. Once created, an Error is immutable.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "errorCode"
michael@0:  *      Value of error code.
michael@0:  *  "cause"
michael@0:  *      Address of Error representing error's cause.
michael@0:  *      NULL if none or unspecified.
michael@0:  *  "info"
michael@0:  *      Address of Object representing error's supplementary information.
michael@0:  *      NULL if none.
michael@0:  *  "desc"
michael@0:  *      Address of String representing error's description. NULL if none.
michael@0:  *  "pError"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_Create(
michael@0:         PKIX_ERRORCLASS errClass,
michael@0:         PKIX_Error *cause,
michael@0:         PKIX_PL_Object *info,
michael@0:         PKIX_ERRORCODE errCode,
michael@0:         PKIX_Error **pError,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_GetErrorClass
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the error class of the Error pointed to by "error" and 
michael@0:  *  stores it at "pClass". Supported error codes are defined in pkixt.h.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "error"
michael@0:  *      Address of Error whose error code is desired. Must be non-NULL.
michael@0:  *  "pClass"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_GetErrorClass(
michael@0:         PKIX_Error *error,
michael@0:         PKIX_ERRORCLASS *pClass,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_GetErrorCode
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the error code of the Error pointed to by "error" and 
michael@0:  *  stores it at "pCode". Supported error codes are defined in pkixt.h.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "error"
michael@0:  *      Address of Error whose error code is desired. Must be non-NULL.
michael@0:  *  "pCode"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_GetErrorCode(
michael@0:         PKIX_Error *error,
michael@0:         PKIX_ERRORCODE *pCode,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_GetCause
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the cause of the Error pointed to by "error" and stores it at
michael@0:  *  "pCause". If no cause was specified, NULL will be stored at "pCause".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "error"
michael@0:  *      Address of Error whose cause is desired. Must be non-NULL.
michael@0:  *  "pCause"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_GetCause(
michael@0:         PKIX_Error *error,
michael@0:         PKIX_Error **pCause,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_GetSupplementaryInfo
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the supplementary info of the Error pointed to by "error" and
michael@0:  *  stores it at "pInfo".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "error"
michael@0:  *      Address of Error whose info is desired. Must be non-NULL.
michael@0:  *  "pInfo"
michael@0:  *      Address where info pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_GetSupplementaryInfo(
michael@0:         PKIX_Error *error,
michael@0:         PKIX_PL_Object **pInfo,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_Error_GetDescription
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the description of the Error pointed to by "error" and stores it
michael@0:  *  at "pDesc". If no description was specified, NULL will be stored at
michael@0:  *  "pDesc".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "error"
michael@0:  *      Address of Error whose description is desired. Must be non-NULL.
michael@0:  *  "pDesc"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns an Error Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_Error_GetDescription(
michael@0:         PKIX_Error *error,
michael@0:         PKIX_PL_String **pDesc,
michael@0:         void *plContext);
michael@0: 
michael@0: /* PKIX_List
michael@0:  *
michael@0:  * Represents a collection of items. NULL is considered a valid item.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new List and stores it at "pList". The List is initially empty
michael@0:  *  and holds no items. To initially add items to the List, use
michael@0:  *  PKIX_List_AppendItem
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "pList"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_Create(
michael@0:         PKIX_List **pList,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_SetImmutable
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the List pointed to by "list" to be immutable. If a caller tries to
michael@0:  *  change a List after it has been marked immutable (i.e. by calling
michael@0:  *  PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
michael@0:  *  PKIX_List_DeleteItem), an Error is returned.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to be marked immutable. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "list"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_SetImmutable(
michael@0:         PKIX_List *list,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_IsImmutable
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the List pointed to by "list" is immutable and stores
michael@0:  *  the Boolean result at "pImmutable". If a caller tries to change a List
michael@0:  *  after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
michael@0:  *  PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
michael@0:  *  Error is returned.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List whose immutability is to be determined.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pImmutable"
michael@0:  *      Address where PKIX_Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_IsImmutable(
michael@0:         PKIX_List *list,
michael@0:         PKIX_Boolean *pImmutable,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_GetLength
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves the length of the List pointed to by "list" and stores it at
michael@0:  *  "pLength".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List whose length is desired. Must be non-NULL.
michael@0:  *  "pLength"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_GetLength(
michael@0:         PKIX_List *list,
michael@0:         PKIX_UInt32 *pLength,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_IsEmpty
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the List pointed to by "list" is empty and stores
michael@0:  *  the Boolean result at "pEmpty".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List whose emptiness is to be determined. Must be non-NULL.
michael@0:  *  "pEmpty"
michael@0:  *      Address where PKIX_Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_IsEmpty(
michael@0:         PKIX_List *list,
michael@0:         PKIX_Boolean *pEmpty,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_AppendItem
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Appends the Object pointed to by "item" after the last non-NULL item in
michael@0:  *  List pointed to by "list", if any. Note that a List may validly contain
michael@0:  *  NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
michael@0:  *  in ("a", NULL, "b", "c").
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to append to. Must be non-NULL.
michael@0:  *  "item"
michael@0:  *      Address of new item to append.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "list"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_AppendItem(
michael@0:         PKIX_List *list,
michael@0:         PKIX_PL_Object *item,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_InsertItem
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Inserts the Object pointed to by "item" into the List pointed to by "list"
michael@0:  *  at the given "index". The index counts from zero and must be less than the
michael@0:  *  List's length. Existing list entries at or after this index will be moved
michael@0:  *  to the next highest index.
michael@0:  *
michael@0:  *  XXX why not allow equal to length which would be equivalent to AppendItem?
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to insert into. Must be non-NULL.
michael@0:  *  "index"
michael@0:  *      Position to insert into. Must be less than List's length.
michael@0:  *  "item"
michael@0:  *      Address of new item to append.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "list"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_InsertItem(
michael@0:         PKIX_List *list,
michael@0:         PKIX_UInt32 index,
michael@0:         PKIX_PL_Object *item,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_GetItem
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Copies the "list"'s item at "index" into "pItem". The index counts from
michael@0:  *  zero and must be less than the list's length. Increments the reference
michael@0:  *  count on the returned object, if non-NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to get item from. Must be non-NULL.
michael@0:  *  "index"
michael@0:  *      Index of list to get item from. Must be less than List's length.
michael@0:  *  "pItem"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_GetItem(
michael@0:         PKIX_List *list,
michael@0:         PKIX_UInt32 index,
michael@0:         PKIX_PL_Object **pItem,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_SetItem
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the item at "index" of the List pointed to by "list" with the Object
michael@0:  *  pointed to by "item". The index counts from zero and must be less than the
michael@0:  *  List's length. The previous entry at this index will have its reference
michael@0:  *  count decremented and the new entry will have its reference count
michael@0:  *  incremented.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to modify. Must be non-NULL.
michael@0:  *  "index"
michael@0:  *      Position in List to set. Must be less than List's length.
michael@0:  *  "item"
michael@0:  *      Address of Object to set at "index".
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "list"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_SetItem(
michael@0:         PKIX_List *list,
michael@0:         PKIX_UInt32 index,
michael@0:         PKIX_PL_Object *item,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_DeleteItem
michael@0:  *
michael@0:  *  Deletes the item at "index" from the List pointed to by "list". The index
michael@0:  *  counts from zero and must be less than the List's length. Note that this
michael@0:  *  function does not destroy the List. It simply decrements the reference
michael@0:  *  count of the item at "index" in the List, deletes that item from the list
michael@0:  *  and moves all subsequent entries to a lower index in the list. If there is
michael@0:  *  only a single element in the List and that element is deleted, then the
michael@0:  *  List will be empty.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List to delete from. Must be non-NULL.
michael@0:  *  "index"
michael@0:  *      Position in List to delete. Must be less than List's length.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "list"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_DeleteItem(
michael@0:         PKIX_List *list,
michael@0:         PKIX_UInt32 index,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_List_ReverseList
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new List whose elements are in the reverse order as the elements
michael@0:  *  of the Object pointed to by "list" and stores the copy at "pReversedList".
michael@0:  *  If "list" is empty, the new reversed List will be a copy of "list".
michael@0:  *  Changes to the new object will not affect the original and vice versa.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "list"
michael@0:  *      Address of List whose elements are to be reversed. Must be non-NULL.
michael@0:  *  "pReversedList"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_List_ReverseList(
michael@0:         PKIX_List *list,
michael@0:         PKIX_List **pReversedList,
michael@0:         void *plContext);
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #endif /* _PKIX_UTIL_H */