1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_util.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,941 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * These functions provide support for a number of other functions
1.9 + * by creating and manipulating data structures used by those functions.
1.10 + *
1.11 + */
1.12 +
1.13 +#ifndef _PKIX_UTIL_H
1.14 +#define _PKIX_UTIL_H
1.15 +
1.16 +#include "pkixt.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +/* General
1.23 + *
1.24 + * Please refer to the libpkix Programmer's Guide for detailed information
1.25 + * about how to use the libpkix library. Certain key warnings and notices from
1.26 + * that document are repeated here for emphasis.
1.27 + *
1.28 + * All identifiers in this file (and all public identifiers defined in
1.29 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.30 + * within the library begin with "pkix_".
1.31 + *
1.32 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.33 + *
1.34 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.35 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.36 + * shared object. Therefore, the caller should treat this shared object as
1.37 + * read-only and should not modify this shared object. When done using the
1.38 + * shared object, the caller should release the reference to the object by
1.39 + * using the PKIX_PL_Object_DecRef function.
1.40 + *
1.41 + * While a function is executing, if its arguments (or anything referred to by
1.42 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.43 + * is undefined.
1.44 + *
1.45 + */
1.46 +
1.47 +/* PKIX_Logger
1.48 + *
1.49 + * PKIX_Loggers provide a standard way for the caller to insert custom logging
1.50 + * facilities. These are used by libpkix to log errors, debug information,
1.51 + * status, etc. The LogCallback allows custom logging to take place.
1.52 + * Additionally, a Logger can be initialized with a loggerContext, which is
1.53 + * where the caller can specify configuration data such as the name of a
1.54 + * logfile or database. Note that this loggerContext must be a PKIX_PL_Object,
1.55 + * allowing it to be reference-counted and allowing it to provide the standard
1.56 + * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
1.57 + *
1.58 + * Once the caller has created the Logger object(s) (and set the loggerContext
1.59 + * (if any) and the Log callback), the caller then registers these Loggers
1.60 + * with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log
1.61 + * entries will then be logged using the specified Loggers. If multiple
1.62 + * Loggers are specified, every log entry will be logged with each of them.
1.63 + *
1.64 + * XXX Maybe give some guidance somewhere on how much detail each logging
1.65 + * level should have and where component boundaries should be. Maybe in
1.66 + * Implementor's Guide or Programmer's Guide.
1.67 + */
1.68 +
1.69 +#define PKIX_LOGGER_LEVEL_TRACE 5
1.70 +#define PKIX_LOGGER_LEVEL_DEBUG 4
1.71 +#define PKIX_LOGGER_LEVEL_WARNING 3
1.72 +#define PKIX_LOGGER_LEVEL_ERROR 2
1.73 +#define PKIX_LOGGER_LEVEL_FATALERROR 1
1.74 +
1.75 +#define PKIX_LOGGER_LEVEL_MAX 5
1.76 +
1.77 +/*
1.78 + * FUNCTION: PKIX_Logger_LogCallback
1.79 + * DESCRIPTION:
1.80 + *
1.81 + * This callback function logs a log entry containing the String pointed to
1.82 + * by "message", the integer value of logLevel, and the String pointed to by
1.83 + * "logComponent". A log entry can be associated with a particular log
1.84 + * level (i.e. level 3) and a particular log component (i.e. "CertStore").
1.85 + * For example, someone reading the log may only be interested in very general
1.86 + * log entries so they look only for log level 1. Similarly, they may only be
1.87 + * interested in log entries pertaining to the CertStore component so they
1.88 + * look only for that log component. This function can be used before calling
1.89 + * PKIX_Initialize.
1.90 + *
1.91 + * PARAMETERS:
1.92 + * "logger"
1.93 + * Address of logger whose LogCallback is to be used. Must be non-NULL.
1.94 + * "message"
1.95 + * Address of String that is to be logged used "logger". Must be non-NULL.
1.96 + * "logLevel"
1.97 + * Integer value representing the log level for this entry. The higher the
1.98 + * level, the more detail. Must be non-NULL.
1.99 + * "logComponent"
1.100 + * PKIXERRORNUM value (defined in pkixt.h) designating the log component
1.101 + * for this entry.
1.102 + * "plContext"
1.103 + * Platform-specific context pointer.
1.104 + * THREAD SAFETY:
1.105 + * Thread Safe
1.106 + *
1.107 + * Multiple threads must be able to safely call this function without
1.108 + * worrying about conflicts, even if they're operating on the same objects.
1.109 + * RETURNS:
1.110 + * Returns NULL if the function succeeds.
1.111 + * Returns a Logger Error if the function fails in a non-fatal way.
1.112 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.113 + */
1.114 +typedef PKIX_Error *
1.115 +(*PKIX_Logger_LogCallback)(
1.116 + PKIX_Logger *logger,
1.117 + PKIX_PL_String *message,
1.118 + PKIX_UInt32 logLevel,
1.119 + PKIX_ERRORCLASS logComponent,
1.120 + void *plContext);
1.121 +
1.122 +/*
1.123 + * FUNCTION: PKIX_Logger_Create
1.124 + * DESCRIPTION:
1.125 + *
1.126 + * Creates a new Logger using the Object pointed to by "loggerContext"
1.127 + * (if any) and stores it at "pLogger". The new Logger uses the LogCallback
1.128 + * pointed to by "callback". The Logger's maximum logging level is initially
1.129 + * set to a very high level and its logging component is set to NULL (all
1.130 + * components).
1.131 + *
1.132 + * PARAMETERS:
1.133 + * "callback"
1.134 + * The LogCallback function to be used. Must be non-NULL.
1.135 + * "loggerContext"
1.136 + * Address of Object representing the Logger's context (if any).
1.137 + * "pLogger"
1.138 + * Address where object pointer will be stored. Must be non-NULL.
1.139 + * "plContext"
1.140 + * Platform-specific context pointer.
1.141 + * THREAD SAFETY:
1.142 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.143 + * RETURNS:
1.144 + * Returns NULL if the function succeeds.
1.145 + * Returns a Logger Error if the function fails in a non-fatal way.
1.146 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.147 + */
1.148 +PKIX_Error *
1.149 +PKIX_Logger_Create(
1.150 + PKIX_Logger_LogCallback callback,
1.151 + PKIX_PL_Object *loggerContext,
1.152 + PKIX_Logger **pLogger,
1.153 + void *plContext);
1.154 +
1.155 +/*
1.156 + * FUNCTION: PKIX_Logger_GetLogCallback
1.157 + * DESCRIPTION:
1.158 + *
1.159 + * Retrieves a pointer to "logger's" Log callback function and puts it in
1.160 + * "pCallback".
1.161 + *
1.162 + * PARAMETERS:
1.163 + * "logger"
1.164 + * Address of Logger whose Log callback is desired. Must be non-NULL.
1.165 + * "pCallback"
1.166 + * Address where Log callback function pointer will be stored.
1.167 + * Must be non-NULL.
1.168 + * "plContext"
1.169 + * Platform-specific context pointer.
1.170 + * THREAD SAFETY:
1.171 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.172 + * RETURNS:
1.173 + * Returns NULL if the function succeeds.
1.174 + * Returns a Logger Error if the function fails in a non-fatal way.
1.175 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.176 + */
1.177 +PKIX_Error *
1.178 +PKIX_Logger_GetLogCallback(
1.179 + PKIX_Logger *logger,
1.180 + PKIX_Logger_LogCallback *pCallback,
1.181 + void *plContext);
1.182 +
1.183 +/*
1.184 + * FUNCTION: PKIX_Logger_GetLoggerContext
1.185 + * DESCRIPTION:
1.186 + *
1.187 + * Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
1.188 + * of the Logger pointed to by "logger" and stores it at "pLoggerContext".
1.189 + *
1.190 + * PARAMETERS:
1.191 + * "logger"
1.192 + * Address of Logger whose context is to be stored. Must be non-NULL.
1.193 + * "pLoggerContext"
1.194 + * Address where object pointer will be stored. Must be non-NULL.
1.195 + * "plContext"
1.196 + * Platform-specific context pointer.
1.197 + * THREAD SAFETY:
1.198 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.199 + * RETURNS:
1.200 + * Returns NULL if the function succeeds.
1.201 + * Returns a Logger Error if the function fails in a non-fatal way.
1.202 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.203 + */
1.204 +PKIX_Error *
1.205 +PKIX_Logger_GetLoggerContext(
1.206 + PKIX_Logger *logger,
1.207 + PKIX_PL_Object **pLoggerContext,
1.208 + void *plContext);
1.209 +
1.210 +/*
1.211 + * FUNCTION: PKIX_Logger_GetMaxLoggingLevel
1.212 + * DESCRIPTION:
1.213 + *
1.214 + * Retrieves a pointer to a PKIX_UInt32 representing the maximum logging
1.215 + * level of the Logger pointed to by "logger" and stores it at "pLevel". Only
1.216 + * log entries whose log level is less than or equal to this maximum logging
1.217 + * level will be logged.
1.218 + *
1.219 + * PARAMETERS:
1.220 + * "logger"
1.221 + * Address of Logger whose maximum logging level is to be stored.
1.222 + * Must be non-NULL.
1.223 + * "pLevel"
1.224 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.225 + * "plContext"
1.226 + * Platform-specific context pointer.
1.227 + * THREAD SAFETY:
1.228 + * Conditionally Thread Safe
1.229 + * (see Thread Safety Definitions in Programmer's Guide)
1.230 + * RETURNS:
1.231 + * Returns NULL if the function succeeds.
1.232 + * Returns a Logger Error if the function fails in a non-fatal way.
1.233 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.234 + */
1.235 +PKIX_Error *
1.236 +PKIX_Logger_GetMaxLoggingLevel(
1.237 + PKIX_Logger *logger,
1.238 + PKIX_UInt32 *pLevel,
1.239 + void *plContext);
1.240 +
1.241 +/*
1.242 + * FUNCTION: PKIX_Logger_SetMaxLoggingLevel
1.243 + * DESCRIPTION:
1.244 + *
1.245 + * Sets the maximum logging level of the Logger pointed to by "logger" with
1.246 + * the integer value of "level".
1.247 + *
1.248 + * PARAMETERS:
1.249 + * "logger"
1.250 + * Address of Logger whose maximum logging level is to be set.
1.251 + * Must be non-NULL.
1.252 + * "level"
1.253 + * Maximum logging level to be set
1.254 + * "plContext"
1.255 + * Platform-specific context pointer.
1.256 + * THREAD SAFETY:
1.257 + * Not Thread Safe - assumes exclusive access to "logger"
1.258 + * (see Thread Safety Definitions in Programmer's Guide)
1.259 + * RETURNS:
1.260 + * Returns NULL if the function succeeds.
1.261 + * Returns a Logger Error if the function fails in a non-fatal way.
1.262 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.263 + */
1.264 +PKIX_Error *
1.265 +PKIX_Logger_SetMaxLoggingLevel(
1.266 + PKIX_Logger *logger,
1.267 + PKIX_UInt32 level,
1.268 + void *plContext);
1.269 +
1.270 +/*
1.271 + * FUNCTION: PKIX_Logger_GetLoggingComponent
1.272 + * DESCRIPTION:
1.273 + *
1.274 + * Retrieves a pointer to a String representing the logging component of the
1.275 + * Logger pointed to by "logger" and stores it at "pComponent". Only log
1.276 + * entries whose log component matches the specified logging component will
1.277 + * be logged.
1.278 + *
1.279 + * PARAMETERS:
1.280 + * "logger"
1.281 + * Address of Logger whose logging component is to be stored.
1.282 + * Must be non-NULL.
1.283 + * "pComponent"
1.284 + * Address where PKIXERRORNUM will be stored. Must be non-NULL.
1.285 + * "plContext"
1.286 + * Platform-specific context pointer.
1.287 + * THREAD SAFETY:
1.288 + * Conditionally Thread Safe
1.289 + * (see Thread Safety Definitions in Programmer's Guide)
1.290 + * RETURNS:
1.291 + * Returns NULL if the function succeeds.
1.292 + * Returns a Logger Error if the function fails in a non-fatal way.
1.293 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.294 + */
1.295 +PKIX_Error *
1.296 +PKIX_Logger_GetLoggingComponent(
1.297 + PKIX_Logger *logger,
1.298 + PKIX_ERRORCLASS *pComponent,
1.299 + void *plContext);
1.300 +
1.301 +/*
1.302 + * FUNCTION: PKIX_Logger_SetLoggingComponent
1.303 + * DESCRIPTION:
1.304 + *
1.305 + * Sets the logging component of the Logger pointed to by "logger" with the
1.306 + * PKIXERRORNUM pointed to by "component". To match a small set of components,
1.307 + * create a Logger for each.
1.308 + *
1.309 + * PARAMETERS:
1.310 + * "logger"
1.311 + * Address of Logger whose logging component is to be set.
1.312 + * Must be non-NULL.
1.313 + * "component"
1.314 + * PKIXERRORNUM value representing logging component to be set.
1.315 + * "plContext"
1.316 + * Platform-specific context pointer.
1.317 + * THREAD SAFETY:
1.318 + * Not Thread Safe - assumes exclusive access to "logger"
1.319 + * (see Thread Safety Definitions in Programmer's Guide)
1.320 + * RETURNS:
1.321 + * Returns NULL if the function succeeds.
1.322 + * Returns a Logger Error if the function fails in a non-fatal way.
1.323 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.324 + */
1.325 +PKIX_Error *
1.326 +PKIX_Logger_SetLoggingComponent(
1.327 + PKIX_Logger *logger,
1.328 + PKIX_ERRORCLASS component,
1.329 + void *plContext);
1.330 +
1.331 +/*
1.332 + * FUNCTION: PKIX_GetLoggers
1.333 + * DESCRIPTION:
1.334 + *
1.335 + * Retrieves a pointer to the List of Loggers (if any) being used for logging
1.336 + * by libpkix and stores it at "pLoggers". If no loggers are being used, this
1.337 + * function stores an empty List at "pLoggers".
1.338 + *
1.339 + * Note that the List returned by this function is immutable.
1.340 + *
1.341 + * PARAMETERS:
1.342 + * "pLoggers"
1.343 + * Address where object pointer will be stored. Must be non-NULL.
1.344 + * "plContext"
1.345 + * Platform-specific context pointer.
1.346 + * THREAD SAFETY:
1.347 + * Conditionally Thread Safe
1.348 + * (see Thread Safety Definitions in Programmer's Guide)
1.349 + * RETURNS:
1.350 + * Returns NULL if the function succeeds.
1.351 + * Returns a Logger Error if the function fails in a non-fatal way.
1.352 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.353 + */
1.354 +PKIX_Error *
1.355 +PKIX_GetLoggers(
1.356 + PKIX_List **pLoggers, /* list of PKIX_Logger */
1.357 + void *plContext);
1.358 +
1.359 +/*
1.360 + * FUNCTION: PKIX_SetLoggers
1.361 + * DESCRIPTION:
1.362 + *
1.363 + * Sets the Loggers to be used by libpkix to the List of Loggers pointed to
1.364 + * by "loggers". If "loggers" is NULL, no Loggers will be used.
1.365 + *
1.366 + * PARAMETERS:
1.367 + * "loggers"
1.368 + * Address of List of Loggers to be set. NULL for no Loggers.
1.369 + * "plContext"
1.370 + * Platform-specific context pointer.
1.371 + * THREAD SAFETY:
1.372 + * Not Thread Safe
1.373 + * (see Thread Safety Definitions in Programmer's Guide)
1.374 + * RETURNS:
1.375 + * Returns NULL if the function succeeds.
1.376 + * Returns a Logger Error if the function fails in a non-fatal way.
1.377 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.378 + */
1.379 +PKIX_Error *
1.380 +PKIX_SetLoggers(
1.381 + PKIX_List *loggers, /* list of PKIX_Logger */
1.382 + void *plContext);
1.383 +
1.384 +/*
1.385 + * FUNCTION: PKIX_AddLogger
1.386 + * DESCRIPTION:
1.387 + *
1.388 + * Adds the Logger pointed to by "logger" to the List of Loggers used by
1.389 + * libpkix.
1.390 + *
1.391 + * PARAMETERS:
1.392 + * "logger"
1.393 + * Address of Logger to be added. Must be non-NULL.
1.394 + * "plContext"
1.395 + * Platform-specific context pointer.
1.396 + * THREAD SAFETY:
1.397 + * Not Thread Safe
1.398 + * (see Thread Safety Definitions in Programmer's Guide)
1.399 + * RETURNS:
1.400 + * Returns NULL if the function succeeds.
1.401 + * Returns a Logger Error if the function fails in a non-fatal way.
1.402 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.403 + */
1.404 +PKIX_Error *
1.405 +PKIX_AddLogger(
1.406 + PKIX_Logger *logger,
1.407 + void *plContext);
1.408 +
1.409 +/* Functions pertaining to the PKIX_Error type */
1.410 +
1.411 +/* Error
1.412 + *
1.413 + * An Error object is returned by a function upon encountering some error
1.414 + * condition. Each Error is associated with an errorCode specified in pkixt.h.
1.415 + * The remaining components of an Error are optional. An Error's description
1.416 + * specifies a text message describing the Error. An Error's supplementary info
1.417 + * specifies additional information that might be useful. Finally, an Error's
1.418 + * cause specifies the underlying Error (if any) that resulted in this Error
1.419 + * being returned, thereby allowing Errors to be chained so that an entire
1.420 + * "error stack trace" can be represented. Once created, an Error is immutable.
1.421 + *
1.422 + * Note that the Error's supplementary info must be an Object (although any
1.423 + * object type), allowing it to be reference-counted and allowing it to
1.424 + * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
1.425 + * Duplicate).
1.426 + *
1.427 + * Errors are classified as either being fatal or non-fatal. If a function
1.428 + * fails in an unrecoverable way, it returns an Error whose errorCode is
1.429 + * PKIX_FATAL_ERROR. If such an error is encountered, the caller should
1.430 + * not attempt to recover since something seriously wrong has happened
1.431 + * (e.g. corrupted memory, memory finished, etc.). All other errorCodes
1.432 + * are considered non-fatal errors and can be handled by the caller as they
1.433 + * see fit.
1.434 + */
1.435 +
1.436 +/*
1.437 + * FUNCTION: PKIX_Error_Create
1.438 + * DESCRIPTION:
1.439 + *
1.440 + * Creates a new Error using the value of "errorCode", the Error pointed to by
1.441 + * "cause" (if any), the Object pointed to by "info" (if any), and the String
1.442 + * pointed to by "desc" and stores it at "pError". If any error occurs during
1.443 + * error allocation, it will be returned without chaining, since new errors
1.444 + * cannot be created. Once created, an Error is immutable.
1.445 + *
1.446 + * PARAMETERS:
1.447 + * "errorCode"
1.448 + * Value of error code.
1.449 + * "cause"
1.450 + * Address of Error representing error's cause.
1.451 + * NULL if none or unspecified.
1.452 + * "info"
1.453 + * Address of Object representing error's supplementary information.
1.454 + * NULL if none.
1.455 + * "desc"
1.456 + * Address of String representing error's description. NULL if none.
1.457 + * "pError"
1.458 + * Address where object pointer will be stored. Must be non-NULL.
1.459 + * "plContext"
1.460 + * Platform-specific context pointer.
1.461 + * THREAD SAFETY:
1.462 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.463 + * RETURNS:
1.464 + * Returns NULL if the function succeeds.
1.465 + * Returns an Error Error if the function fails in a non-fatal way.
1.466 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.467 + */
1.468 +PKIX_Error *
1.469 +PKIX_Error_Create(
1.470 + PKIX_ERRORCLASS errClass,
1.471 + PKIX_Error *cause,
1.472 + PKIX_PL_Object *info,
1.473 + PKIX_ERRORCODE errCode,
1.474 + PKIX_Error **pError,
1.475 + void *plContext);
1.476 +
1.477 +/*
1.478 + * FUNCTION: PKIX_Error_GetErrorClass
1.479 + * DESCRIPTION:
1.480 + *
1.481 + * Retrieves the error class of the Error pointed to by "error" and
1.482 + * stores it at "pClass". Supported error codes are defined in pkixt.h.
1.483 + *
1.484 + * PARAMETERS:
1.485 + * "error"
1.486 + * Address of Error whose error code is desired. Must be non-NULL.
1.487 + * "pClass"
1.488 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.489 + * "plContext"
1.490 + * Platform-specific context pointer.
1.491 + * THREAD SAFETY:
1.492 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.493 + * RETURNS:
1.494 + * Returns NULL if the function succeeds.
1.495 + * Returns an Error Error if the function fails in a non-fatal way.
1.496 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.497 + */
1.498 +PKIX_Error *
1.499 +PKIX_Error_GetErrorClass(
1.500 + PKIX_Error *error,
1.501 + PKIX_ERRORCLASS *pClass,
1.502 + void *plContext);
1.503 +
1.504 +/*
1.505 + * FUNCTION: PKIX_Error_GetErrorCode
1.506 + * DESCRIPTION:
1.507 + *
1.508 + * Retrieves the error code of the Error pointed to by "error" and
1.509 + * stores it at "pCode". Supported error codes are defined in pkixt.h.
1.510 + *
1.511 + * PARAMETERS:
1.512 + * "error"
1.513 + * Address of Error whose error code is desired. Must be non-NULL.
1.514 + * "pCode"
1.515 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.516 + * "plContext"
1.517 + * Platform-specific context pointer.
1.518 + * THREAD SAFETY:
1.519 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.520 + * RETURNS:
1.521 + * Returns NULL if the function succeeds.
1.522 + * Returns an Error Error if the function fails in a non-fatal way.
1.523 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.524 + */
1.525 +PKIX_Error *
1.526 +PKIX_Error_GetErrorCode(
1.527 + PKIX_Error *error,
1.528 + PKIX_ERRORCODE *pCode,
1.529 + void *plContext);
1.530 +
1.531 +/*
1.532 + * FUNCTION: PKIX_Error_GetCause
1.533 + * DESCRIPTION:
1.534 + *
1.535 + * Retrieves the cause of the Error pointed to by "error" and stores it at
1.536 + * "pCause". If no cause was specified, NULL will be stored at "pCause".
1.537 + *
1.538 + * PARAMETERS:
1.539 + * "error"
1.540 + * Address of Error whose cause is desired. Must be non-NULL.
1.541 + * "pCause"
1.542 + * Address where object pointer will be stored. Must be non-NULL.
1.543 + * "plContext"
1.544 + * Platform-specific context pointer.
1.545 + * THREAD SAFETY:
1.546 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.547 + * RETURNS:
1.548 + * Returns NULL if the function succeeds.
1.549 + * Returns an Error Error if the function fails in a non-fatal way.
1.550 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.551 + */
1.552 +PKIX_Error *
1.553 +PKIX_Error_GetCause(
1.554 + PKIX_Error *error,
1.555 + PKIX_Error **pCause,
1.556 + void *plContext);
1.557 +
1.558 +/*
1.559 + * FUNCTION: PKIX_Error_GetSupplementaryInfo
1.560 + * DESCRIPTION:
1.561 + *
1.562 + * Retrieves the supplementary info of the Error pointed to by "error" and
1.563 + * stores it at "pInfo".
1.564 + *
1.565 + * PARAMETERS:
1.566 + * "error"
1.567 + * Address of Error whose info is desired. Must be non-NULL.
1.568 + * "pInfo"
1.569 + * Address where info pointer will be stored. Must be non-NULL.
1.570 + * "plContext"
1.571 + * Platform-specific context pointer.
1.572 + * THREAD SAFETY:
1.573 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.574 + * RETURNS:
1.575 + * Returns NULL if the function succeeds.
1.576 + * Returns an Error Error if the function fails in a non-fatal way.
1.577 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.578 + */
1.579 +PKIX_Error *
1.580 +PKIX_Error_GetSupplementaryInfo(
1.581 + PKIX_Error *error,
1.582 + PKIX_PL_Object **pInfo,
1.583 + void *plContext);
1.584 +
1.585 +/*
1.586 + * FUNCTION: PKIX_Error_GetDescription
1.587 + * DESCRIPTION:
1.588 + *
1.589 + * Retrieves the description of the Error pointed to by "error" and stores it
1.590 + * at "pDesc". If no description was specified, NULL will be stored at
1.591 + * "pDesc".
1.592 + *
1.593 + * PARAMETERS:
1.594 + * "error"
1.595 + * Address of Error whose description is desired. Must be non-NULL.
1.596 + * "pDesc"
1.597 + * Address where object pointer will be stored. Must be non-NULL.
1.598 + * "plContext"
1.599 + * Platform-specific context pointer.
1.600 + * THREAD SAFETY:
1.601 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.602 + * RETURNS:
1.603 + * Returns NULL if the function succeeds.
1.604 + * Returns an Error Error if the function fails in a non-fatal way.
1.605 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.606 + */
1.607 +PKIX_Error *
1.608 +PKIX_Error_GetDescription(
1.609 + PKIX_Error *error,
1.610 + PKIX_PL_String **pDesc,
1.611 + void *plContext);
1.612 +
1.613 +/* PKIX_List
1.614 + *
1.615 + * Represents a collection of items. NULL is considered a valid item.
1.616 + */
1.617 +
1.618 +/*
1.619 + * FUNCTION: PKIX_List_Create
1.620 + * DESCRIPTION:
1.621 + *
1.622 + * Creates a new List and stores it at "pList". The List is initially empty
1.623 + * and holds no items. To initially add items to the List, use
1.624 + * PKIX_List_AppendItem
1.625 + *
1.626 + * PARAMETERS:
1.627 + * "pList"
1.628 + * Address where object pointer will be stored. Must be non-NULL.
1.629 + * "plContext"
1.630 + * Platform-specific context pointer.
1.631 + * THREAD SAFETY:
1.632 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.633 + * RETURNS:
1.634 + * Returns NULL if the function succeeds.
1.635 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.636 + */
1.637 +PKIX_Error *
1.638 +PKIX_List_Create(
1.639 + PKIX_List **pList,
1.640 + void *plContext);
1.641 +
1.642 +/*
1.643 + * FUNCTION: PKIX_List_SetImmutable
1.644 + * DESCRIPTION:
1.645 + *
1.646 + * Sets the List pointed to by "list" to be immutable. If a caller tries to
1.647 + * change a List after it has been marked immutable (i.e. by calling
1.648 + * PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
1.649 + * PKIX_List_DeleteItem), an Error is returned.
1.650 + *
1.651 + * PARAMETERS:
1.652 + * "list"
1.653 + * Address of List to be marked immutable. Must be non-NULL.
1.654 + * "plContext"
1.655 + * Platform-specific context pointer.
1.656 + * THREAD SAFETY:
1.657 + * Not Thread Safe - assumes exclusive access to "list"
1.658 + * (see Thread Safety Definitions in Programmer's Guide)
1.659 + * RETURNS:
1.660 + * Returns NULL if the function succeeds.
1.661 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.662 + */
1.663 +PKIX_Error *
1.664 +PKIX_List_SetImmutable(
1.665 + PKIX_List *list,
1.666 + void *plContext);
1.667 +
1.668 +/*
1.669 + * FUNCTION: PKIX_List_IsImmutable
1.670 + * DESCRIPTION:
1.671 + *
1.672 + * Checks whether the List pointed to by "list" is immutable and stores
1.673 + * the Boolean result at "pImmutable". If a caller tries to change a List
1.674 + * after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
1.675 + * PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
1.676 + * Error is returned.
1.677 + *
1.678 + * PARAMETERS:
1.679 + * "list"
1.680 + * Address of List whose immutability is to be determined.
1.681 + * Must be non-NULL.
1.682 + * "pImmutable"
1.683 + * Address where PKIX_Boolean will be stored. Must be non-NULL.
1.684 + * "plContext"
1.685 + * Platform-specific context pointer.
1.686 + * THREAD SAFETY:
1.687 + * Conditionally Thread Safe
1.688 + * (see Thread Safety Definitions in Programmer's Guide)
1.689 + * RETURNS:
1.690 + * Returns NULL if the function succeeds.
1.691 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.692 + */
1.693 +PKIX_Error *
1.694 +PKIX_List_IsImmutable(
1.695 + PKIX_List *list,
1.696 + PKIX_Boolean *pImmutable,
1.697 + void *plContext);
1.698 +
1.699 +/*
1.700 + * FUNCTION: PKIX_List_GetLength
1.701 + * DESCRIPTION:
1.702 + *
1.703 + * Retrieves the length of the List pointed to by "list" and stores it at
1.704 + * "pLength".
1.705 + *
1.706 + * PARAMETERS:
1.707 + * "list"
1.708 + * Address of List whose length is desired. Must be non-NULL.
1.709 + * "pLength"
1.710 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.711 + * "plContext"
1.712 + * Platform-specific context pointer.
1.713 + * THREAD SAFETY:
1.714 + * Conditionally Thread Safe
1.715 + * (see Thread Safety Definitions in Programmer's Guide)
1.716 + * RETURNS:
1.717 + * Returns NULL if the function succeeds.
1.718 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.719 + */
1.720 +PKIX_Error *
1.721 +PKIX_List_GetLength(
1.722 + PKIX_List *list,
1.723 + PKIX_UInt32 *pLength,
1.724 + void *plContext);
1.725 +
1.726 +/*
1.727 + * FUNCTION: PKIX_List_IsEmpty
1.728 + * DESCRIPTION:
1.729 + *
1.730 + * Checks whether the List pointed to by "list" is empty and stores
1.731 + * the Boolean result at "pEmpty".
1.732 + *
1.733 + * PARAMETERS:
1.734 + * "list"
1.735 + * Address of List whose emptiness is to be determined. Must be non-NULL.
1.736 + * "pEmpty"
1.737 + * Address where PKIX_Boolean will be stored. Must be non-NULL.
1.738 + * "plContext"
1.739 + * Platform-specific context pointer.
1.740 + * THREAD SAFETY:
1.741 + * Conditionally Thread Safe
1.742 + * (see Thread Safety Definitions in Programmer's Guide)
1.743 + * RETURNS:
1.744 + * Returns NULL if the function succeeds.
1.745 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.746 + */
1.747 +PKIX_Error *
1.748 +PKIX_List_IsEmpty(
1.749 + PKIX_List *list,
1.750 + PKIX_Boolean *pEmpty,
1.751 + void *plContext);
1.752 +
1.753 +/*
1.754 + * FUNCTION: PKIX_List_AppendItem
1.755 + * DESCRIPTION:
1.756 + *
1.757 + * Appends the Object pointed to by "item" after the last non-NULL item in
1.758 + * List pointed to by "list", if any. Note that a List may validly contain
1.759 + * NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
1.760 + * in ("a", NULL, "b", "c").
1.761 + *
1.762 + * PARAMETERS:
1.763 + * "list"
1.764 + * Address of List to append to. Must be non-NULL.
1.765 + * "item"
1.766 + * Address of new item to append.
1.767 + * "plContext"
1.768 + * Platform-specific context pointer.
1.769 + * THREAD SAFETY:
1.770 + * Not Thread Safe - assumes exclusive access to "list"
1.771 + * (see Thread Safety Definitions in Programmer's Guide)
1.772 + * RETURNS:
1.773 + * Returns NULL if the function succeeds.
1.774 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.775 + */
1.776 +PKIX_Error *
1.777 +PKIX_List_AppendItem(
1.778 + PKIX_List *list,
1.779 + PKIX_PL_Object *item,
1.780 + void *plContext);
1.781 +
1.782 +/*
1.783 + * FUNCTION: PKIX_List_InsertItem
1.784 + * DESCRIPTION:
1.785 + *
1.786 + * Inserts the Object pointed to by "item" into the List pointed to by "list"
1.787 + * at the given "index". The index counts from zero and must be less than the
1.788 + * List's length. Existing list entries at or after this index will be moved
1.789 + * to the next highest index.
1.790 + *
1.791 + * XXX why not allow equal to length which would be equivalent to AppendItem?
1.792 + *
1.793 + * PARAMETERS:
1.794 + * "list"
1.795 + * Address of List to insert into. Must be non-NULL.
1.796 + * "index"
1.797 + * Position to insert into. Must be less than List's length.
1.798 + * "item"
1.799 + * Address of new item to append.
1.800 + * "plContext"
1.801 + * Platform-specific context pointer.
1.802 + * THREAD SAFETY:
1.803 + * Not Thread Safe - assumes exclusive access to "list"
1.804 + * (see Thread Safety Definitions in Programmer's Guide)
1.805 + * RETURNS:
1.806 + * Returns NULL if the function succeeds.
1.807 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.808 + */
1.809 +PKIX_Error *
1.810 +PKIX_List_InsertItem(
1.811 + PKIX_List *list,
1.812 + PKIX_UInt32 index,
1.813 + PKIX_PL_Object *item,
1.814 + void *plContext);
1.815 +
1.816 +/*
1.817 + * FUNCTION: PKIX_List_GetItem
1.818 + * DESCRIPTION:
1.819 + *
1.820 + * Copies the "list"'s item at "index" into "pItem". The index counts from
1.821 + * zero and must be less than the list's length. Increments the reference
1.822 + * count on the returned object, if non-NULL.
1.823 + *
1.824 + * PARAMETERS:
1.825 + * "list"
1.826 + * Address of List to get item from. Must be non-NULL.
1.827 + * "index"
1.828 + * Index of list to get item from. Must be less than List's length.
1.829 + * "pItem"
1.830 + * Address where object pointer will be stored. Must be non-NULL.
1.831 + * "plContext"
1.832 + * Platform-specific context pointer.
1.833 + * THREAD SAFETY:
1.834 + * Conditionally Thread Safe
1.835 + * (see Thread Safety Definitions in Programmer's Guide)
1.836 + * RETURNS:
1.837 + * Returns NULL if the function succeeds.
1.838 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.839 + */
1.840 +PKIX_Error *
1.841 +PKIX_List_GetItem(
1.842 + PKIX_List *list,
1.843 + PKIX_UInt32 index,
1.844 + PKIX_PL_Object **pItem,
1.845 + void *plContext);
1.846 +
1.847 +/*
1.848 + * FUNCTION: PKIX_List_SetItem
1.849 + * DESCRIPTION:
1.850 + *
1.851 + * Sets the item at "index" of the List pointed to by "list" with the Object
1.852 + * pointed to by "item". The index counts from zero and must be less than the
1.853 + * List's length. The previous entry at this index will have its reference
1.854 + * count decremented and the new entry will have its reference count
1.855 + * incremented.
1.856 + *
1.857 + * PARAMETERS:
1.858 + * "list"
1.859 + * Address of List to modify. Must be non-NULL.
1.860 + * "index"
1.861 + * Position in List to set. Must be less than List's length.
1.862 + * "item"
1.863 + * Address of Object to set at "index".
1.864 + * "plContext"
1.865 + * Platform-specific context pointer.
1.866 + * THREAD SAFETY:
1.867 + * Not Thread Safe - assumes exclusive access to "list"
1.868 + * (see Thread Safety Definitions in Programmer's Guide)
1.869 + * RETURNS:
1.870 + * Returns NULL if the function succeeds.
1.871 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.872 + */
1.873 +PKIX_Error *
1.874 +PKIX_List_SetItem(
1.875 + PKIX_List *list,
1.876 + PKIX_UInt32 index,
1.877 + PKIX_PL_Object *item,
1.878 + void *plContext);
1.879 +
1.880 +/*
1.881 + * FUNCTION: PKIX_List_DeleteItem
1.882 + *
1.883 + * Deletes the item at "index" from the List pointed to by "list". The index
1.884 + * counts from zero and must be less than the List's length. Note that this
1.885 + * function does not destroy the List. It simply decrements the reference
1.886 + * count of the item at "index" in the List, deletes that item from the list
1.887 + * and moves all subsequent entries to a lower index in the list. If there is
1.888 + * only a single element in the List and that element is deleted, then the
1.889 + * List will be empty.
1.890 + *
1.891 + * PARAMETERS:
1.892 + * "list"
1.893 + * Address of List to delete from. Must be non-NULL.
1.894 + * "index"
1.895 + * Position in List to delete. Must be less than List's length.
1.896 + * "plContext"
1.897 + * Platform-specific context pointer.
1.898 + * THREAD SAFETY:
1.899 + * Not Thread Safe - assumes exclusive access to "list"
1.900 + * (see Thread Safety Definitions in Programmer's Guide)
1.901 + * RETURNS:
1.902 + * Returns NULL if the function succeeds.
1.903 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.904 + */
1.905 +PKIX_Error *
1.906 +PKIX_List_DeleteItem(
1.907 + PKIX_List *list,
1.908 + PKIX_UInt32 index,
1.909 + void *plContext);
1.910 +
1.911 +/*
1.912 + * FUNCTION: PKIX_List_ReverseList
1.913 + * DESCRIPTION:
1.914 + *
1.915 + * Creates a new List whose elements are in the reverse order as the elements
1.916 + * of the Object pointed to by "list" and stores the copy at "pReversedList".
1.917 + * If "list" is empty, the new reversed List will be a copy of "list".
1.918 + * Changes to the new object will not affect the original and vice versa.
1.919 + *
1.920 + * PARAMETERS:
1.921 + * "list"
1.922 + * Address of List whose elements are to be reversed. Must be non-NULL.
1.923 + * "pReversedList"
1.924 + * Address where object pointer will be stored. Must be non-NULL.
1.925 + * "plContext"
1.926 + * Platform-specific context pointer.
1.927 + * THREAD SAFETY:
1.928 + * Conditionally Thread Safe
1.929 + * (see Thread Safety Definitions in Programmer's Guide)
1.930 + * RETURNS:
1.931 + * Returns NULL if the function succeeds.
1.932 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.933 + */
1.934 +PKIX_Error *
1.935 +PKIX_List_ReverseList(
1.936 + PKIX_List *list,
1.937 + PKIX_List **pReversedList,
1.938 + void *plContext);
1.939 +
1.940 +#ifdef __cplusplus
1.941 +}
1.942 +#endif
1.943 +
1.944 +#endif /* _PKIX_UTIL_H */
