security/nss/lib/libpkix/include/pkix_pl_system.h@b8a032363ba2
security/nss/lib/libpkix/include/pkix_pl_system.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 * This file defines several platform independent functions to make system
6 * calls in a portable manner.
7 *
8 */
10 #ifndef _PKIX_PL_SYSTEM_H
11 #define _PKIX_PL_SYSTEM_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 /*
45 * FUNCTION: PKIX_PL_Initialize
46 * DESCRIPTION:
47 *
48 * XXX If this function is really only meant to be used by PKIX_Initialize,
49 * why don't we just put it in a private header file rather than the public
50 * API. I think it may confuse users.
51 *
52 * This function should NOT be called by applications. It is only meant to
53 * be used internally. The application needs only to call PKIX_Initialize,
54 * which in turn will call this function.
55 *
56 * This function initializes data structures critical to the operation of
57 * libpkix. If initialization is not successful, an Error pointer is
58 * returned. This function should only be called once. If it is called more
59 * than once, the behavior is undefined.
60 *
61 * No PKIX_* types and functions should be used before this function is
62 * called and returns successfully.
63 *
64 * PARAMETERS:
65 * "platformInitNeeded"
66 * Boolean indicating whether platform initialization is to be called
67 * "useArenas"
68 * Boolean indicating whether allocation is to be done using arenas or
69 * individual allocation (malloc).
70 * "pPlContext"
71 * Address at which platform-specific context pointer is stored. Must be
72 * non-NULL.
73 * THREAD SAFETY:
74 * Not Thread Safe
75 *
76 * This function assumes that no other thread is calling this function while
77 * it is executing.
78 * RETURNS:
79 * Returns NULL if the function succeeds.
80 * Returns a Fatal Error if the function fails in an unrecoverable way.
81 */
82 PKIX_Error *
83 PKIX_PL_Initialize(
84 PKIX_Boolean platformInitNeeded,
85 PKIX_Boolean useArenas,
86 void **pPlContext);
88 /*
89 * FUNCTION: PKIX_PL_Shutdown
90 * DESCRIPTION:
91 *
92 * XXX If this function is really only meant to be used by PKIX_Shutdown,
93 * why don't we just put it in a private header file rather than the public
94 * API. I think it may confuse users.
95 *
96 * This function should NOT be called by applications. It is only meant to
97 * be used internally. The application needs only to call PKIX_Shutdown,
98 * which in turn will call this function.
99 *
100 * This function deallocates any memory used by the Portability Layer (PL)
101 * component of the libpkix library and shuts down any ongoing operations.
102 * This function should only be called once. If it is called more than once,
103 * the behavior is undefined.
104 *
105 * No PKIX_* types and functions should be used after this function is called
106 * and returns successfully.
107 *
108 * PARAMETERS:
109 * "platformInitNeeded"
110 * Boolean value of whether PKIX initialized NSS: PKIX_TRUE if we
111 * called nssInit, PKIX_FALSE otherwise
112 * "plContext"
113 * Platform-specific context pointer.
114 * THREAD SAFETY:
115 * Not Thread Safe
116 *
117 * This function makes use of global variables and should only be called once.
118 * RETURNS:
119 * Returns NULL if the function succeeds.
120 * Returns a Fatal Error if the function fails in an unrecoverable way.
121 */
122 PKIX_Error *
123 PKIX_PL_Shutdown(void *plContext);
125 /* standard memory management operations (not reference-counted) */
127 /*
128 * FUNCTION: PKIX_PL_Malloc
129 * DESCRIPTION:
130 *
131 * Allocates a block of "size" bytes. The bytes are not initialized. A
132 * pointer to the newly allocated memory will be stored at "pMemory". The
133 * memory allocated by PKIX_PL_Malloc() may only be freed by PKIX_PL_Free().
134 * If "size" equals zero, this function stores NULL at "pMemory".
135 *
136 * PARAMETERS:
137 * "size"
138 * Number of bytes to allocate.
139 * "pMemory"
140 * Address where newly allocated pointer will be stored. Must be non-NULL.
141 * "plContext"
142 * Platform-specific context pointer.
143 * THREAD SAFETY:
144 * Thread safety depends on underlying thread safety of platform used by PL.
145 * RETURNS:
146 * Returns NULL if the function succeeds.
147 * Returns a Fatal Error if the function fails in an unrecoverable way.
148 */
149 PKIX_Error *
150 PKIX_PL_Malloc(
151 PKIX_UInt32 size,
152 void **pMemory,
153 void *plContext);
155 /*
156 * FUNCTION: PKIX_PL_Calloc
157 * DESCRIPTION:
158 *
159 * Allocates memory for an array of "nElem" elements, with each element
160 * requiring "elSize" bytes, and with all the bits initialized to zero. A
161 * pointer to the newly allocated memory will be stored at "pMemory". The
162 * memory allocated by PKIX_PL_Calloc() may only be freed by PKIX_PL_Free().
163 * If "nElem" equals zero or "elSize" equals zero, this function stores NULL
164 * at "pMemory".
165 *
166 * PARAMETERS:
167 * "nElem"
168 * Number of elements needed.
169 * "elSize"
170 * Number of bytes needed per element.
171 * "pMemory"
172 * Address where newly allocated pointer will be stored. Must be non-NULL.
173 * "plContext"
174 * Platform-specific context pointer.
175 * THREAD SAFETY:
176 * Thread safety depends on underlying thread safety of platform used by PL.
177 * RETURNS:
178 * Returns NULL if the function succeeds.
179 * Returns a Fatal Error if the function fails in an unrecoverable way.
180 */
181 PKIX_Error *
182 PKIX_PL_Calloc(
183 PKIX_UInt32 nElem,
184 PKIX_UInt32 elSize,
185 void **pMemory,
186 void *plContext);
188 /*
189 * FUNCTION: PKIX_PL_Realloc
190 * DESCRIPTION:
191 *
192 * Resizes an existing block of memory (pointed to by "ptr") to "size" bytes.
193 * Stores a pointer to the resized memory at "pNewPtr". The "ptr" must
194 * originate from either PKIX_PL_Malloc(), PKIX_PL_Realloc(), or
195 * PKIX_PL_Calloc(). If "ptr" is NULL, this function behaves as if
196 * PKIX_PL_Malloc were called. If "ptr" is not NULL and "size" equals zero,
197 * the memory pointed to by "ptr" is deallocated and this function stores
198 * NULL at "pPtr".
199 *
200 * PARAMETERS:
201 * "ptr"
202 * A pointer to an existing block of memory.
203 * "size"
204 * New size in bytes.
205 * "pPtr"
206 * Address where newly allocated pointer will be stored. Must be non-NULL.
207 * "plContext"
208 * Platform-specific context pointer.
209 * THREAD SAFETY:
210 * Thread safety depends on underlying thread safety of platform used by PL.
211 * RETURNS:
212 * Returns NULL if the function succeeds.
213 * Returns a Fatal Error if the function fails in an unrecoverable way.
214 */
215 PKIX_Error *
216 PKIX_PL_Realloc(
217 void *ptr,
218 PKIX_UInt32 size,
219 void **pNewPtr,
220 void *plContext);
222 /*
223 * FUNCTION: PKIX_PL_Free
224 * DESCRIPTION:
225 *
226 * Frees a block of memory pointed to by "ptr". This value must originate with
227 * either PKIX_PL_Malloc(), PKIX_PL_Calloc, or PKIX_PL_Realloc(). If "ptr" is
228 * NULL, the function has no effect.
229 *
230 * PARAMETERS:
231 * "ptr"
232 * A pointer to an existing block of memory.
233 * "plContext"
234 * Platform-specific context pointer.
235 * THREAD SAFETY:
236 * Thread safety depends on underlying thread safety of platform used by PL.
237 * RETURNS:
238 * Returns NULL always.
239 */
240 PKIX_Error *
241 PKIX_PL_Free(
242 void *ptr,
243 void *plContext);
245 /* Callback Types
246 *
247 * The next few typedefs define function pointer types for the standard
248 * functions associated with every object type. See the Implementation
249 * Guidelines or the comments below for more information.
250 */
252 /*
253 * TYPE: PKIX_PL_DestructorCallback
254 * DESCRIPTION:
255 *
256 * This callback function destroys (or DecRef's) any pointers contained in
257 * the user data for the Object pointed to by "object" before the Object is
258 * destroyed.
259 *
260 * PARAMETERS:
261 * "object"
262 * Address of Object to destroy. Must be non-NULL.
263 * "plContext"
264 * Platform-specific context pointer.
265 * THREAD SAFETY:
266 * Thread Safe
267 *
268 * Multiple threads must be able to safely call this function without
269 * worrying about conflicts (as long as they're not operating on the same
270 * object and nobody else is performing an operation on the object at the
271 * same time). Both of these conditions should be guaranteed by the fact that
272 * the object's ref count was reduced to 0 in a lock that's still held when
273 * this callback is called.
274 * RETURNS:
275 * Returns NULL if the function succeeds.
276 * Returns an error if the function fails in a non-fatal way.
277 * Returns a Fatal Error if the function fails in an unrecoverable way.
278 */
279 typedef PKIX_Error *
280 (*PKIX_PL_DestructorCallback)(
281 PKIX_PL_Object *object,
282 void *plContext);
284 /*
285 * TYPE: PKIX_PL_EqualsCallback
286 * DESCRIPTION:
287 *
288 * This callback function compares the Object pointed to by "firstObject" with
289 * the Object pointed to by "secondObject" for equality and stores the result
290 * at "pResult" (PKIX_TRUE if equal; PKIX_FALSE if not).
291 *
292 * PARAMETERS:
293 * "firstObject"
294 * Address of first object to compare. Must be non-NULL.
295 * "secondObject"
296 * Address of second object to compare. Must be non-NULL.
297 * "pResult"
298 * Address where Boolean will be stored. Must be non-NULL.
299 * "plContext"
300 * Platform-specific context pointer.
301 * THREAD SAFETY:
302 * Thread Safe
303 *
304 * Multiple threads must be able to safely call this function without
305 * worrying about conflicts, even if they're operating on the same objects.
306 * RETURNS:
307 * Returns NULL if the function succeeds.
308 * Returns an error if the function fails in a non-fatal way.
309 * Returns a Fatal Error if the function fails in an unrecoverable way.
310 */
311 typedef PKIX_Error *
312 (*PKIX_PL_EqualsCallback)(
313 PKIX_PL_Object *firstObject,
314 PKIX_PL_Object *secondObject,
315 PKIX_Boolean *pResult,
316 void *plContext);
318 /*
319 * TYPE: PKIX_PL_HashcodeCallback
320 * DESCRIPTION:
321 *
322 * This callback function computes the hashcode of the Object pointed to by
323 * "object" and stores the result at "pValue".
324 *
325 * PARAMETERS:
326 * "object"
327 * Address of Object whose hashcode is desired. Must be non-NULL.
328 * "pValue"
329 * Address where PKIX_UInt32 will be stored. Must be non-NULL.
330 * "plContext"
331 * Platform-specific context pointer.
332 * THREAD SAFETY:
333 * Thread Safe
334 *
335 * Multiple threads must be able to safely call this function without
336 * worrying about conflicts, even if they're operating on the same object.
337 * RETURNS:
338 * Returns NULL if the function succeeds.
339 * Returns an error if the function fails in a non-fatal way.
340 * Returns a Fatal Error if the function fails in an unrecoverable way.
341 */
342 typedef PKIX_Error *
343 (*PKIX_PL_HashcodeCallback)(
344 PKIX_PL_Object *object,
345 PKIX_UInt32 *pValue,
346 void *plContext);
348 /*
349 * TYPE: PKIX_PL_ToStringCallback
350 * DESCRIPTION:
351 *
352 * This callback function converts the Object pointed to by "object" to a
353 * string representation and stores the result at "pString".
354 *
355 * PARAMETERS:
356 * "object"
357 * Object to get a string representation from. Must be non-NULL.
358 * "pString"
359 * Address where object pointer will be stored. Must be non-NULL.
360 * "plContext"
361 * Platform-specific context pointer.
362 * THREAD SAFETY:
363 * Thread Safe
364 *
365 * Multiple threads must be able to safely call this function without
366 * worrying about conflicts, even if they're operating on the same object.
367 * RETURNS:
368 * Returns NULL if the function succeeds.
369 * Returns an error if the function fails in a non-fatal way.
370 * Returns a Fatal Error if the function fails in an unrecoverable way.
371 */
372 typedef PKIX_Error *
373 (*PKIX_PL_ToStringCallback)(
374 PKIX_PL_Object *object,
375 PKIX_PL_String **pString,
376 void *plContext);
378 /*
379 * TYPE: PKIX_PL_ComparatorCallback
380 * DESCRIPTION:
381 *
382 * This callback function determines how the Object pointed to by
383 * "firstObject" compares to the Object pointed to by "secondObject" and
384 * stores the result at "pResult".
385 *
386 * Result is less than 0 if firstObject < secondObject
387 * Result equals 0 if firstObject = secondObject
388 * Result is greater than 0 if firstObject > secondObject
389 *
390 * PARAMETERS:
391 * "firstObject"
392 * Address of the first Object to compare. Must be non-NULL.
393 * "secondObject"
394 * Address of the second Object to compare. Must be non-NULL.
395 * "pResult"
396 * Address where PKIX_Int32 will be stored. Must be non-NULL.
397 * "plContext"
398 * Platform-specific context pointer.
399 * THREAD SAFETY:
400 * Thread Safe
401 *
402 * Multiple threads must be able to safely call this function without
403 * worrying about conflicts, even if they're operating on the same objects.
404 * RETURNS:
405 * Returns NULL if the function succeeds.
406 * Returns an 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 typedef PKIX_Error *
410 (*PKIX_PL_ComparatorCallback)(
411 PKIX_PL_Object *firstObject,
412 PKIX_PL_Object *secondObject,
413 PKIX_Int32 *pResult,
414 void *plContext);
416 /*
417 * TYPE: PKIX_PL_DuplicateCallback
418 * DESCRIPTION:
419 *
420 * This callback function creates a copy of the Object pointed to by "object"
421 * and stores it at "pNewObject". Changes to the copy will not affect the
422 * original and vice versa.
423 *
424 * Note that if "object" is immutable, the Duplicate callback function simply
425 * needs to increment the reference count on "object" and return a reference
426 * to "object".
427 *
428 * PARAMETERS:
429 * "object"
430 * Address of the object to be copied. Must be non-NULL.
431 * "pNewObject"
432 * Address where object pointer will be stored. Must be non-NULL.
433 * "plContext"
434 * Platform-specific context pointer.
435 * THREAD SAFETY:
436 * Thread Safe
437 *
438 * Multiple threads must be able to safely call this function without
439 * worrying about conflicts, even if they're operating on the same object.
440 * RETURNS:
441 * Returns NULL if the function succeeds.
442 * Returns an error if the function fails in a non-fatal way.
443 * Returns a Fatal Error if the function fails in an unrecoverable way.
444 */
445 typedef PKIX_Error *
446 (*PKIX_PL_DuplicateCallback)(
447 PKIX_PL_Object *object,
448 PKIX_PL_Object **pNewObject,
449 void *plContext);
451 /* reference-counted objects */
453 /*
454 * FUNCTION: PKIX_PL_Object_Alloc
455 * DESCRIPTION:
456 *
457 * Allocates a new Object of type "type" with "size" bytes and stores the
458 * resulting pointer at "pObject". The reference count of the newly
459 * allocated object will be initialized to 1. To improve performance, each
460 * object maintains a small cache for the results of Hashcode and ToString.
461 * Mutable objects should call InvalidateCache whenever changes are made to
462 * the object's state (after creation). If an error occurs during allocation,
463 * "pObject" will be set to NULL. If "size" equals zero, this function creates
464 * an Object with a reference count of 1, and places a pointer to unallocated
465 * memory at "pMemory".
466 *
467 * PARAMETERS:
468 * "type"
469 * The type code of this object. See pkixt.h for codes. The type code
470 * must be previously registered with PKIX_PL_Object_RegisterType().
471 * "size"
472 * The number of bytes needed for this object.
473 * "pMemory"
474 * Address where object pointer will be stored. Must be non-NULL.
475 * "plContext"
476 * Platform-specific context pointer.
477 * THREAD SAFETY:
478 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
479 * RETURNS:
480 * Returns NULL if the function succeeds.
481 * Returns a Fatal Error if the function fails in an unrecoverable way.
482 */
483 PKIX_Error *
484 PKIX_PL_Object_Alloc(
485 PKIX_TYPENUM type,
486 PKIX_UInt32 size,
487 PKIX_PL_Object **pObject,
488 void *plContext);
490 /*
491 * FUNCTION: PKIX_PL_Object_IsTypeRegistered
492 * DESCRIPTION:
493 *
494 * Checks whether "type" has been registered by a previous call to
495 * PKIX_PL_Object_RegisterType() and stores the Boolean result at "pBool".
496 * This function will typically only be called by constructors for specific
497 * types.
498 *
499 * PARAMETERS:
500 * "type"
501 * The type code to check if valid.
502 * "pBool"
503 * Address where Boolean will be stored. Must be non-NULL.
504 * "plContext"
505 * Platform-specific context pointer.
506 * THREAD SAFETY:
507 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
508 * RETURNS:
509 * Returns NULL if the function succeeds.
510 * Returns a Fatal Error if the function fails in an unrecoverable way.
511 */
512 PKIX_Error *
513 PKIX_PL_Object_IsTypeRegistered(
514 PKIX_UInt32 type,
515 PKIX_Boolean *pBool,
516 void *plContext);
518 #ifdef PKIX_USER_OBJECT_TYPE
519 /*
520 * FUNCTION: PKIX_PL_Object_RegisterType
521 * DESCRIPTION:
522 *
523 * Registers a new Object with type value "type" and associates it with a set
524 * of functions ("destructor", "equalsFunction", "hashcodeFunction",
525 * "toStringFunction", "comparator", "duplicateFunction"). The new type value
526 * is also associated with a string pointed to by "description", which is used
527 * by the default ToStringCallback. This function may only be called with a
528 * particular "type" value once. If "destructor", "equalsFunction",
529 * "hashcodeFunction", or "toStringFunction" are NULL, default functions will
530 * be registered. However, if "comparator" and "duplicateFunction" are NULL,
531 * no functions will be registered and calls to PKIX_PL_Object_Compare and
532 * PKIX_PL_Object_Duplicate will result in an error.
533 *
534 * PARAMETERS:
535 * "type"
536 * The type code.
537 * "description"
538 * The string used by the default ToStringCallback. Default used if NULL.
539 * "destructor"
540 * The DestructorCallback function to be set. Default used if NULL.
541 * "equalsFunction"
542 * The EqualsCallback function to be set. Default used if NULL.
543 * "hashcodeFunction"
544 * The HashcodeCallback function to be set. Default used if NULL.
545 * "toStringFunction"
546 * The ToStringCallback function to be set. Default used if NULL.
547 * "comparator"
548 * The ComparatorCallback function to be set. None set if NULL. If no
549 * callback function is set in this field, calls to
550 * PKIX_PL_Object_Compare() will result in an error.
551 * "duplicateFunction"
552 * The DuplicateCallback function to be set. None set if NULL. If no
553 * callback function is set in this field, calls to
554 * PKIX_PL_Object_Duplicate() will result in an error.
555 * "plContext"
556 * Platform-specific context pointer.
557 * THREAD SAFETY:
558 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
559 * RETURNS:
560 * Returns NULL if the function succeeds.
561 * Returns an Object Error if "type" is already registered.
562 * Returns a Fatal Error if the function fails in an unrecoverable way.
563 */
564 PKIX_Error *
565 PKIX_PL_Object_RegisterType(
566 PKIX_UInt32 type,
567 char *description,
568 PKIX_PL_DestructorCallback destructor,
569 PKIX_PL_EqualsCallback equalsFunction,
570 PKIX_PL_HashcodeCallback hashcodeFunction,
571 PKIX_PL_ToStringCallback toStringFunction,
572 PKIX_PL_ComparatorCallback comparator,
573 PKIX_PL_DuplicateCallback duplicateFunction,
574 void *plContext);
576 #endif
577 /*
578 * FUNCTION: PKIX_PL_Object_InvalidateCache
579 * DESCRIPTION:
580 *
581 * Invalidates the cache of the Object pointed to by "object". The cache
582 * contains results of Hashcode and ToString. This function should be used by
583 * mutable objects whenever changes are made to the Object's state (after
584 * creation).
585 *
586 * For example, if ToString is called on a mutable Object, the result will be
587 * computed, cached, and returned. If the Object's state does not change, a
588 * subsequent call to ToString will recognize that the relevant result is
589 * cached and will simply return the result (without calling the Object's
590 * ToStringCallback to recompute it). However, when the Object's state
591 * changes, the cache needs to be invalidated in order to force a subsequent
592 * call to ToString to recompute the result.
593 *
594 * PARAMETERS:
595 * "object"
596 * Address of Object whose cache is to be invalidated. Must be non-NULL.
597 * "plContext"
598 * Platform-specific context pointer.
599 *
600 * THREAD SAFETY
601 * Thread Safe - Object Type Table is locked during modification.
602 *
603 * Multiple threads can safely call this function without worrying about
604 * conflicts, even if they're operating on the same object.
605 * RETURNS:
606 * Returns NULL if the function succeeds.
607 * Returns a Fatal Error if the function fails in an unrecoverable way.
608 */
609 PKIX_Error *
610 PKIX_PL_Object_InvalidateCache(
611 PKIX_PL_Object *object,
612 void *plContext);
614 /*
615 * FUNCTION: PKIX_PL_Object_IncRef
616 * DESCRIPTION:
617 *
618 * Increments the reference count of the Object pointed to by "object".
619 *
620 * PARAMETERS:
621 * "object"
622 * Address of Object whose reference count is to be incremented.
623 * Must be non-NULL.
624 * "plContext"
625 * Platform-specific context pointer.
626 * THREAD SAFETY:
627 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
628 * RETURNS:
629 * Returns NULL if the function succeeds.
630 * Returns a Fatal Error if the function fails in an unrecoverable way.
631 */
632 PKIX_Error *
633 PKIX_PL_Object_IncRef(
634 PKIX_PL_Object *object,
635 void *plContext);
637 /*
638 * FUNCTION: PKIX_PL_Object_DecRef
639 * DESCRIPTION:
640 *
641 * Decrements the reference count of the Object pointed to by "object". If the
642 * resulting reference count is zero, the destructor (if any) registered for
643 * the Object's type (by PKIX_PL_RegisterType) will be called and then the
644 * Object will be destroyed.
645 *
646 * PARAMETERS:
647 * "object"
648 * Address of Object whose reference count is to be decremented.
649 * Must be non-NULL.
650 * "plContext"
651 * Platform-specific context pointer.
652 * THREAD SAFETY:
653 * If destructor is not called, multiple threads can safely call this function
654 * without worrying about conflicts, even if they're operating on the same
655 * object. If destructor is called, thread safety depends on the callback
656 * defined by PKIX_PL_RegisterType().
657 * RETURNS:
658 * Returns NULL if the function succeeds.
659 * Returns a Fatal Error if the function fails in an unrecoverable way.
660 */
661 PKIX_Error *
662 PKIX_PL_Object_DecRef(
663 PKIX_PL_Object *object,
664 void *plContext);
666 /*
667 * FUNCTION: PKIX_PL_Object_Equals
668 * DESCRIPTION:
669 *
670 * Compares the Object pointed to by "firstObject" with the Object pointed to
671 * by "secondObject" for equality using the callback function registered for
672 * "firstObject"'s type, and stores the Boolean result at "pResult". While
673 * typical callbacks will return PKIX_FALSE if the objects are of different
674 * types, other callbacks may be capable of comparing objects of different
675 * types [which may correctly result in cases where Equals(first, second)
676 * differs from Equals(second, first)].
677 *
678 * PARAMETERS:
679 * "firstObject"
680 * Address of the first Object to compare. Must be non-NULL.
681 * The EqualsCallback for this Object will be called.
682 * "secondObject"
683 * Address of the second Object to compare. Must be non-NULL.
684 * "pResult"
685 * Address where Boolean will be stored. Must be non-NULL.
686 * "plContext"
687 * Platform-specific context pointer.
688 * THREAD SAFETY:
689 * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
690 * RETURNS:
691 * Returns NULL if the function succeeds.
692 * Returns an Object Error if the function fails in a non-fatal way.
693 * Returns a Fatal Error if the function fails in an unrecoverable way.
694 */
695 PKIX_Error *
696 PKIX_PL_Object_Equals(
697 PKIX_PL_Object *firstObject,
698 PKIX_PL_Object *secondObject,
699 PKIX_Boolean *pResult,
700 void *plContext);
702 /*
703 * FUNCTION: PKIX_PL_Object_Hashcode
704 * DESCRIPTION:
705 *
706 * Computes a hashcode of the Object pointed to by "object" using the
707 * callback registered for "object"'s type and stores it at "pValue". Two
708 * objects which are equal should have the same hashcode. Once a call to
709 * Hashcode has been made, the results are cached and subsequent calls to
710 * Hashcode will return the cached value. For mutable objects, an
711 * InvalidateCache function is provided, which should be called whenever
712 * changes are made to the object's state (after creation).
713 *
714 * PARAMETERS:
715 * "object"
716 * Address of the Object whose hashcode is desired. Must be non-NULL.
717 * The HashcodeCallback for this object will be called.
718 * "pValue"
719 * Address where PKIX_Int32 will be stored. Must be non-NULL.
720 * "plContext"
721 * Platform-specific context pointer.
722 *
723 * THREAD SAFETY:
724 * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
725 * RETURNS:
726 * Returns NULL if the function succeeds.
727 * Returns an Object Error if the function fails in a non-fatal way.
728 * Returns a Fatal Error if the function fails in an unrecoverable way.
729 */
730 PKIX_Error *
731 PKIX_PL_Object_Hashcode(
732 PKIX_PL_Object *object,
733 PKIX_UInt32 *pValue,
734 void *plContext);
736 /*
737 * FUNCTION: PKIX_PL_Object_ToString
738 * DESCRIPTION:
739 *
740 * Creates a string representation of the Object pointed to by "object" using
741 * the callback registered for "object"'s type and stores it at "pString".
742 * Once a call to ToString has been made, the results are cached and
743 * subsequent calls to ToString will return the cached value. For mutable
744 * objects, an InvalidateCache function is provided, which should be called
745 * whenever changes are made to the object's state (after creation).
746 *
747 * PARAMETERS:
748 * "object"
749 * Address of Object whose string representation is desired.
750 * Must be non-NULL. The ToStringCallback for this object will be called.
751 * "pString"
752 * Address where object pointer will be stored. Must be non-NULL.
753 * "plContext"
754 * Platform-specific context pointer.
755 * THREAD SAFETY:
756 * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
757 * RETURNS:
758 * Returns NULL if the function succeeds.
759 * Returns an Object Error if the function fails in a non-fatal way.
760 * Returns a Fatal Error if the function fails in an unrecoverable way.
761 */
762 PKIX_Error *
763 PKIX_PL_Object_ToString(
764 PKIX_PL_Object *object,
765 PKIX_PL_String **pString,
766 void *plContext);
768 /*
769 * FUNCTION: PKIX_PL_Object_Compare
770 * DESCRIPTION:
771 *
772 * Compares the Object pointed to by "firstObject" and the Object pointed to
773 * by "secondObject" using the comparator registered for "firstObject"'s type
774 * and stores the result at "pResult". Different types may be compared. This
775 * may correctly result in cases where Compare(first, second) is not the
776 * opposite of Compare(second, first). The PKIX_Int32 value stored at
777 * "pResult" will be:
778 * Less than 0 if "firstObject" < "secondObject"
779 * Equals to 0 if "firstObject" = "secondObject"
780 * Greater than 0 if "firstObject" > "secondObject"
781 *
782 * PARAMETERS:
783 * "firstObject"
784 * Address of first Object to compare. Must be non-NULL.
785 * The ComparatorCallback for this object will be called.
786 * "secondObject"
787 * Address of second object to compare. Must be non-NULL.
788 * "pResult
789 * Address where PKIX_Int32 will be stored. Must be non-NULL.
790 * "plContext"
791 * Platform-specific context pointer.
792 * THREAD SAFETY:
793 * Thread safety depends on the comparator defined by PKIX_PL_RegisterType().
794 * RETURNS:
795 * Returns NULL if the function succeeds.
796 * Returns an Object Error if the function fails in a non-fatal way.
797 * Returns a Fatal Error if the function fails in an unrecoverable way.
798 */
799 PKIX_Error *
800 PKIX_PL_Object_Compare(
801 PKIX_PL_Object *firstObject,
802 PKIX_PL_Object *secondObject,
803 PKIX_Int32 *pResult,
804 void *plContext);
806 /*
807 * FUNCTION: PKIX_PL_Object_Duplicate
808 * DESCRIPTION:
809 *
810 * Creates a duplicate copy of the Object pointed to by "object" using the
811 * callback registered for "object"'s type and stores the copy at
812 * "pNewObject". Changes to the new object will not affect the original and
813 * vice versa.
814 *
815 * Note that if "object" is immutable, the Duplicate callback function simply
816 * needs to increment the reference count on "object" and return a reference
817 * to "object".
818 *
819 * PARAMETERS:
820 * "object"
821 * Address of Object to be duplicated. Must be non-NULL.
822 * The DuplicateCallback for this Object will be called.
823 * "pNewObject"
824 * Address where object pointer will be stored. Must be non-NULL.
825 * "plContext"
826 * Platform-specific context pointer.
827 * THREAD SAFETY:
828 * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
829 * RETURNS:
830 * Returns NULL if the function succeeds.
831 * Returns an Object Error if the function fails in a non-fatal way.
832 * Returns a Fatal Error if the function fails in an unrecoverable way.
833 */
834 PKIX_Error *
835 PKIX_PL_Object_Duplicate(
836 PKIX_PL_Object *object,
837 PKIX_PL_Object **pNewObject,
838 void *plContext);
840 /*
841 * FUNCTION: PKIX_PL_Object_GetType
842 * DESCRIPTION:
843 *
844 * Retrieves the type code of the Object pointed to by "object" and stores it
845 * at "pType". See pkixt.h for type codes.
846 *
847 * PARAMETERS:
848 * "object"
849 * Address of Object whose type is desired. Must be non-NULL.
850 * "pType"
851 * Address where PKIX_UInt32 will be stored. Must be non-NULL.
852 * "plContext"
853 * Platform-specific context pointer.
854 * THREAD SAFETY:
855 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
856 * RETURNS:
857 * Returns NULL if the function succeeds.
858 * Returns a Fatal Error if the function fails in an unrecoverable way.
859 */
860 PKIX_Error *
861 PKIX_PL_Object_GetType(
862 PKIX_PL_Object *object,
863 PKIX_UInt32 *pType,
864 void *plContext);
866 /*
867 * FUNCTION: PKIX_PL_Object_Lock
868 * DESCRIPTION:
869 *
870 * Locks the Mutex associated with the Object pointed to by "object". When an
871 * object is created, it is associated with an object-specific Mutex to allow
872 * for synchronization when the fields of the object are modified.
873 *
874 * PARAMETERS:
875 * "object"
876 * Address of Object whose Mutex is to be locked. Must be non-NULL.
877 * "plContext"
878 * Platform-specific context pointer.
879 * THREAD SAFETY:
880 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
881 * RETURNS:
882 * Returns NULL if the function succeeds.
883 * Returns a Fatal Error if the function fails in an unrecoverable way.
884 */
885 PKIX_Error *
886 PKIX_PL_Object_Lock(
887 PKIX_PL_Object *object,
888 void *plContext);
890 /*
891 * FUNCTION: PKIX_PL_Object_Unlock
892 * DESCRIPTION:
893 *
894 * Unlocks the Mutex associated with the Object pointed to by "object". When
895 * an object is created, it is associated with an object-specific Mutex to
896 * allow for synchronization when the fields of the object are modified.
897 *
898 * PARAMETERS:
899 * "object"
900 * Address of Object whose Mutex is to be unlocked. Must be non-NULL.
901 * "plContext"
902 * Platform-specific context pointer.
903 * THREAD SAFETY:
904 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
905 * RETURNS:
906 * Returns NULL if the function succeeds.
907 * Returns a Fatal Error if the function fails in an unrecoverable way.
908 */
909 PKIX_Error *
910 PKIX_PL_Object_Unlock(
911 PKIX_PL_Object *object,
912 void *plContext);
914 /* mutexes (locks) */
916 /*
917 * FUNCTION: PKIX_PL_Mutex_Create
918 * DESCRIPTION:
919 *
920 * Creates a new Mutex and stores it at "pNewLock".
921 *
922 * PARAMETERS:
923 * "pNewLock"
924 * Address where object pointer will be stored. Must be non-NULL.
925 * "plContext"
926 * Platform-specific context pointer.
927 * THREAD SAFETY:
928 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
929 * RETURNS:
930 * Returns NULL if the function succeeds.
931 * Returns a Fatal Error if the function fails in an unrecoverable way.
932 */
933 PKIX_Error *
934 PKIX_PL_Mutex_Create(
935 PKIX_PL_Mutex **pNewLock,
936 void *plContext);
938 /*
939 * FUNCTION: PKIX_PL_Mutex_Lock
940 * DESCRIPTION:
941 *
942 * Locks the Mutex pointed to by "lock". If the Mutex is already locked, this
943 * function will block the current thread until the mutex can be locked by
944 * this thread.
945 *
946 * PARAMETERS:
947 * "lock"
948 * Address of Mutex to lock. Must be non-NULL.
949 * "plContext"
950 * Platform-specific context pointer.
951 * THREAD SAFETY:
952 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
953 * RETURNS:
954 * Returns NULL if the function succeeds.
955 * Returns a Fatal Error if the function fails in an unrecoverable way.
956 */
957 PKIX_Error *
958 PKIX_PL_Mutex_Lock(
959 PKIX_PL_Mutex *lock,
960 void *plContext);
962 /*
963 * FUNCTION: PKIX_PL_Mutex_Unlock
964 * DESCRIPTION:
965 *
966 * Unlocks the Mutex pointed to by "lock" if the current thread holds the
967 * Mutex.
968 *
969 * PARAMETERS:
970 * "lock"
971 * Address of Mutex to unlock. Must be non-NULL.
972 * "plContext"
973 * Platform-specific context pointer.
974 * THREAD SAFETY:
975 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
976 * RETURNS:
977 * Returns NULL if the function succeeds.
978 * Returns a Fatal Error if the function fails in an unrecoverable way.
979 */
980 PKIX_Error *
981 PKIX_PL_Mutex_Unlock(
982 PKIX_PL_Mutex *lock,
983 void *plContext);
985 /* monitor (locks) */
987 /*
988 * FUNCTION: PKIX_PL_MonitorLock_Create
989 * DESCRIPTION:
990 *
991 * Creates a new PKIX_PL_MonitorLock and stores it at "pNewLock".
992 *
993 * PARAMETERS:
994 * "pNewLock"
995 * Address where object pointer will be stored. Must be non-NULL.
996 * "plContext"
997 * Platform-specific context pointer.
998 * THREAD SAFETY:
999 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1000 * RETURNS:
1001 * Returns NULL if the function succeeds.
1002 * Returns a Fatal Error if the function fails in an unrecoverable way.
1003 */
1004 PKIX_Error *
1005 PKIX_PL_MonitorLock_Create(
1006 PKIX_PL_MonitorLock **pNewLock,
1007 void *plContext);
1009 /*
1010 * FUNCTION: PKIX_PL_MonitorLock_Enter
1011 * DESCRIPTION:
1012 *
1013 * Locks the MonitorLock pointed to by "lock". If the MonitorLock is already
1014 * locked by other thread, this function will block the current thread. If
1015 * the "lock" had been locked by current thread, this function will NOT block.
1016 *
1017 * PARAMETERS:
1018 * "lock"
1019 * Address of MonitorLock to lock. Must be non-NULL.
1020 * "plContext"
1021 * Platform-specific context pointer.
1022 * THREAD SAFETY:
1023 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1024 * RETURNS:
1025 * Returns NULL if the function succeeds.
1026 * Returns a Fatal Error if the function fails in an unrecoverable way.
1027 */
1028 PKIX_Error *
1029 PKIX_PL_MonitorLock_Enter(
1030 PKIX_PL_MonitorLock *lock,
1031 void *plContext);
1033 /*
1034 * FUNCTION: PKIX_PL_MonitorLock_Exit
1035 * DESCRIPTION:
1036 *
1037 * Unlocks the MonitorLock pointed to by "lock" if the lock counter of
1038 * current thread holds the MonitorLock reach 0, the lock is released.
1039 *
1040 * PARAMETERS:
1041 * "lock"
1042 * Address of MonitorLock to unlock. Must be non-NULL.
1043 * "plContext"
1044 * Platform-specific context pointer.
1045 * THREAD SAFETY:
1046 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1047 * RETURNS:
1048 * Returns NULL if the function succeeds.
1049 * Returns a Fatal Error if the function fails in an unrecoverable way.
1050 */
1051 PKIX_Error *
1052 PKIX_PL_MonitorLock_Exit(
1053 PKIX_PL_MonitorLock *lock,
1054 void *plContext);
1056 /* strings and formatted printing */
1058 /*
1059 * FUNCTION: PKIX_PL_String_Create
1060 * DESCRIPTION:
1061 *
1062 * Creates a new String using the data pointed to by "pString", the
1063 * PKIX_UInt32 pointed to by "stringLen", and the PKIX_UInt32 pointed to by
1064 * "fmtIndicator" and stores it at "pString". If the format is PKIX_ESCASCII
1065 * the "stringLen" parameter is ignored and the string extends until a zero
1066 * byte is found. Once created, a String object is immutable.
1067 *
1068 * Valid formats are:
1069 * PKIX_ESCASCII
1070 * PKIX_ESCASCII_DEBUG
1071 * PKIX_UTF8
1072 * PKIX_UTF8_NULL_TERM
1073 * PKIX_UTF16
1074 *
1075 * PARAMETERS:
1076 * "fmtIndicator"
1077 * Format that "stringRep" is encoded with. Must be non-NULL.
1078 * "stringRep"
1079 * Address of encoded string representation. Must be non-NULL.
1080 * "stringLen"
1081 * Length of data stored at stringRep.
1082 * "pString"
1083 * Address where object pointer will be stored. Must be non-NULL.
1084 * "plContext"
1085 * Platform-specific context pointer.
1086 * THREAD SAFETY:
1087 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1088 * RETURNS:
1089 * Returns NULL if the function succeeds.
1090 * Returns a String Error if the function fails in a non-fatal way.
1091 * Returns a Fatal Error if the function fails in an unrecoverable way.
1092 */
1093 PKIX_Error *
1094 PKIX_PL_String_Create(
1095 PKIX_UInt32 fmtIndicator,
1096 const void *stringRep,
1097 PKIX_UInt32 stringLen,
1098 PKIX_PL_String **pString,
1099 void *plContext);
1101 /*
1102 * FUNCTION: PKIX_PL_Sprintf
1103 * DESCRIPTION:
1104 *
1105 * Creates a formatted string at "pOut" using the given format "fmt" and a
1106 * variable length list of arguments. The format flags are identical to
1107 * standard C with the exception that %s expects a PKIX_PL_String*, rather
1108 * than a char *, and that {%d, %i, %o, %u, %x, %X} expect PKIX_UInt32 or
1109 * PKIX_Int32 instead of int or unsigned int.
1110 *
1111 * PARAMETERS:
1112 * "pOut"
1113 * Address where object pointer will be stored. Must be non-NULL.
1114 * "plContext"
1115 * Platform-specific context pointer.
1116 * "fmt"
1117 * Address of format string. Must be non-NULL.
1118 * THREAD SAFETY:
1119 * Not Thread Safe - Caller must have exclusive access to all arguments.
1120 * (see Thread Safety Definitions in Programmer's Guide)
1121 * RETURNS:
1122 * Returns NULL if the function succeeds.
1123 * Returns a String Error if the function fails in a non-fatal way.
1124 * Returns a Fatal Error if the function fails in an unrecoverable way.
1125 */
1126 PKIX_Error *
1127 PKIX_PL_Sprintf(
1128 PKIX_PL_String **pOut,
1129 void *plContext,
1130 const PKIX_PL_String *fmt, ...);
1132 /*
1133 * FUNCTION: PKIX_PL_GetString
1134 * DESCRIPTION:
1135 *
1136 * Retrieves the String associated with the value of "stringID" (if any) and
1137 * stores it at "pString". If no such string is associated with "stringID",
1138 * this function uses "defaultString" to create a String and stores it at
1139 * "pString".
1140 *
1141 * PARAMETERS:
1142 * "stringID"
1143 * PKIX_UInt32 valud of string identifier.
1144 * "defaultString"
1145 * Address of a PKIX_ESCASCII encoded string representation.
1146 * Must be non-NULL.
1147 * "pString"
1148 * Address where object pointer will be stored. Must be non-NULL.
1149 * "plContext"
1150 * Platform-specific context pointer.
1151 * THREAD SAFETY:
1152 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1153 * RETURNS:
1154 * Returns NULL if the function succeeds.
1155 * Returns a String Error if the function fails in a non-fatal way.
1156 * Returns a Fatal Error if the function fails in an unrecoverable way.
1157 */
1158 PKIX_Error *
1159 PKIX_PL_GetString(
1160 PKIX_UInt32 stringID,
1161 char *defaultString,
1162 PKIX_PL_String **pString,
1163 void *plContext);
1165 /*
1166 * FUNCTION: PKIX_PL_String_GetEncoded
1167 * DESCRIPTION:
1168 *
1169 * Retrieves the value of the String pointed to by "string" in the encoding
1170 * specified by "fmtIndicator" and stores the result in "pStringRep" and
1171 * "pLength", respectively. Note that "pStringRep" is not reference counted
1172 * and will need to be freed with PKIX_PL_Free().
1173 *
1174 * PARAMETERS:
1175 * "string"
1176 * Address of String whose encoded value is desired. Must be non-NULL.
1177 * "fmtIndicator"
1178 * Format of encoding. Supported formats are:
1179 * PKIX_ESCASCII, PKIX_ESCASII_DEBUG, PKIX_UTF8, PKIX_UTF8_NULL_TERM, and
1180 * PKIX_UTF16. XXX Where are these documented?
1181 * "pStringRep"
1182 * Address where pointer to encoded value will be stored.
1183 * Must be non-NULL.
1184 * "pLength"
1185 * Address where byte length of encoded value will be stored.
1186 * "plContext"
1187 * Platform-specific context pointer.
1188 * THREAD SAFETY:
1189 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1190 * RETURNS:
1191 * Returns NULL if the function succeeds.
1192 * Returns a String Error if the function fails in a non-fatal way.
1193 * Returns a Fatal Error if the function fails in an unrecoverable way.
1194 */
1195 PKIX_Error *
1196 PKIX_PL_String_GetEncoded(
1197 PKIX_PL_String *string,
1198 PKIX_UInt32 fmtIndicator,
1199 void **pStringRep,
1200 PKIX_UInt32 *pLength,
1201 void *plContext);
1203 /*
1204 * Hashtable
1205 *
1206 * A hashtable is a very efficient data structure used for mapping keys to
1207 * values. Any non-null PKIX_PL_Object can be used as a key or as a value,
1208 * provided that it correctly implements the PKIX_PL_EqualsCallback and the
1209 * PKIX_PL_HashcodeCallback. A hashtable consists of several buckets, with
1210 * each bucket capable of holding a linked list of key/value mappings. When
1211 * adding, retrieving, or deleting a value, the hashcode of the key is used to
1212 * determine which bucket's linked list is relevant. The corresponding
1213 * key/value pair is then appended, retrieved, or deleted.
1214 */
1216 /*
1217 * FUNCTION: PKIX_PL_HashTable_Create
1218 * DESCRIPTION:
1219 *
1220 * Creates a new Hashtable with an initial capacity of "numBuckets" buckets
1221 * and "maxEntriesPerBucket" of entries limit for each bucket and stores it
1222 * at "pResult".
1223 *
1224 * PARAMETERS:
1225 * "numBuckets"
1226 * The initial number of hash table buckets. Must be non-zero.
1227 * "maxEntriesPerBucket"
1228 * The limit of entries per bucket. Zero means no limit.
1229 * "pResult"
1230 * Address where object pointer will be stored. Must be non-NULL.
1231 * "plContext"
1232 * Platform-specific context pointer.
1233 * THREAD SAFETY:
1234 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1235 * RETURNS:
1236 * Returns NULL if the function succeeds.
1237 * Returns a Fatal Error if the function fails in an unrecoverable way.
1238 */
1239 PKIX_Error *
1240 PKIX_PL_HashTable_Create(
1241 PKIX_UInt32 numBuckets,
1242 PKIX_UInt32 maxEntriesPerBucket,
1243 PKIX_PL_HashTable **pResult,
1244 void *plContext);
1246 /*
1247 * FUNCTION: PKIX_PL_HashTable_Add
1248 * DESCRIPTION:
1249 *
1250 * Adds a key/value mapping using the Objects pointed to by "key" and "value"
1251 * to the Hashtable pointed to by "ht".
1252 *
1253 * Function increments key/value reference counts. Caller is responsible to
1254 * to decrement(destroy) key/value ref counts(objects).
1255 *
1256 * PARAMETERS:
1257 * "ht"
1258 * Address of Hashtable to be added to. Must be non-NULL.
1259 * "key"
1260 * Address of Object to be associated with "value". Must be non-NULL.
1261 * "value"
1262 * Address of Object to be added to Hashtable. Must be non-NULL.
1263 * "plContext"
1264 * Platform-specific context pointer.
1265 * THREAD SAFETY:
1266 * Not Thread Safe - assumes exclusive access to "ht"
1267 * (see Thread Safety Definitions in Programmer's Guide)
1268 * RETURNS:
1269 * Returns NULL if the function succeeds.
1270 * Returns a Hashtable Error if the function fails in a non-fatal way.
1271 * Returns a Fatal Error if the function fails in an unrecoverable way.
1272 */
1273 PKIX_Error *
1274 PKIX_PL_HashTable_Add(
1275 PKIX_PL_HashTable *ht,
1276 PKIX_PL_Object *key,
1277 PKIX_PL_Object *value,
1278 void *plContext);
1280 /*
1281 * FUNCTION: PKIX_PL_HashTable_Remove
1282 * DESCRIPTION:
1283 *
1284 * Removes the Object value whose key is equal to the Object pointed to by
1285 * "key" from the Hashtable pointed to by "ht". If no such object exists,
1286 * this function throws an Error.
1287 *
1288 * Function frees "value" object. Caller is responsible to free "key"
1289 * object.
1290 *
1291 * PARAMETERS:
1292 * "ht"
1293 * Address of Hashtable to remove object from. Must be non-NULL.
1294 * "key"
1295 * Address of Object used for lookup. Must be non-NULL.
1296 * "plContext"
1297 * Platform-specific context pointer.
1298 * THREAD SAFETY:
1299 * Not Thread Safe - assumes exclusive access to "ht"
1300 * (see Thread Safety Definitions in Programmer's Guide)
1301 * RETURNS:
1302 * Returns NULL if the function succeeds.
1303 * Returns a Hashtable Error if the function fails in a non-fatal way.
1304 * Returns a Fatal Error if the function fails in an unrecoverable way.
1305 */
1306 PKIX_Error *
1307 PKIX_PL_HashTable_Remove(
1308 PKIX_PL_HashTable *ht,
1309 PKIX_PL_Object *key,
1310 void *plContext);
1312 /*
1313 * FUNCTION: PKIX_PL_HashTable_Lookup
1314 * DESCRIPTION:
1315 *
1316 * Retrieves the Object whose key equals the Object pointed to by "key" from
1317 * the Hashtable associated with "ht" and stores it at "pResult". If no
1318 * Object is found, this function stores NULL at "pResult".
1319 *
1320 * PARAMETERS:
1321 * "ht"
1322 * Address of Hashtable to lookup Object from. Must be non-NULL.
1323 * "key"
1324 * Address of key Object used for lookup. Must be non-NULL.
1325 * "pResult"
1326 * Address where object pointer will be stored. Must be non-NULL.
1327 * "plContext"
1328 * Platform-specific context pointer.
1329 * THREAD SAFETY:
1330 * Conditionally Thread Safe
1331 * (see Thread Safety Definitions in Programmer's Guide)
1332 * RETURNS:
1333 * Returns NULL if the function succeeds.
1334 * Returns a Hashtable Error if the function fails in a non-fatal way.
1335 * Returns a Fatal Error if the function fails in an unrecoverable way.
1336 */
1337 PKIX_Error *
1338 PKIX_PL_HashTable_Lookup(
1339 PKIX_PL_HashTable *ht,
1340 PKIX_PL_Object *key,
1341 PKIX_PL_Object **pResult,
1342 void *plContext);
1344 /*
1345 * FUNCTION: PKIX_PL_ByteArray_Create
1346 * DESCRIPTION:
1347 *
1348 * Creates a new ByteArray using "length" bytes of data pointed to by "array"
1349 * and stores it at "pByteArray". Once created, a ByteArray is immutable.
1350 *
1351 * PARAMETERS:
1352 * "array"
1353 * Address of source data.
1354 * "length"
1355 * Number of bytes to copy.
1356 * "pByteArray"
1357 * Address where object pointer will be stored. Must be non-NULL.
1358 * "plContext"
1359 * Platform-specific context pointer.
1360 * THREAD SAFETY:
1361 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1362 * RETURNS:
1363 * Returns NULL if the function succeeds.
1364 * Returns a Fatal Error if the function fails in an unrecoverable way.
1365 */
1366 PKIX_Error *
1367 PKIX_PL_ByteArray_Create(
1368 void *array,
1369 PKIX_UInt32 length,
1370 PKIX_PL_ByteArray **pByteArray,
1371 void *plContext);
1373 /*
1374 * FUNCTION: PKIX_PL_ByteArray_GetPointer
1375 * DESCRIPTION:
1376 *
1377 * Allocates enough memory to hold the contents of the ByteArray pointed to
1378 * by "byteArray", copies the data from the ByteArray pointed to by
1379 * "byteArray" into the newly allocated memory, and stores a pointer to the
1380 * memory at "pArray". Note that "pArray" is not reference counted. It will
1381 * need to be freed with PKIX_PL_Free().
1382 *
1383 * PARAMETERS:
1384 * "byteArray"
1385 * Address of ByteArray whose data is desired. Must be non-NULL.
1386 * "pArray"
1387 * Address where object pointer will be stored. Must be non-NULL.
1388 * "plContext"
1389 * Platform-specific context pointer.
1390 * THREAD SAFETY:
1391 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1392 * RETURNS:
1393 * Returns NULL if the function succeeds.
1394 * Returns a Fatal Error if the function fails in an unrecoverable way.
1395 */
1396 PKIX_Error *
1397 PKIX_PL_ByteArray_GetPointer(
1398 PKIX_PL_ByteArray *byteArray,
1399 void **pArray,
1400 void *plContext);
1402 /*
1403 * FUNCTION: PKIX_PL_ByteArray_GetLength
1404 * DESCRIPTION:
1405 *
1406 * Retrieves the length of the ByteArray pointed to by "byteArray" and stores
1407 * the length at "pLength".
1408 *
1409 * PARAMETERS:
1410 * "byteArray"
1411 * Address of ByteArray whose length is desired. Must be non-NULL.
1412 * "pLength"
1413 * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1414 * "plContext"
1415 * Platform-specific context pointer.
1416 * THREAD SAFETY:
1417 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1418 * RETURNS:
1419 * Returns NULL if the function succeeds.
1420 * Returns a Fatal Error if the function fails in an unrecoverable way.
1421 */
1422 PKIX_Error *
1423 PKIX_PL_ByteArray_GetLength(
1424 PKIX_PL_ByteArray *byteArray,
1425 PKIX_UInt32 *pLength,
1426 void *plContext);
1428 /*
1429 * FUNCTION: PKIX_PL_OID_Create
1430 * DESCRIPTION:
1431 *
1432 * Creates a new OID using NSS oid tag.
1433 *
1434 * PARAMETERS:
1435 * "idtag"
1436 * nss oid id tag.
1437 * "pOID"
1438 * Address where object pointer will be stored. Must be non-NULL.
1439 * "plContext"
1440 * Platform-specific context pointer.
1441 * THREAD SAFETY:
1442 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1443 * RETURNS:
1444 * Returns NULL if the function succeeds.
1445 * Returns an OID Error if the function fails in a non-fatal way.
1446 * Returns a Fatal Error if the function fails in an unrecoverable way.
1447 */
1448 PKIX_Error *
1449 PKIX_PL_OID_Create(
1450 SECOidTag idtag,
1451 PKIX_PL_OID **pOID,
1452 void *plContext);
1454 /*
1455 * FUNCTION: PKIX_PL_OID_CreateBySECItem
1456 * DESCRIPTION:
1457 *
1458 * Creates a new OID using a DER encoded OID stored as SECItem.
1459 *
1460 * PARAMETERS:
1461 * "derOid"
1462 * Address of SECItem that holds DER encoded OID.
1463 * "pOID"
1464 * Address where object pointer will be stored. Must be non-NULL.
1465 * "plContext"
1466 * Platform-specific context pointer.
1467 * THREAD SAFETY:
1468 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1469 * RETURNS:
1470 * Returns NULL if the function succeeds.
1471 * Returns an OID Error if the function fails in a non-fatal way.
1472 * Returns a Fatal Error if the function fails in an unrecoverable way.
1473 */
1474 PKIX_Error *
1475 PKIX_PL_OID_CreateBySECItem(
1476 SECItem *derOid,
1477 PKIX_PL_OID **pOID,
1478 void *plContext);
1480 /*
1481 * FUNCTION: PKIX_PL_BigInt_Create
1482 * DESCRIPTION:
1483 *
1484 * Creates a new BigInt using the source String pointed to by "stringRep" and
1485 * stores it at "pBigInt". Valid source Strings consist of an even number of
1486 * hexadecimal digits, which are always interpreted as a positive number.
1487 * Once created, a BigInt is immutable.
1488 *
1489 * The regexp format is:
1490 * HexDigit ::= [0-9] | [A-F] | [a-f]
1491 * DoubleHex ::= HexDigit HexDigit
1492 * BigIntSrc ::= (DoubleHex)+
1493 *
1494 * Note that since we are using DoubleHex, the number of characters in the
1495 * source MUST be even. Additionally, the first DoubleHex MUST NOT be "00"
1496 * unless it is the only DoubleHex.
1497 *
1498 * Valid : "09"
1499 * Valid : "00" (special case where first and only DoubleHex is "00")
1500 * Invalid: "9" (not DoubleHex: odd number of characters)
1501 * Invalid: "0009" (first DoubleHex is "00")
1502 *
1503 * XXX Why does this take a String object while OID_Create takes a char* ?
1504 * Perhaps because OID_Create is often used with constant strings and
1505 * this function isn't. That's a good reason, but we should explain it
1506 * (if it's right)
1507 * PARAMETERS:
1508 * "stringRep"
1509 * Address of String representing a BigInt. Must be non-NULL.
1510 * "pBigInt"
1511 * Address where object pointer will be stored. Must be non-NULL.
1512 * "plContext"
1513 * Platform-specific context pointer.
1514 * THREAD SAFETY:
1515 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1516 * RETURNS:
1517 * Returns NULL if the function succeeds.
1518 * Returns a BigInt Error if the function fails in a non-fatal way.
1519 * Returns a Fatal Error if the function fails in an unrecoverable way.
1520 */
1521 PKIX_Error *
1522 PKIX_PL_BigInt_Create(
1523 PKIX_PL_String *stringRep,
1524 PKIX_PL_BigInt **pBigInt,
1525 void *plContext);
1527 #ifdef __cplusplus
1528 }
1529 #endif
1531 /*
1532 * FUNCTION: PKIX_PL_GetPLErrorCode
1533 * DESCRIPTION:
1534 *
1535 * Returns error code from PL layer.
1536 *
1537 * THREAD SAFETY:
1538 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1539 * RETURNS:
1540 * PL layer error code.
1541 */
1542 int
1543 PKIX_PL_GetPLErrorCode();
1545 #endif /* _LIBPKIX_SYSTEM_H */
