/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
 49extern "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 */
144typedef 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 */
178PKIX_Error *
179PKIX_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 */
207PKIX_Error *
208PKIX_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 */
234PKIX_Error *
235PKIX_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 */
265PKIX_Error *
266PKIX_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 */
294PKIX_Error *
295PKIX_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 */
325PKIX_Error *
326PKIX_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 */
355PKIX_Error *
356PKIX_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 */
384PKIX_Error *
385PKIX_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 */
409PKIX_Error *
410PKIX_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 */
434PKIX_Error *
435PKIX_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 */
498PKIX_Error *
499PKIX_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 */
528PKIX_Error *
529PKIX_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 */
555PKIX_Error *
556PKIX_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 */
582PKIX_Error *
583PKIX_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 */
609PKIX_Error *
610PKIX_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 */
637PKIX_Error *
638PKIX_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 */
667PKIX_Error *
668PKIX_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 */
693PKIX_Error *
694PKIX_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 */
723PKIX_Error *
724PKIX_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 */
750PKIX_Error *
751PKIX_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 */
777PKIX_Error *
778PKIX_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 */
806PKIX_Error *
807PKIX_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 */
839PKIX_Error *
840PKIX_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 */
870PKIX_Error *
871PKIX_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 */
903PKIX_Error *
904PKIX_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 */
935PKIX_Error *
936PKIX_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 */
964PKIX_Error *
965PKIX_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 */