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