security/nss/lib/libpkix/include/pkix_util.h

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