mirror of
https://github.com/rn10950/RetroZilla.git
synced 2024-11-14 03:30:17 +01:00
942 lines
31 KiB
C
942 lines
31 KiB
C
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
/*
|
|
* These functions provide support for a number of other functions
|
|
* by creating and manipulating data structures used by those functions.
|
|
*
|
|
*/
|
|
|
|
#ifndef _PKIX_UTIL_H
|
|
#define _PKIX_UTIL_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.
|
|
*
|
|
*/
|
|
|
|
/* PKIX_Logger
|
|
*
|
|
* PKIX_Loggers provide a standard way for the caller to insert custom logging
|
|
* facilities. These are used by libpkix to log errors, debug information,
|
|
* status, etc. The LogCallback allows custom logging to take place.
|
|
* Additionally, a Logger can be initialized with a loggerContext, which is
|
|
* where the caller can specify configuration data such as the name of a
|
|
* logfile or database. Note that this loggerContext must be a PKIX_PL_Object,
|
|
* allowing it to be reference-counted and allowing it to provide the standard
|
|
* PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
|
|
*
|
|
* Once the caller has created the Logger object(s) (and set the loggerContext
|
|
* (if any) and the Log callback), the caller then registers these Loggers
|
|
* with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log
|
|
* entries will then be logged using the specified Loggers. If multiple
|
|
* Loggers are specified, every log entry will be logged with each of them.
|
|
*
|
|
* XXX Maybe give some guidance somewhere on how much detail each logging
|
|
* level should have and where component boundaries should be. Maybe in
|
|
* Implementor's Guide or Programmer's Guide.
|
|
*/
|
|
|
|
#define PKIX_LOGGER_LEVEL_TRACE 5
|
|
#define PKIX_LOGGER_LEVEL_DEBUG 4
|
|
#define PKIX_LOGGER_LEVEL_WARNING 3
|
|
#define PKIX_LOGGER_LEVEL_ERROR 2
|
|
#define PKIX_LOGGER_LEVEL_FATALERROR 1
|
|
|
|
#define PKIX_LOGGER_LEVEL_MAX 5
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_LogCallback
|
|
* DESCRIPTION:
|
|
*
|
|
* This callback function logs a log entry containing the String pointed to
|
|
* by "message", the integer value of logLevel, and the String pointed to by
|
|
* "logComponent". A log entry can be associated with a particular log
|
|
* level (i.e. level 3) and a particular log component (i.e. "CertStore").
|
|
* For example, someone reading the log may only be interested in very general
|
|
* log entries so they look only for log level 1. Similarly, they may only be
|
|
* interested in log entries pertaining to the CertStore component so they
|
|
* look only for that log component. This function can be used before calling
|
|
* PKIX_Initialize.
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of logger whose LogCallback is to be used. Must be non-NULL.
|
|
* "message"
|
|
* Address of String that is to be logged used "logger". Must be non-NULL.
|
|
* "logLevel"
|
|
* Integer value representing the log level for this entry. The higher the
|
|
* level, the more detail. Must be non-NULL.
|
|
* "logComponent"
|
|
* PKIXERRORNUM value (defined in pkixt.h) designating the log component
|
|
* for this entry.
|
|
* "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 a Logger 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_Logger_LogCallback)(
|
|
PKIX_Logger *logger,
|
|
PKIX_PL_String *message,
|
|
PKIX_UInt32 logLevel,
|
|
PKIX_ERRORCLASS logComponent,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_Create
|
|
* DESCRIPTION:
|
|
*
|
|
* Creates a new Logger using the Object pointed to by "loggerContext"
|
|
* (if any) and stores it at "pLogger". The new Logger uses the LogCallback
|
|
* pointed to by "callback". The Logger's maximum logging level is initially
|
|
* set to a very high level and its logging component is set to NULL (all
|
|
* components).
|
|
*
|
|
* PARAMETERS:
|
|
* "callback"
|
|
* The LogCallback function to be used. Must be non-NULL.
|
|
* "loggerContext"
|
|
* Address of Object representing the Logger's context (if any).
|
|
* "pLogger"
|
|
* 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 Logger 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_Logger_Create(
|
|
PKIX_Logger_LogCallback callback,
|
|
PKIX_PL_Object *loggerContext,
|
|
PKIX_Logger **pLogger,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_GetLogCallback
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves a pointer to "logger's" Log callback function and puts it in
|
|
* "pCallback".
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose Log callback is desired. Must be non-NULL.
|
|
* "pCallback"
|
|
* Address where Log callback function 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 Logger 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_Logger_GetLogCallback(
|
|
PKIX_Logger *logger,
|
|
PKIX_Logger_LogCallback *pCallback,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_GetLoggerContext
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
|
|
* of the Logger pointed to by "logger" and stores it at "pLoggerContext".
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose context is to be stored. Must be non-NULL.
|
|
* "pLoggerContext"
|
|
* 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 Logger 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_Logger_GetLoggerContext(
|
|
PKIX_Logger *logger,
|
|
PKIX_PL_Object **pLoggerContext,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_GetMaxLoggingLevel
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves a pointer to a PKIX_UInt32 representing the maximum logging
|
|
* level of the Logger pointed to by "logger" and stores it at "pLevel". Only
|
|
* log entries whose log level is less than or equal to this maximum logging
|
|
* level will be logged.
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose maximum logging level is to be stored.
|
|
* Must be non-NULL.
|
|
* "pLevel"
|
|
* Address where PKIX_UInt32 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 Logger 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_Logger_GetMaxLoggingLevel(
|
|
PKIX_Logger *logger,
|
|
PKIX_UInt32 *pLevel,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_SetMaxLoggingLevel
|
|
* DESCRIPTION:
|
|
*
|
|
* Sets the maximum logging level of the Logger pointed to by "logger" with
|
|
* the integer value of "level".
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose maximum logging level is to be set.
|
|
* Must be non-NULL.
|
|
* "level"
|
|
* Maximum logging level to be set
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "logger"
|
|
* (see Thread Safety Definitions in Programmer's Guide)
|
|
* RETURNS:
|
|
* Returns NULL if the function succeeds.
|
|
* Returns a Logger 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_Logger_SetMaxLoggingLevel(
|
|
PKIX_Logger *logger,
|
|
PKIX_UInt32 level,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_GetLoggingComponent
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves a pointer to a String representing the logging component of the
|
|
* Logger pointed to by "logger" and stores it at "pComponent". Only log
|
|
* entries whose log component matches the specified logging component will
|
|
* be logged.
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose logging component is to be stored.
|
|
* Must be non-NULL.
|
|
* "pComponent"
|
|
* Address where PKIXERRORNUM 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 Logger 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_Logger_GetLoggingComponent(
|
|
PKIX_Logger *logger,
|
|
PKIX_ERRORCLASS *pComponent,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Logger_SetLoggingComponent
|
|
* DESCRIPTION:
|
|
*
|
|
* Sets the logging component of the Logger pointed to by "logger" with the
|
|
* PKIXERRORNUM pointed to by "component". To match a small set of components,
|
|
* create a Logger for each.
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger whose logging component is to be set.
|
|
* Must be non-NULL.
|
|
* "component"
|
|
* PKIXERRORNUM value representing logging component to be set.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "logger"
|
|
* (see Thread Safety Definitions in Programmer's Guide)
|
|
* RETURNS:
|
|
* Returns NULL if the function succeeds.
|
|
* Returns a Logger 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_Logger_SetLoggingComponent(
|
|
PKIX_Logger *logger,
|
|
PKIX_ERRORCLASS component,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_GetLoggers
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves a pointer to the List of Loggers (if any) being used for logging
|
|
* by libpkix and stores it at "pLoggers". If no loggers are being used, this
|
|
* function stores an empty List at "pLoggers".
|
|
*
|
|
* Note that the List returned by this function is immutable.
|
|
*
|
|
* PARAMETERS:
|
|
* "pLoggers"
|
|
* 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 Logger 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_GetLoggers(
|
|
PKIX_List **pLoggers, /* list of PKIX_Logger */
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_SetLoggers
|
|
* DESCRIPTION:
|
|
*
|
|
* Sets the Loggers to be used by libpkix to the List of Loggers pointed to
|
|
* by "loggers". If "loggers" is NULL, no Loggers will be used.
|
|
*
|
|
* PARAMETERS:
|
|
* "loggers"
|
|
* Address of List of Loggers to be set. NULL for no Loggers.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe
|
|
* (see Thread Safety Definitions in Programmer's Guide)
|
|
* RETURNS:
|
|
* Returns NULL if the function succeeds.
|
|
* Returns a Logger 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_SetLoggers(
|
|
PKIX_List *loggers, /* list of PKIX_Logger */
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_AddLogger
|
|
* DESCRIPTION:
|
|
*
|
|
* Adds the Logger pointed to by "logger" to the List of Loggers used by
|
|
* libpkix.
|
|
*
|
|
* PARAMETERS:
|
|
* "logger"
|
|
* Address of Logger to be added. Must be non-NULL.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe
|
|
* (see Thread Safety Definitions in Programmer's Guide)
|
|
* RETURNS:
|
|
* Returns NULL if the function succeeds.
|
|
* Returns a Logger 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_AddLogger(
|
|
PKIX_Logger *logger,
|
|
void *plContext);
|
|
|
|
/* Functions pertaining to the PKIX_Error type */
|
|
|
|
/* Error
|
|
*
|
|
* An Error object is returned by a function upon encountering some error
|
|
* condition. Each Error is associated with an errorCode specified in pkixt.h.
|
|
* The remaining components of an Error are optional. An Error's description
|
|
* specifies a text message describing the Error. An Error's supplementary info
|
|
* specifies additional information that might be useful. Finally, an Error's
|
|
* cause specifies the underlying Error (if any) that resulted in this Error
|
|
* being returned, thereby allowing Errors to be chained so that an entire
|
|
* "error stack trace" can be represented. Once created, an Error is immutable.
|
|
*
|
|
* Note that the Error's supplementary info must be an Object (although any
|
|
* object type), allowing it to be reference-counted and allowing it to
|
|
* provide the standard Object functions (Equals, Hashcode, ToString, Compare,
|
|
* Duplicate).
|
|
*
|
|
* Errors are classified as either being fatal or non-fatal. If a function
|
|
* fails in an unrecoverable way, it returns an Error whose errorCode is
|
|
* PKIX_FATAL_ERROR. If such an error is encountered, the caller should
|
|
* not attempt to recover since something seriously wrong has happened
|
|
* (e.g. corrupted memory, memory finished, etc.). All other errorCodes
|
|
* are considered non-fatal errors and can be handled by the caller as they
|
|
* see fit.
|
|
*/
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_Create
|
|
* DESCRIPTION:
|
|
*
|
|
* Creates a new Error using the value of "errorCode", the Error pointed to by
|
|
* "cause" (if any), the Object pointed to by "info" (if any), and the String
|
|
* pointed to by "desc" and stores it at "pError". If any error occurs during
|
|
* error allocation, it will be returned without chaining, since new errors
|
|
* cannot be created. Once created, an Error is immutable.
|
|
*
|
|
* PARAMETERS:
|
|
* "errorCode"
|
|
* Value of error code.
|
|
* "cause"
|
|
* Address of Error representing error's cause.
|
|
* NULL if none or unspecified.
|
|
* "info"
|
|
* Address of Object representing error's supplementary information.
|
|
* NULL if none.
|
|
* "desc"
|
|
* Address of String representing error's description. NULL if none.
|
|
* "pError"
|
|
* 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 Error 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_Error_Create(
|
|
PKIX_ERRORCLASS errClass,
|
|
PKIX_Error *cause,
|
|
PKIX_PL_Object *info,
|
|
PKIX_ERRORCODE errCode,
|
|
PKIX_Error **pError,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_GetErrorClass
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the error class of the Error pointed to by "error" and
|
|
* stores it at "pClass". Supported error codes are defined in pkixt.h.
|
|
*
|
|
* PARAMETERS:
|
|
* "error"
|
|
* Address of Error whose error code is desired. Must be non-NULL.
|
|
* "pClass"
|
|
* 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 an Error 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_Error_GetErrorClass(
|
|
PKIX_Error *error,
|
|
PKIX_ERRORCLASS *pClass,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_GetErrorCode
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the error code of the Error pointed to by "error" and
|
|
* stores it at "pCode". Supported error codes are defined in pkixt.h.
|
|
*
|
|
* PARAMETERS:
|
|
* "error"
|
|
* Address of Error whose error code is desired. Must be non-NULL.
|
|
* "pCode"
|
|
* 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 an Error 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_Error_GetErrorCode(
|
|
PKIX_Error *error,
|
|
PKIX_ERRORCODE *pCode,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_GetCause
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the cause of the Error pointed to by "error" and stores it at
|
|
* "pCause". If no cause was specified, NULL will be stored at "pCause".
|
|
*
|
|
* PARAMETERS:
|
|
* "error"
|
|
* Address of Error whose cause is desired. Must be non-NULL.
|
|
* "pCause"
|
|
* 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 Error 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_Error_GetCause(
|
|
PKIX_Error *error,
|
|
PKIX_Error **pCause,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_GetSupplementaryInfo
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the supplementary info of the Error pointed to by "error" and
|
|
* stores it at "pInfo".
|
|
*
|
|
* PARAMETERS:
|
|
* "error"
|
|
* Address of Error whose info is desired. Must be non-NULL.
|
|
* "pInfo"
|
|
* Address where info 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 Error 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_Error_GetSupplementaryInfo(
|
|
PKIX_Error *error,
|
|
PKIX_PL_Object **pInfo,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_Error_GetDescription
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the description of the Error pointed to by "error" and stores it
|
|
* at "pDesc". If no description was specified, NULL will be stored at
|
|
* "pDesc".
|
|
*
|
|
* PARAMETERS:
|
|
* "error"
|
|
* Address of Error whose description is desired. Must be non-NULL.
|
|
* "pDesc"
|
|
* 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 Error 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_Error_GetDescription(
|
|
PKIX_Error *error,
|
|
PKIX_PL_String **pDesc,
|
|
void *plContext);
|
|
|
|
/* PKIX_List
|
|
*
|
|
* Represents a collection of items. NULL is considered a valid item.
|
|
*/
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_Create
|
|
* DESCRIPTION:
|
|
*
|
|
* Creates a new List and stores it at "pList". The List is initially empty
|
|
* and holds no items. To initially add items to the List, use
|
|
* PKIX_List_AppendItem
|
|
*
|
|
* PARAMETERS:
|
|
* "pList"
|
|
* 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_List_Create(
|
|
PKIX_List **pList,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_SetImmutable
|
|
* DESCRIPTION:
|
|
*
|
|
* Sets the List pointed to by "list" to be immutable. If a caller tries to
|
|
* change a List after it has been marked immutable (i.e. by calling
|
|
* PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
|
|
* PKIX_List_DeleteItem), an Error is returned.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to be marked immutable. Must be non-NULL.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "list"
|
|
* (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_List_SetImmutable(
|
|
PKIX_List *list,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_IsImmutable
|
|
* DESCRIPTION:
|
|
*
|
|
* Checks whether the List pointed to by "list" is immutable and stores
|
|
* the Boolean result at "pImmutable". If a caller tries to change a List
|
|
* after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
|
|
* PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
|
|
* Error is returned.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List whose immutability is to be determined.
|
|
* Must be non-NULL.
|
|
* "pImmutable"
|
|
* Address where PKIX_Boolean 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 Fatal Error if the function fails in an unrecoverable way.
|
|
*/
|
|
PKIX_Error *
|
|
PKIX_List_IsImmutable(
|
|
PKIX_List *list,
|
|
PKIX_Boolean *pImmutable,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_GetLength
|
|
* DESCRIPTION:
|
|
*
|
|
* Retrieves the length of the List pointed to by "list" and stores it at
|
|
* "pLength".
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List 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:
|
|
* Conditionally 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_List_GetLength(
|
|
PKIX_List *list,
|
|
PKIX_UInt32 *pLength,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_IsEmpty
|
|
* DESCRIPTION:
|
|
*
|
|
* Checks whether the List pointed to by "list" is empty and stores
|
|
* the Boolean result at "pEmpty".
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List whose emptiness is to be determined. Must be non-NULL.
|
|
* "pEmpty"
|
|
* Address where PKIX_Boolean 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 Fatal Error if the function fails in an unrecoverable way.
|
|
*/
|
|
PKIX_Error *
|
|
PKIX_List_IsEmpty(
|
|
PKIX_List *list,
|
|
PKIX_Boolean *pEmpty,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_AppendItem
|
|
* DESCRIPTION:
|
|
*
|
|
* Appends the Object pointed to by "item" after the last non-NULL item in
|
|
* List pointed to by "list", if any. Note that a List may validly contain
|
|
* NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
|
|
* in ("a", NULL, "b", "c").
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to append to. Must be non-NULL.
|
|
* "item"
|
|
* Address of new item to append.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "list"
|
|
* (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_List_AppendItem(
|
|
PKIX_List *list,
|
|
PKIX_PL_Object *item,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_InsertItem
|
|
* DESCRIPTION:
|
|
*
|
|
* Inserts the Object pointed to by "item" into the List pointed to by "list"
|
|
* at the given "index". The index counts from zero and must be less than the
|
|
* List's length. Existing list entries at or after this index will be moved
|
|
* to the next highest index.
|
|
*
|
|
* XXX why not allow equal to length which would be equivalent to AppendItem?
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to insert into. Must be non-NULL.
|
|
* "index"
|
|
* Position to insert into. Must be less than List's length.
|
|
* "item"
|
|
* Address of new item to append.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "list"
|
|
* (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_List_InsertItem(
|
|
PKIX_List *list,
|
|
PKIX_UInt32 index,
|
|
PKIX_PL_Object *item,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_GetItem
|
|
* DESCRIPTION:
|
|
*
|
|
* Copies the "list"'s item at "index" into "pItem". The index counts from
|
|
* zero and must be less than the list's length. Increments the reference
|
|
* count on the returned object, if non-NULL.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to get item from. Must be non-NULL.
|
|
* "index"
|
|
* Index of list to get item from. Must be less than List's length.
|
|
* "pItem"
|
|
* 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 Fatal Error if the function fails in an unrecoverable way.
|
|
*/
|
|
PKIX_Error *
|
|
PKIX_List_GetItem(
|
|
PKIX_List *list,
|
|
PKIX_UInt32 index,
|
|
PKIX_PL_Object **pItem,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_SetItem
|
|
* DESCRIPTION:
|
|
*
|
|
* Sets the item at "index" of the List pointed to by "list" with the Object
|
|
* pointed to by "item". The index counts from zero and must be less than the
|
|
* List's length. The previous entry at this index will have its reference
|
|
* count decremented and the new entry will have its reference count
|
|
* incremented.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to modify. Must be non-NULL.
|
|
* "index"
|
|
* Position in List to set. Must be less than List's length.
|
|
* "item"
|
|
* Address of Object to set at "index".
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "list"
|
|
* (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_List_SetItem(
|
|
PKIX_List *list,
|
|
PKIX_UInt32 index,
|
|
PKIX_PL_Object *item,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_DeleteItem
|
|
*
|
|
* Deletes the item at "index" from the List pointed to by "list". The index
|
|
* counts from zero and must be less than the List's length. Note that this
|
|
* function does not destroy the List. It simply decrements the reference
|
|
* count of the item at "index" in the List, deletes that item from the list
|
|
* and moves all subsequent entries to a lower index in the list. If there is
|
|
* only a single element in the List and that element is deleted, then the
|
|
* List will be empty.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List to delete from. Must be non-NULL.
|
|
* "index"
|
|
* Position in List to delete. Must be less than List's length.
|
|
* "plContext"
|
|
* Platform-specific context pointer.
|
|
* THREAD SAFETY:
|
|
* Not Thread Safe - assumes exclusive access to "list"
|
|
* (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_List_DeleteItem(
|
|
PKIX_List *list,
|
|
PKIX_UInt32 index,
|
|
void *plContext);
|
|
|
|
/*
|
|
* FUNCTION: PKIX_List_ReverseList
|
|
* DESCRIPTION:
|
|
*
|
|
* Creates a new List whose elements are in the reverse order as the elements
|
|
* of the Object pointed to by "list" and stores the copy at "pReversedList".
|
|
* If "list" is empty, the new reversed List will be a copy of "list".
|
|
* Changes to the new object will not affect the original and vice versa.
|
|
*
|
|
* PARAMETERS:
|
|
* "list"
|
|
* Address of List whose elements are to be reversed. Must be non-NULL.
|
|
* "pReversedList"
|
|
* 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 Fatal Error if the function fails in an unrecoverable way.
|
|
*/
|
|
PKIX_Error *
|
|
PKIX_List_ReverseList(
|
|
PKIX_List *list,
|
|
PKIX_List **pReversedList,
|
|
void *plContext);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _PKIX_UTIL_H */
|