[ tor-browser ].git.dasho

pkix_util.h (31440B)
      1 /* This Source Code Form is subject to the terms of the Mozilla Public
      2 * License, v. 2.0. If a copy of the MPL was not distributed with this
      3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
      4 /*
      5 * These functions provide support for a number of other functions
      6 * by creating and manipulating data structures used by those functions.
      7 *
      8 */
      9 
     10 #ifndef _PKIX_UTIL_H
     11 #define _PKIX_UTIL_H
     12 
     13 #include "pkixt.h"
     14 
     15 #ifdef __cplusplus
     16 extern "C" {
     17 #endif
     18 
     19 /* General
     20 *
     21 * Please refer to the libpkix Programmer's Guide for detailed information
     22 * about how to use the libpkix library. Certain key warnings and notices from
     23 * that document are repeated here for emphasis.
     24 *
     25 * All identifiers in this file (and all public identifiers defined in
     26 * libpkix) begin with "PKIX_". Private identifiers only intended for use
     27 * within the library begin with "pkix_".
     28 *
     29 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
     30 *
     31 * Unless otherwise noted, for all accessor (gettor) functions that return a
     32 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
     33 * shared object. Therefore, the caller should treat this shared object as
     34 * read-only and should not modify this shared object. When done using the
     35 * shared object, the caller should release the reference to the object by
     36 * using the PKIX_PL_Object_DecRef function.
     37 *
     38 * While a function is executing, if its arguments (or anything referred to by
     39 * its arguments) are modified, free'd, or destroyed, the function's behavior
     40 * is undefined.
     41 *
     42 */
     43 
     44 /* PKIX_Logger
     45 *
     46 * PKIX_Loggers provide a standard way for the caller to insert custom logging
     47 * facilities. These are used by libpkix to log errors, debug information,
     48 * status, etc. The LogCallback allows custom logging to take place.
     49 * Additionally, a Logger can be initialized with a loggerContext, which is
     50 * where the caller can specify configuration data such as the name of a
     51 * logfile or database. Note that this loggerContext must be a PKIX_PL_Object,
     52 * allowing it to be reference-counted and allowing it to provide the standard
     53 * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
     54 *
     55 * Once the caller has created the Logger object(s) (and set the loggerContext
     56 * (if any) and the Log callback), the caller then registers these Loggers
     57 * with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log
     58 * entries will then be logged using the specified Loggers. If multiple
     59 * Loggers are specified, every log entry will be logged with each of them.
     60 *
     61 * XXX Maybe give some guidance somewhere on how much detail each logging
     62 * level should have and where component boundaries should be. Maybe in
     63 * Implementor's Guide or Programmer's Guide.
     64 */
     65 
     66 #define PKIX_LOGGER_LEVEL_TRACE                5
     67 #define PKIX_LOGGER_LEVEL_DEBUG                4
     68 #define PKIX_LOGGER_LEVEL_WARNING              3
     69 #define PKIX_LOGGER_LEVEL_ERROR                2
     70 #define PKIX_LOGGER_LEVEL_FATALERROR           1
     71 
     72 #define PKIX_LOGGER_LEVEL_MAX                  5
     73 
     74 /*
     75 * FUNCTION: PKIX_Logger_LogCallback
     76 * DESCRIPTION:
     77 *
     78 *  This callback function logs a log entry containing the String pointed to
     79 *  by "message", the integer value of logLevel, and the String pointed to by
     80 *  "logComponent". A log entry can be associated with a particular log
     81 *  level (i.e. level 3) and a particular log component (i.e. "CertStore").
     82 *  For example, someone reading the log may only be interested in very general
     83 *  log entries so they look only for log level 1. Similarly, they may only be
     84 *  interested in log entries pertaining to the CertStore component so they
     85 *  look only for that log component. This function can be used before calling
     86 *  PKIX_Initialize.
     87 *
     88 * PARAMETERS:
     89 *  "logger"
     90 *      Address of logger whose LogCallback is to be used. Must be non-NULL.
     91 *  "message"
     92 *      Address of String that is to be logged used "logger". Must be non-NULL.
     93 *  "logLevel"
     94 *      Integer value representing the log level for this entry. The higher the
     95 *      level, the more detail. Must be non-NULL.
     96 *  "logComponent"
     97 *      PKIXERRORNUM value (defined in pkixt.h) designating the log component
     98 *      for this entry.
     99 *  "plContext"
    100 *      Platform-specific context pointer.
    101 * THREAD SAFETY:
    102 *  Thread Safe
    103 *
    104 *  Multiple threads must be able to safely call this function without
    105 *  worrying about conflicts, even if they're operating on the same objects.
    106 * RETURNS:
    107 *  Returns NULL if the function succeeds.
    108 *  Returns a Logger Error if the function fails in a non-fatal way.
    109 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    110 */
    111 typedef PKIX_Error *
    112 (*PKIX_Logger_LogCallback)(
    113        PKIX_Logger *logger,
    114        PKIX_PL_String *message,
    115        PKIX_UInt32 logLevel,
    116        PKIX_ERRORCLASS logComponent,
    117        void *plContext);
    118 
    119 /*
    120 * FUNCTION: PKIX_Logger_Create
    121 * DESCRIPTION:
    122 *
    123 *  Creates a new Logger using the Object pointed to by "loggerContext"
    124 *  (if any) and stores it at "pLogger". The new Logger uses the LogCallback
    125 *  pointed to by "callback". The Logger's maximum logging level is initially
    126 *  set to a very high level and its logging component is set to NULL (all
    127 *  components).
    128 *
    129 * PARAMETERS:
    130 *  "callback"
    131 *      The LogCallback function to be used. Must be non-NULL.
    132 *  "loggerContext"
    133 *      Address of Object representing the Logger's context (if any).
    134 *  "pLogger"
    135 *      Address where object pointer will be stored. Must be non-NULL.
    136 *  "plContext"
    137 *      Platform-specific context pointer.
    138 * THREAD SAFETY:
    139 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    140 * RETURNS:
    141 *  Returns NULL if the function succeeds.
    142 *  Returns a Logger Error if the function fails in a non-fatal way.
    143 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    144 */
    145 PKIX_Error *
    146 PKIX_Logger_Create(
    147        PKIX_Logger_LogCallback callback,
    148        PKIX_PL_Object *loggerContext,
    149        PKIX_Logger **pLogger,
    150        void *plContext);
    151 
    152 /*
    153 * FUNCTION: PKIX_Logger_GetLogCallback
    154 * DESCRIPTION:
    155 *
    156 *  Retrieves a pointer to "logger's" Log callback function and puts it in
    157 *  "pCallback".
    158 *
    159 * PARAMETERS:
    160 *  "logger"
    161 *      Address of Logger whose Log callback is desired. Must be non-NULL.
    162 *  "pCallback"
    163 *      Address where Log callback function pointer will be stored.
    164 *      Must be non-NULL.
    165 *  "plContext"
    166 *      Platform-specific context pointer.
    167 * THREAD SAFETY:
    168 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    169 * RETURNS:
    170 *  Returns NULL if the function succeeds.
    171 *  Returns a Logger Error if the function fails in a non-fatal way.
    172 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    173 */
    174 PKIX_Error *
    175 PKIX_Logger_GetLogCallback(
    176        PKIX_Logger *logger,
    177        PKIX_Logger_LogCallback *pCallback,
    178        void *plContext);
    179 
    180 /*
    181 * FUNCTION: PKIX_Logger_GetLoggerContext
    182 * DESCRIPTION:
    183 *
    184 *  Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
    185 *  of the Logger pointed to by "logger" and stores it at "pLoggerContext".
    186 *
    187 * PARAMETERS:
    188 *  "logger"
    189 *      Address of Logger whose context is to be stored. Must be non-NULL.
    190 *  "pLoggerContext"
    191 *      Address where object pointer will be stored. Must be non-NULL.
    192 *  "plContext"
    193 *      Platform-specific context pointer.
    194 * THREAD SAFETY:
    195 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    196 * RETURNS:
    197 *  Returns NULL if the function succeeds.
    198 *  Returns a Logger Error if the function fails in a non-fatal way.
    199 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    200 */
    201 PKIX_Error *
    202 PKIX_Logger_GetLoggerContext(
    203        PKIX_Logger *logger,
    204        PKIX_PL_Object **pLoggerContext,
    205        void *plContext);
    206 
    207 /*
    208 * FUNCTION: PKIX_Logger_GetMaxLoggingLevel
    209 * DESCRIPTION:
    210 *
    211 *  Retrieves a pointer to a PKIX_UInt32 representing the maximum logging
    212 *  level of the Logger pointed to by "logger" and stores it at "pLevel". Only
    213 *  log entries whose log level is less than or equal to this maximum logging
    214 *  level will be logged.
    215 *
    216 * PARAMETERS:
    217 *  "logger"
    218 *      Address of Logger whose maximum logging level is to be stored.
    219 *      Must be non-NULL.
    220 *  "pLevel"
    221 *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
    222 *  "plContext"
    223 *      Platform-specific context pointer.
    224 * THREAD SAFETY:
    225 *  Conditionally Thread Safe
    226 *      (see Thread Safety Definitions in Programmer's Guide)
    227 * RETURNS:
    228 *  Returns NULL if the function succeeds.
    229 *  Returns a Logger Error if the function fails in a non-fatal way.
    230 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    231 */
    232 PKIX_Error *
    233 PKIX_Logger_GetMaxLoggingLevel(
    234        PKIX_Logger *logger,
    235        PKIX_UInt32 *pLevel,
    236        void *plContext);
    237 
    238 /*
    239 * FUNCTION: PKIX_Logger_SetMaxLoggingLevel
    240 * DESCRIPTION:
    241 *
    242 *  Sets the maximum logging level of the Logger pointed to by "logger" with
    243 *  the integer value of "level".
    244 *
    245 * PARAMETERS:
    246 *  "logger"
    247 *      Address of Logger whose maximum logging level is to be set.
    248 *      Must be non-NULL.
    249 *  "level"
    250 *      Maximum logging level to be set
    251 *  "plContext"
    252 *      Platform-specific context pointer.
    253 * THREAD SAFETY:
    254 *  Not Thread Safe - assumes exclusive access to "logger"
    255 *  (see Thread Safety Definitions in Programmer's Guide)
    256 * RETURNS:
    257 *  Returns NULL if the function succeeds.
    258 *  Returns a Logger Error if the function fails in a non-fatal way.
    259 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    260 */
    261 PKIX_Error *
    262 PKIX_Logger_SetMaxLoggingLevel(
    263        PKIX_Logger *logger,
    264        PKIX_UInt32 level,
    265        void *plContext);
    266 
    267 /*
    268 * FUNCTION: PKIX_Logger_GetLoggingComponent
    269 * DESCRIPTION:
    270 *
    271 *  Retrieves a pointer to a String representing the logging component of the
    272 *  Logger pointed to by "logger" and stores it at "pComponent". Only log
    273 *  entries whose log component matches the specified logging component will
    274 *  be logged.
    275 *
    276 * PARAMETERS:
    277 *  "logger"
    278 *      Address of Logger whose logging component is to be stored.
    279 *      Must be non-NULL.
    280 *  "pComponent"
    281 *      Address where PKIXERRORNUM will be stored. Must be non-NULL.
    282 *  "plContext"
    283 *      Platform-specific context pointer.
    284 * THREAD SAFETY:
    285 *  Conditionally Thread Safe
    286 *      (see Thread Safety Definitions in Programmer's Guide)
    287 * RETURNS:
    288 *  Returns NULL if the function succeeds.
    289 *  Returns a Logger Error if the function fails in a non-fatal way.
    290 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    291 */
    292 PKIX_Error *
    293 PKIX_Logger_GetLoggingComponent(
    294        PKIX_Logger *logger,
    295        PKIX_ERRORCLASS *pComponent,
    296        void *plContext);
    297 
    298 /*
    299 * FUNCTION: PKIX_Logger_SetLoggingComponent
    300 * DESCRIPTION:
    301 *
    302 *  Sets the logging component of the Logger pointed to by "logger" with the
    303 *  PKIXERRORNUM pointed to by "component". To match a small set of components,
    304 *  create a Logger for each.
    305 *
    306 * PARAMETERS:
    307 *  "logger"
    308 *      Address of Logger whose logging component is to be set.
    309 *      Must be non-NULL.
    310 *  "component"
    311 *      PKIXERRORNUM value representing logging component to be set.
    312 *  "plContext"
    313 *      Platform-specific context pointer.
    314 * THREAD SAFETY:
    315 *  Not Thread Safe - assumes exclusive access to "logger"
    316 *  (see Thread Safety Definitions in Programmer's Guide)
    317 * RETURNS:
    318 *  Returns NULL if the function succeeds.
    319 *  Returns a Logger Error if the function fails in a non-fatal way.
    320 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    321 */
    322 PKIX_Error *
    323 PKIX_Logger_SetLoggingComponent(
    324        PKIX_Logger *logger,
    325        PKIX_ERRORCLASS component,
    326        void *plContext);
    327 
    328 /*
    329 * FUNCTION: PKIX_GetLoggers
    330 * DESCRIPTION:
    331 *
    332 *  Retrieves a pointer to the List of Loggers (if any) being used for logging
    333 *  by libpkix and stores it at "pLoggers". If no loggers are being used, this
    334 *  function stores an empty List at "pLoggers".
    335 *
    336 *  Note that the List returned by this function is immutable.
    337 *
    338 * PARAMETERS:
    339 *  "pLoggers"
    340 *      Address where object pointer will be stored. Must be non-NULL.
    341 *  "plContext"
    342 *      Platform-specific context pointer.
    343 * THREAD SAFETY:
    344 *  Conditionally Thread Safe
    345 *      (see Thread Safety Definitions in Programmer's Guide)
    346 * RETURNS:
    347 *  Returns NULL if the function succeeds.
    348 *  Returns a Logger Error if the function fails in a non-fatal way.
    349 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    350 */
    351 PKIX_Error *
    352 PKIX_GetLoggers(
    353        PKIX_List **pLoggers,  /* list of PKIX_Logger */
    354        void *plContext);
    355 
    356 /*
    357 * FUNCTION: PKIX_SetLoggers
    358 * DESCRIPTION:
    359 *
    360 *  Sets the Loggers to be used by libpkix to the List of Loggers pointed to
    361 *  by "loggers". If "loggers" is NULL, no Loggers will be used.
    362 *
    363 * PARAMETERS:
    364 *  "loggers"
    365 *      Address of List of Loggers to be set. NULL for no Loggers.
    366 *  "plContext"
    367 *      Platform-specific context pointer.
    368 * THREAD SAFETY:
    369 *  Not Thread Safe
    370 *  (see Thread Safety Definitions in Programmer's Guide)
    371 * RETURNS:
    372 *  Returns NULL if the function succeeds.
    373 *  Returns a Logger Error if the function fails in a non-fatal way.
    374 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    375 */
    376 PKIX_Error *
    377 PKIX_SetLoggers(
    378        PKIX_List *loggers,  /* list of PKIX_Logger */
    379        void *plContext);
    380 
    381 /*
    382 * FUNCTION: PKIX_AddLogger
    383 * DESCRIPTION:
    384 *
    385 *  Adds the Logger pointed to by "logger" to the List of Loggers used by
    386 *  libpkix.
    387 *
    388 * PARAMETERS:
    389 *  "logger"
    390 *      Address of Logger to be added. Must be non-NULL.
    391 *  "plContext"
    392 *      Platform-specific context pointer.
    393 * THREAD SAFETY:
    394 *  Not Thread Safe
    395 *  (see Thread Safety Definitions in Programmer's Guide)
    396 * RETURNS:
    397 *  Returns NULL if the function succeeds.
    398 *  Returns a Logger Error if the function fails in a non-fatal way.
    399 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    400 */
    401 PKIX_Error *
    402 PKIX_AddLogger(
    403        PKIX_Logger *logger,
    404        void *plContext);
    405 
    406 /* Functions pertaining to the PKIX_Error type */
    407 
    408 /* Error
    409 *
    410 * An Error object is returned by a function upon encountering some error
    411 * condition. Each Error is associated with an errorCode specified in pkixt.h.
    412 * The remaining components of an Error are optional. An Error's description
    413 * specifies a text message describing the Error. An Error's supplementary info
    414 * specifies additional information that might be useful. Finally, an Error's
    415 * cause specifies the underlying Error (if any) that resulted in this Error
    416 * being returned, thereby allowing Errors to be chained so that an entire
    417 * "error stack trace" can be represented. Once created, an Error is immutable.
    418 *
    419 * Note that the Error's supplementary info must be an Object (although any
    420 * object type), allowing it to be reference-counted and allowing it to
    421 * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
    422 * Duplicate).
    423 *
    424 * Errors are classified as either being fatal or non-fatal. If a function
    425 * fails in an unrecoverable way, it returns an Error whose errorCode is
    426 * PKIX_FATAL_ERROR. If such an error is encountered, the caller should
    427 * not attempt to recover since something seriously wrong has happened
    428 * (e.g. corrupted memory, memory finished, etc.). All other errorCodes
    429 * are considered non-fatal errors and can be handled by the caller as they
    430 * see fit.
    431 */
    432 
    433 /*
    434 * FUNCTION: PKIX_Error_Create
    435 * DESCRIPTION:
    436 *
    437 *  Creates a new Error using the value of "errorCode", the Error pointed to by
    438 *  "cause" (if any), the Object pointed to by "info" (if any), and the String
    439 *  pointed to by "desc" and stores it at "pError". If any error occurs during
    440 *  error allocation, it will be returned without chaining, since new errors
    441 *  cannot be created. Once created, an Error is immutable.
    442 *
    443 * PARAMETERS:
    444 *  "errorCode"
    445 *      Value of error code.
    446 *  "cause"
    447 *      Address of Error representing error's cause.
    448 *      NULL if none or unspecified.
    449 *  "info"
    450 *      Address of Object representing error's supplementary information.
    451 *      NULL if none.
    452 *  "desc"
    453 *      Address of String representing error's description. NULL if none.
    454 *  "pError"
    455 *      Address where object pointer will be stored. Must be non-NULL.
    456 *  "plContext"
    457 *      Platform-specific context pointer.
    458 * THREAD SAFETY:
    459 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    460 * RETURNS:
    461 *  Returns NULL if the function succeeds.
    462 *  Returns an Error Error if the function fails in a non-fatal way.
    463 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    464 */
    465 PKIX_Error *
    466 PKIX_Error_Create(
    467        PKIX_ERRORCLASS errClass,
    468        PKIX_Error *cause,
    469        PKIX_PL_Object *info,
    470        PKIX_ERRORCODE errCode,
    471        PKIX_Error **pError,
    472        void *plContext);
    473 
    474 /*
    475 * FUNCTION: PKIX_Error_GetErrorClass
    476 * DESCRIPTION:
    477 *
    478 *  Retrieves the error class of the Error pointed to by "error" and 
    479 *  stores it at "pClass". Supported error codes are defined in pkixt.h.
    480 *
    481 * PARAMETERS:
    482 *  "error"
    483 *      Address of Error whose error code is desired. Must be non-NULL.
    484 *  "pClass"
    485 *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
    486 *  "plContext"
    487 *      Platform-specific context pointer.
    488 * THREAD SAFETY:
    489 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    490 * RETURNS:
    491 *  Returns NULL if the function succeeds.
    492 *  Returns an Error Error if the function fails in a non-fatal way.
    493 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    494 */
    495 PKIX_Error *
    496 PKIX_Error_GetErrorClass(
    497        PKIX_Error *error,
    498        PKIX_ERRORCLASS *pClass,
    499        void *plContext);
    500 
    501 /*
    502 * FUNCTION: PKIX_Error_GetErrorCode
    503 * DESCRIPTION:
    504 *
    505 *  Retrieves the error code of the Error pointed to by "error" and 
    506 *  stores it at "pCode". Supported error codes are defined in pkixt.h.
    507 *
    508 * PARAMETERS:
    509 *  "error"
    510 *      Address of Error whose error code is desired. Must be non-NULL.
    511 *  "pCode"
    512 *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
    513 *  "plContext"
    514 *      Platform-specific context pointer.
    515 * THREAD SAFETY:
    516 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    517 * RETURNS:
    518 *  Returns NULL if the function succeeds.
    519 *  Returns an Error Error if the function fails in a non-fatal way.
    520 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    521 */
    522 PKIX_Error *
    523 PKIX_Error_GetErrorCode(
    524        PKIX_Error *error,
    525        PKIX_ERRORCODE *pCode,
    526        void *plContext);
    527 
    528 /*
    529 * FUNCTION: PKIX_Error_GetCause
    530 * DESCRIPTION:
    531 *
    532 *  Retrieves the cause of the Error pointed to by "error" and stores it at
    533 *  "pCause". If no cause was specified, NULL will be stored at "pCause".
    534 *
    535 * PARAMETERS:
    536 *  "error"
    537 *      Address of Error whose cause is desired. Must be non-NULL.
    538 *  "pCause"
    539 *      Address where object pointer will be stored. Must be non-NULL.
    540 *  "plContext"
    541 *      Platform-specific context pointer.
    542 * THREAD SAFETY:
    543 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    544 * RETURNS:
    545 *  Returns NULL if the function succeeds.
    546 *  Returns an Error Error if the function fails in a non-fatal way.
    547 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    548 */
    549 PKIX_Error *
    550 PKIX_Error_GetCause(
    551        PKIX_Error *error,
    552        PKIX_Error **pCause,
    553        void *plContext);
    554 
    555 /*
    556 * FUNCTION: PKIX_Error_GetSupplementaryInfo
    557 * DESCRIPTION:
    558 *
    559 *  Retrieves the supplementary info of the Error pointed to by "error" and
    560 *  stores it at "pInfo".
    561 *
    562 * PARAMETERS:
    563 *  "error"
    564 *      Address of Error whose info is desired. Must be non-NULL.
    565 *  "pInfo"
    566 *      Address where info pointer will be stored. Must be non-NULL.
    567 *  "plContext"
    568 *      Platform-specific context pointer.
    569 * THREAD SAFETY:
    570 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    571 * RETURNS:
    572 *  Returns NULL if the function succeeds.
    573 *  Returns an Error Error if the function fails in a non-fatal way.
    574 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    575 */
    576 PKIX_Error *
    577 PKIX_Error_GetSupplementaryInfo(
    578        PKIX_Error *error,
    579        PKIX_PL_Object **pInfo,
    580        void *plContext);
    581 
    582 /*
    583 * FUNCTION: PKIX_Error_GetDescription
    584 * DESCRIPTION:
    585 *
    586 *  Retrieves the description of the Error pointed to by "error" and stores it
    587 *  at "pDesc". If no description was specified, NULL will be stored at
    588 *  "pDesc".
    589 *
    590 * PARAMETERS:
    591 *  "error"
    592 *      Address of Error whose description is desired. Must be non-NULL.
    593 *  "pDesc"
    594 *      Address where object pointer will be stored. Must be non-NULL.
    595 *  "plContext"
    596 *      Platform-specific context pointer.
    597 * THREAD SAFETY:
    598 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    599 * RETURNS:
    600 *  Returns NULL if the function succeeds.
    601 *  Returns an Error Error if the function fails in a non-fatal way.
    602 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    603 */
    604 PKIX_Error *
    605 PKIX_Error_GetDescription(
    606        PKIX_Error *error,
    607        PKIX_PL_String **pDesc,
    608        void *plContext);
    609 
    610 /* PKIX_List
    611 *
    612 * Represents a collection of items. NULL is considered a valid item.
    613 */
    614 
    615 /*
    616 * FUNCTION: PKIX_List_Create
    617 * DESCRIPTION:
    618 *
    619 *  Creates a new List and stores it at "pList". The List is initially empty
    620 *  and holds no items. To initially add items to the List, use
    621 *  PKIX_List_AppendItem
    622 *
    623 * PARAMETERS:
    624 *  "pList"
    625 *      Address where object pointer will be stored. Must be non-NULL.
    626 *  "plContext"
    627 *      Platform-specific context pointer.
    628 * THREAD SAFETY:
    629 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    630 * RETURNS:
    631 *  Returns NULL if the function succeeds.
    632 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    633 */
    634 PKIX_Error *
    635 PKIX_List_Create(
    636        PKIX_List **pList,
    637        void *plContext);
    638 
    639 /*
    640 * FUNCTION: PKIX_List_SetImmutable
    641 * DESCRIPTION:
    642 *
    643 *  Sets the List pointed to by "list" to be immutable. If a caller tries to
    644 *  change a List after it has been marked immutable (i.e. by calling
    645 *  PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
    646 *  PKIX_List_DeleteItem), an Error is returned.
    647 *
    648 * PARAMETERS:
    649 *  "list"
    650 *      Address of List to be marked immutable. Must be non-NULL.
    651 *  "plContext"
    652 *      Platform-specific context pointer.
    653 * THREAD SAFETY:
    654 *  Not Thread Safe - assumes exclusive access to "list"
    655 *  (see Thread Safety Definitions in Programmer's Guide)
    656 * RETURNS:
    657 *  Returns NULL if the function succeeds.
    658 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    659 */
    660 PKIX_Error *
    661 PKIX_List_SetImmutable(
    662        PKIX_List *list,
    663        void *plContext);
    664 
    665 /*
    666 * FUNCTION: PKIX_List_IsImmutable
    667 * DESCRIPTION:
    668 *
    669 *  Checks whether the List pointed to by "list" is immutable and stores
    670 *  the Boolean result at "pImmutable". If a caller tries to change a List
    671 *  after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
    672 *  PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
    673 *  Error is returned.
    674 *
    675 * PARAMETERS:
    676 *  "list"
    677 *      Address of List whose immutability is to be determined.
    678 *      Must be non-NULL.
    679 *  "pImmutable"
    680 *      Address where PKIX_Boolean will be stored. Must be non-NULL.
    681 *  "plContext"
    682 *      Platform-specific context pointer.
    683 * THREAD SAFETY:
    684 *  Conditionally Thread Safe
    685 *      (see Thread Safety Definitions in Programmer's Guide)
    686 * RETURNS:
    687 *  Returns NULL if the function succeeds.
    688 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    689 */
    690 PKIX_Error *
    691 PKIX_List_IsImmutable(
    692        PKIX_List *list,
    693        PKIX_Boolean *pImmutable,
    694        void *plContext);
    695 
    696 /*
    697 * FUNCTION: PKIX_List_GetLength
    698 * DESCRIPTION:
    699 *
    700 *  Retrieves the length of the List pointed to by "list" and stores it at
    701 *  "pLength".
    702 *
    703 * PARAMETERS:
    704 *  "list"
    705 *      Address of List whose length is desired. Must be non-NULL.
    706 *  "pLength"
    707 *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
    708 *  "plContext"
    709 *      Platform-specific context pointer.
    710 * THREAD SAFETY:
    711 *  Conditionally Thread Safe
    712 *      (see Thread Safety Definitions in Programmer's Guide)
    713 * RETURNS:
    714 *  Returns NULL if the function succeeds.
    715 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    716 */
    717 PKIX_Error *
    718 PKIX_List_GetLength(
    719        PKIX_List *list,
    720        PKIX_UInt32 *pLength,
    721        void *plContext);
    722 
    723 /*
    724 * FUNCTION: PKIX_List_IsEmpty
    725 * DESCRIPTION:
    726 *
    727 *  Checks whether the List pointed to by "list" is empty and stores
    728 *  the Boolean result at "pEmpty".
    729 *
    730 * PARAMETERS:
    731 *  "list"
    732 *      Address of List whose emptiness is to be determined. Must be non-NULL.
    733 *  "pEmpty"
    734 *      Address where PKIX_Boolean will be stored. Must be non-NULL.
    735 *  "plContext"
    736 *      Platform-specific context pointer.
    737 * THREAD SAFETY:
    738 *  Conditionally Thread Safe
    739 *      (see Thread Safety Definitions in Programmer's Guide)
    740 * RETURNS:
    741 *  Returns NULL if the function succeeds.
    742 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    743 */
    744 PKIX_Error *
    745 PKIX_List_IsEmpty(
    746        PKIX_List *list,
    747        PKIX_Boolean *pEmpty,
    748        void *plContext);
    749 
    750 /*
    751 * FUNCTION: PKIX_List_AppendItem
    752 * DESCRIPTION:
    753 *
    754 *  Appends the Object pointed to by "item" after the last non-NULL item in
    755 *  List pointed to by "list", if any. Note that a List may validly contain
    756 *  NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
    757 *  in ("a", NULL, "b", "c").
    758 *
    759 * PARAMETERS:
    760 *  "list"
    761 *      Address of List to append to. Must be non-NULL.
    762 *  "item"
    763 *      Address of new item to append.
    764 *  "plContext"
    765 *      Platform-specific context pointer.
    766 * THREAD SAFETY:
    767 *  Not Thread Safe - assumes exclusive access to "list"
    768 *  (see Thread Safety Definitions in Programmer's Guide)
    769 * RETURNS:
    770 *  Returns NULL if the function succeeds.
    771 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    772 */
    773 PKIX_Error *
    774 PKIX_List_AppendItem(
    775        PKIX_List *list,
    776        PKIX_PL_Object *item,
    777        void *plContext);
    778 
    779 /*
    780 * FUNCTION: PKIX_List_InsertItem
    781 * DESCRIPTION:
    782 *
    783 *  Inserts the Object pointed to by "item" into the List pointed to by "list"
    784 *  at the given "index". The index counts from zero and must be less than the
    785 *  List's length. Existing list entries at or after this index will be moved
    786 *  to the next highest index.
    787 *
    788 *  XXX why not allow equal to length which would be equivalent to AppendItem?
    789 *
    790 * PARAMETERS:
    791 *  "list"
    792 *      Address of List to insert into. Must be non-NULL.
    793 *  "index"
    794 *      Position to insert into. Must be less than List's length.
    795 *  "item"
    796 *      Address of new item to append.
    797 *  "plContext"
    798 *      Platform-specific context pointer.
    799 * THREAD SAFETY:
    800 *  Not Thread Safe - assumes exclusive access to "list"
    801 *  (see Thread Safety Definitions in Programmer's Guide)
    802 * RETURNS:
    803 *  Returns NULL if the function succeeds.
    804 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    805 */
    806 PKIX_Error *
    807 PKIX_List_InsertItem(
    808        PKIX_List *list,
    809        PKIX_UInt32 index,
    810        PKIX_PL_Object *item,
    811        void *plContext);
    812 
    813 /*
    814 * FUNCTION: PKIX_List_GetItem
    815 * DESCRIPTION:
    816 *
    817 *  Copies the "list"'s item at "index" into "pItem". The index counts from
    818 *  zero and must be less than the list's length. Increments the reference
    819 *  count on the returned object, if non-NULL.
    820 *
    821 * PARAMETERS:
    822 *  "list"
    823 *      Address of List to get item from. Must be non-NULL.
    824 *  "index"
    825 *      Index of list to get item from. Must be less than List's length.
    826 *  "pItem"
    827 *      Address where object pointer will be stored. Must be non-NULL.
    828 *  "plContext"
    829 *      Platform-specific context pointer.
    830 * THREAD SAFETY:
    831 *  Conditionally Thread Safe
    832 *      (see Thread Safety Definitions in Programmer's Guide)
    833 * RETURNS:
    834 *  Returns NULL if the function succeeds.
    835 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    836 */
    837 PKIX_Error *
    838 PKIX_List_GetItem(
    839        PKIX_List *list,
    840        PKIX_UInt32 index,
    841        PKIX_PL_Object **pItem,
    842        void *plContext);
    843 
    844 /*
    845 * FUNCTION: PKIX_List_SetItem
    846 * DESCRIPTION:
    847 *
    848 *  Sets the item at "index" of the List pointed to by "list" with the Object
    849 *  pointed to by "item". The index counts from zero and must be less than the
    850 *  List's length. The previous entry at this index will have its reference
    851 *  count decremented and the new entry will have its reference count
    852 *  incremented.
    853 *
    854 * PARAMETERS:
    855 *  "list"
    856 *      Address of List to modify. Must be non-NULL.
    857 *  "index"
    858 *      Position in List to set. Must be less than List's length.
    859 *  "item"
    860 *      Address of Object to set at "index".
    861 *  "plContext"
    862 *      Platform-specific context pointer.
    863 * THREAD SAFETY:
    864 *  Not Thread Safe - assumes exclusive access to "list"
    865 *  (see Thread Safety Definitions in Programmer's Guide)
    866 * RETURNS:
    867 *  Returns NULL if the function succeeds.
    868 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    869 */
    870 PKIX_Error *
    871 PKIX_List_SetItem(
    872        PKIX_List *list,
    873        PKIX_UInt32 index,
    874        PKIX_PL_Object *item,
    875        void *plContext);
    876 
    877 /*
    878 * FUNCTION: PKIX_List_DeleteItem
    879 *
    880 *  Deletes the item at "index" from the List pointed to by "list". The index
    881 *  counts from zero and must be less than the List's length. Note that this
    882 *  function does not destroy the List. It simply decrements the reference
    883 *  count of the item at "index" in the List, deletes that item from the list
    884 *  and moves all subsequent entries to a lower index in the list. If there is
    885 *  only a single element in the List and that element is deleted, then the
    886 *  List will be empty.
    887 *
    888 * PARAMETERS:
    889 *  "list"
    890 *      Address of List to delete from. Must be non-NULL.
    891 *  "index"
    892 *      Position in List to delete. Must be less than List's length.
    893 *  "plContext"
    894 *      Platform-specific context pointer.
    895 * THREAD SAFETY:
    896 *  Not Thread Safe - assumes exclusive access to "list"
    897 *  (see Thread Safety Definitions in Programmer's Guide)
    898 * RETURNS:
    899 *  Returns NULL if the function succeeds.
    900 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    901 */
    902 PKIX_Error *
    903 PKIX_List_DeleteItem(
    904        PKIX_List *list,
    905        PKIX_UInt32 index,
    906        void *plContext);
    907 
    908 /*
    909 * FUNCTION: PKIX_List_ReverseList
    910 * DESCRIPTION:
    911 *
    912 *  Creates a new List whose elements are in the reverse order as the elements
    913 *  of the Object pointed to by "list" and stores the copy at "pReversedList".
    914 *  If "list" is empty, the new reversed List will be a copy of "list".
    915 *  Changes to the new object will not affect the original and vice versa.
    916 *
    917 * PARAMETERS:
    918 *  "list"
    919 *      Address of List whose elements are to be reversed. Must be non-NULL.
    920 *  "pReversedList"
    921 *      Address where object pointer will be stored. Must be non-NULL.
    922 *  "plContext"
    923 *      Platform-specific context pointer.
    924 * THREAD SAFETY:
    925 *  Conditionally Thread Safe
    926 *      (see Thread Safety Definitions in Programmer's Guide)
    927 * RETURNS:
    928 *  Returns NULL if the function succeeds.
    929 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    930 */
    931 PKIX_Error *
    932 PKIX_List_ReverseList(
    933        PKIX_List *list,
    934        PKIX_List **pReversedList,
    935        void *plContext);
    936 
    937 #ifdef __cplusplus
    938 }
    939 #endif
    940 
    941 #endif /* _PKIX_UTIL_H */
	tor-browser The Tor Browser
	git clone https://git.dasho.dev/tor-browser.git
	Log \| Files \| Refs \| README \| LICENSE