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 PKIX-C library.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Sun Microsystems, Inc.
  18  * Portions created by the Initial Developer are
  19  * Copyright 2004-2007 Sun Microsystems, Inc.  All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Sun Microsystems, Inc.
  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_ERRORCLASS 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_ERRORCLASS *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_ERRORCLASS 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_ERRORCLASS errClass,
 501         PKIX_Error *cause,
 502         PKIX_PL_Object *info,
 503         PKIX_ERRORCODE errCode,
 504         PKIX_Error **pError,
 505         void *plContext);
 506
 507 /*
 508  * FUNCTION: PKIX_Error_GetErrorClass
 509  * DESCRIPTION:
 510  *
 511  *  Retrieves the error class of the Error pointed to by "error" and
 512  *  stores it at "pClass". 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  *  "pClass"
 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_GetErrorClass(
 530         PKIX_Error *error,
 531         PKIX_ERRORCLASS *pClass,
 532         void *plContext);
 533
 534 /*
 535  * FUNCTION: PKIX_Error_GetErrorCode
 536  * DESCRIPTION:
 537  *
 538  *  Retrieves the error code of the Error pointed to by "error" and
 539  *  stores it at "pCode". Supported error codes are defined in pkixt.h.
 540  *
 541  * PARAMETERS:
 542  *  "error"
 543  *      Address of Error whose error code is desired. Must be non-NULL.
 544  *  "pCode"
 545  *      Address where PKIX_UInt32 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_GetErrorCode(
 557         PKIX_Error *error,
 558         PKIX_ERRORCODE *pCode,
 559         void *plContext);
 560
 561 /*
 562  * FUNCTION: PKIX_Error_GetCause
 563  * DESCRIPTION:
 564  *
 565  *  Retrieves the cause of the Error pointed to by "error" and stores it at
 566  *  "pCause". If no cause was specified, NULL will be stored at "pCause".
 567  *
 568  * PARAMETERS:
 569  *  "error"
 570  *      Address of Error whose cause is desired. Must be non-NULL.
 571  *  "pCause"
 572  *      Address where object 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_GetCause(
 584         PKIX_Error *error,
 585         PKIX_Error **pCause,
 586         void *plContext);
 587
 588 /*
 589  * FUNCTION: PKIX_Error_GetSupplementaryInfo
 590  * DESCRIPTION:
 591  *
 592  *  Retrieves the supplementary info of the Error pointed to by "error" and
 593  *  stores it at "pInfo".
 594  *
 595  * PARAMETERS:
 596  *  "error"
 597  *      Address of Error whose info is desired. Must be non-NULL.
 598  *  "pInfo"
 599  *      Address where info pointer will be stored. Must be non-NULL.
 600  *  "plContext"
 601  *      Platform-specific context pointer.
 602  * THREAD SAFETY:
 603  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 604  * RETURNS:
 605  *  Returns NULL if the function succeeds.
 606  *  Returns an Error Error if the function fails in a non-fatal way.
 607  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 608  */
 609 PKIX_Error *
 610 PKIX_Error_GetSupplementaryInfo(
 611         PKIX_Error *error,
 612         PKIX_PL_Object **pInfo,
 613         void *plContext);
 614
 615 /*
 616  * FUNCTION: PKIX_Error_GetDescription
 617  * DESCRIPTION:
 618  *
 619  *  Retrieves the description of the Error pointed to by "error" and stores it
 620  *  at "pDesc". If no description was specified, NULL will be stored at
 621  *  "pDesc".
 622  *
 623  * PARAMETERS:
 624  *  "error"
 625  *      Address of Error whose description is desired. Must be non-NULL.
 626  *  "pDesc"
 627  *      Address where object pointer will be stored. Must be non-NULL.
 628  *  "plContext"
 629  *      Platform-specific context pointer.
 630  * THREAD SAFETY:
 631  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 632  * RETURNS:
 633  *  Returns NULL if the function succeeds.
 634  *  Returns an Error Error if the function fails in a non-fatal way.
 635  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 636  */
 637 PKIX_Error *
 638 PKIX_Error_GetDescription(
 639         PKIX_Error *error,
 640         PKIX_PL_String **pDesc,
 641         void *plContext);
 642
 643 /* PKIX_List
 644  *
 645  * Represents a collection of items. NULL is considered a valid item.
 646  */
 647
 648 /*
 649  * FUNCTION: PKIX_List_Create
 650  * DESCRIPTION:
 651  *
 652  *  Creates a new List and stores it at "pList". The List is initially empty
 653  *  and holds no items. To initially add items to the List, use
 654  *  PKIX_List_AppendItem
 655  *
 656  * PARAMETERS:
 657  *  "pList"
 658  *      Address where object pointer will be stored. Must be non-NULL.
 659  *  "plContext"
 660  *      Platform-specific context pointer.
 661  * THREAD SAFETY:
 662  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 663  * RETURNS:
 664  *  Returns NULL if the function succeeds.
 665  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 666  */
 667 PKIX_Error *
 668 PKIX_List_Create(
 669         PKIX_List **pList,
 670         void *plContext);
 671
 672 /*
 673  * FUNCTION: PKIX_List_SetImmutable
 674  * DESCRIPTION:
 675  *
 676  *  Sets the List pointed to by "list" to be immutable. If a caller tries to
 677  *  change a List after it has been marked immutable (i.e. by calling
 678  *  PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
 679  *  PKIX_List_DeleteItem), an Error is returned.
 680  *
 681  * PARAMETERS:
 682  *  "list"
 683  *      Address of List to be marked immutable. Must be non-NULL.
 684  *  "plContext"
 685  *      Platform-specific context pointer.
 686  * THREAD SAFETY:
 687  *  Not Thread Safe - assumes exclusive access to "list"
 688  *  (see Thread Safety Definitions in Programmer's Guide)
 689  * RETURNS:
 690  *  Returns NULL if the function succeeds.
 691  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 692  */
 693 PKIX_Error *
 694 PKIX_List_SetImmutable(
 695         PKIX_List *list,
 696         void *plContext);
 697
 698 /*
 699  * FUNCTION: PKIX_List_IsImmutable
 700  * DESCRIPTION:
 701  *
 702  *  Checks whether the List pointed to by "list" is immutable and stores
 703  *  the Boolean result at "pImmutable". If a caller tries to change a List
 704  *  after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
 705  *  PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
 706  *  Error is returned.
 707  *
 708  * PARAMETERS:
 709  *  "list"
 710  *      Address of List whose immutability is to be determined.
 711  *      Must be non-NULL.
 712  *  "pImmutable"
 713  *      Address where PKIX_Boolean 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_IsImmutable(
 725         PKIX_List *list,
 726         PKIX_Boolean *pImmutable,
 727         void *plContext);
 728
 729 /*
 730  * FUNCTION: PKIX_List_GetLength
 731  * DESCRIPTION:
 732  *
 733  *  Retrieves the length of the List pointed to by "list" and stores it at
 734  *  "pLength".
 735  *
 736  * PARAMETERS:
 737  *  "list"
 738  *      Address of List whose length is desired. Must be non-NULL.
 739  *  "pLength"
 740  *      Address where PKIX_UInt32 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_GetLength(
 752         PKIX_List *list,
 753         PKIX_UInt32 *pLength,
 754         void *plContext);
 755
 756 /*
 757  * FUNCTION: PKIX_List_IsEmpty
 758  * DESCRIPTION:
 759  *
 760  *  Checks whether the List pointed to by "list" is empty and stores
 761  *  the Boolean result at "pEmpty".
 762  *
 763  * PARAMETERS:
 764  *  "list"
 765  *      Address of List whose emptiness is to be determined. Must be non-NULL.
 766  *  "pEmpty"
 767  *      Address where PKIX_Boolean will be stored. Must be non-NULL.
 768  *  "plContext"
 769  *      Platform-specific context pointer.
 770  * THREAD SAFETY:
 771  *  Conditionally Thread Safe
 772  *      (see Thread Safety Definitions in Programmer's Guide)
 773  * RETURNS:
 774  *  Returns NULL if the function succeeds.
 775  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 776  */
 777 PKIX_Error *
 778 PKIX_List_IsEmpty(
 779         PKIX_List *list,
 780         PKIX_Boolean *pEmpty,
 781         void *plContext);
 782
 783 /*
 784  * FUNCTION: PKIX_List_AppendItem
 785  * DESCRIPTION:
 786  *
 787  *  Appends the Object pointed to by "item" after the last non-NULL item in
 788  *  List pointed to by "list", if any. Note that a List may validly contain
 789  *  NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
 790  *  in ("a", NULL, "b", "c").
 791  *
 792  * PARAMETERS:
 793  *  "list"
 794  *      Address of List to append to. Must be non-NULL.
 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_AppendItem(
 808         PKIX_List *list,
 809         PKIX_PL_Object *item,
 810         void *plContext);
 811
 812 /*
 813  * FUNCTION: PKIX_List_InsertItem
 814  * DESCRIPTION:
 815  *
 816  *  Inserts the Object pointed to by "item" into the List pointed to by "list"
 817  *  at the given "index". The index counts from zero and must be less than the
 818  *  List's length. Existing list entries at or after this index will be moved
 819  *  to the next highest index.
 820  *
 821  *  XXX why not allow equal to length which would be equivalent to AppendItem?
 822  *
 823  * PARAMETERS:
 824  *  "list"
 825  *      Address of List to insert into. Must be non-NULL.
 826  *  "index"
 827  *      Position to insert into. Must be less than List's length.
 828  *  "item"
 829  *      Address of new item to append.
 830  *  "plContext"
 831  *      Platform-specific context pointer.
 832  * THREAD SAFETY:
 833  *  Not Thread Safe - assumes exclusive access to "list"
 834  *  (see Thread Safety Definitions in Programmer's Guide)
 835  * RETURNS:
 836  *  Returns NULL if the function succeeds.
 837  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 838  */
 839 PKIX_Error *
 840 PKIX_List_InsertItem(
 841         PKIX_List *list,
 842         PKIX_UInt32 index,
 843         PKIX_PL_Object *item,
 844         void *plContext);
 845
 846 /*
 847  * FUNCTION: PKIX_List_GetItem
 848  * DESCRIPTION:
 849  *
 850  *  Copies the "list"'s item at "index" into "pItem". The index counts from
 851  *  zero and must be less than the list's length. Increments the reference
 852  *  count on the returned object, if non-NULL.
 853  *
 854  * PARAMETERS:
 855  *  "list"
 856  *      Address of List to get item from. Must be non-NULL.
 857  *  "index"
 858  *      Index of list to get item from. Must be less than List's length.
 859  *  "pItem"
 860  *      Address where object pointer will be stored. Must be non-NULL.
 861  *  "plContext"
 862  *      Platform-specific context pointer.
 863  * THREAD SAFETY:
 864  *  Conditionally Thread Safe
 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_GetItem(
 872         PKIX_List *list,
 873         PKIX_UInt32 index,
 874         PKIX_PL_Object **pItem,
 875         void *plContext);
 876
 877 /*
 878  * FUNCTION: PKIX_List_SetItem
 879  * DESCRIPTION:
 880  *
 881  *  Sets the item at "index" of the List pointed to by "list" with the Object
 882  *  pointed to by "item". The index counts from zero and must be less than the
 883  *  List's length. The previous entry at this index will have its reference
 884  *  count decremented and the new entry will have its reference count
 885  *  incremented.
 886  *
 887  * PARAMETERS:
 888  *  "list"
 889  *      Address of List to modify. Must be non-NULL.
 890  *  "index"
 891  *      Position in List to set. Must be less than List's length.
 892  *  "item"
 893  *      Address of Object to set at "index".
 894  *  "plContext"
 895  *      Platform-specific context pointer.
 896  * THREAD SAFETY:
 897  *  Not Thread Safe - assumes exclusive access to "list"
 898  *  (see Thread Safety Definitions in Programmer's Guide)
 899  * RETURNS:
 900  *  Returns NULL if the function succeeds.
 901  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 902  */
 903 PKIX_Error *
 904 PKIX_List_SetItem(
 905         PKIX_List *list,
 906         PKIX_UInt32 index,
 907         PKIX_PL_Object *item,
 908         void *plContext);
 909
 910 /*
 911  * FUNCTION: PKIX_List_DeleteItem
 912  *
 913  *  Deletes the item at "index" from the List pointed to by "list". The index
 914  *  counts from zero and must be less than the List's length. Note that this
 915  *  function does not destroy the List. It simply decrements the reference
 916  *  count of the item at "index" in the List, deletes that item from the list
 917  *  and moves all subsequent entries to a lower index in the list. If there is
 918  *  only a single element in the List and that element is deleted, then the
 919  *  List will be empty.
 920  *
 921  * PARAMETERS:
 922  *  "list"
 923  *      Address of List to delete from. Must be non-NULL.
 924  *  "index"
 925  *      Position in List to delete. Must be less than List's length.
 926  *  "plContext"
 927  *      Platform-specific context pointer.
 928  * THREAD SAFETY:
 929  *  Not Thread Safe - assumes exclusive access to "list"
 930  *  (see Thread Safety Definitions in Programmer's Guide)
 931  * RETURNS:
 932  *  Returns NULL if the function succeeds.
 933  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 934  */
 935 PKIX_Error *
 936 PKIX_List_DeleteItem(
 937         PKIX_List *list,
 938         PKIX_UInt32 index,
 939         void *plContext);
 940
 941 /*
 942  * FUNCTION: PKIX_List_ReverseList
 943  * DESCRIPTION:
 944  *
 945  *  Creates a new List whose elements are in the reverse order as the elements
 946  *  of the Object pointed to by "list" and stores the copy at "pReversedList".
 947  *  If "list" is empty, the new reversed List will be a copy of "list".
 948  *  Changes to the new object will not affect the original and vice versa.
 949  *
 950  * PARAMETERS:
 951  *  "list"
 952  *      Address of List whose elements are to be reversed. Must be non-NULL.
 953  *  "pReversedList"
 954  *      Address where object pointer will be stored. Must be non-NULL.
 955  *  "plContext"
 956  *      Platform-specific context pointer.
 957  * THREAD SAFETY:
 958  *  Conditionally Thread Safe
 959  *      (see Thread Safety Definitions in Programmer's Guide)
 960  * RETURNS:
 961  *  Returns NULL if the function succeeds.
 962  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 963  */
 964 PKIX_Error *
 965 PKIX_List_ReverseList(
 966         PKIX_List *list,
 967         PKIX_List **pReversedList,
 968         void *plContext);
 969
 970 #ifdef __cplusplus
 971 }
 972 #endif
 973
 974 #endif /* _PKIX_UTIL_H */