1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_pl_system.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1545 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines several platform independent functions to make system
1.9 + * calls in a portable manner.
1.10 + *
1.11 + */
1.12 +
1.13 +#ifndef _PKIX_PL_SYSTEM_H
1.14 +#define _PKIX_PL_SYSTEM_H
1.15 +
1.16 +#include "pkixt.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +/* General
1.23 + *
1.24 + * Please refer to the libpkix Programmer's Guide for detailed information
1.25 + * about how to use the libpkix library. Certain key warnings and notices from
1.26 + * that document are repeated here for emphasis.
1.27 + *
1.28 + * All identifiers in this file (and all public identifiers defined in
1.29 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.30 + * within the library begin with "pkix_".
1.31 + *
1.32 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.33 + *
1.34 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.35 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.36 + * shared object. Therefore, the caller should treat this shared object as
1.37 + * read-only and should not modify this shared object. When done using the
1.38 + * shared object, the caller should release the reference to the object by
1.39 + * using the PKIX_PL_Object_DecRef function.
1.40 + *
1.41 + * While a function is executing, if its arguments (or anything referred to by
1.42 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.43 + * is undefined.
1.44 + *
1.45 + */
1.46 +
1.47 +/*
1.48 + * FUNCTION: PKIX_PL_Initialize
1.49 + * DESCRIPTION:
1.50 + *
1.51 + * XXX If this function is really only meant to be used by PKIX_Initialize,
1.52 + * why don't we just put it in a private header file rather than the public
1.53 + * API. I think it may confuse users.
1.54 + *
1.55 + * This function should NOT be called by applications. It is only meant to
1.56 + * be used internally. The application needs only to call PKIX_Initialize,
1.57 + * which in turn will call this function.
1.58 + *
1.59 + * This function initializes data structures critical to the operation of
1.60 + * libpkix. If initialization is not successful, an Error pointer is
1.61 + * returned. This function should only be called once. If it is called more
1.62 + * than once, the behavior is undefined.
1.63 + *
1.64 + * No PKIX_* types and functions should be used before this function is
1.65 + * called and returns successfully.
1.66 + *
1.67 + * PARAMETERS:
1.68 + * "platformInitNeeded"
1.69 + * Boolean indicating whether platform initialization is to be called
1.70 + * "useArenas"
1.71 + * Boolean indicating whether allocation is to be done using arenas or
1.72 + * individual allocation (malloc).
1.73 + * "pPlContext"
1.74 + * Address at which platform-specific context pointer is stored. Must be
1.75 + * non-NULL.
1.76 + * THREAD SAFETY:
1.77 + * Not Thread Safe
1.78 + *
1.79 + * This function assumes that no other thread is calling this function while
1.80 + * it is executing.
1.81 + * RETURNS:
1.82 + * Returns NULL if the function succeeds.
1.83 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.84 + */
1.85 +PKIX_Error *
1.86 +PKIX_PL_Initialize(
1.87 + PKIX_Boolean platformInitNeeded,
1.88 + PKIX_Boolean useArenas,
1.89 + void **pPlContext);
1.90 +
1.91 +/*
1.92 + * FUNCTION: PKIX_PL_Shutdown
1.93 + * DESCRIPTION:
1.94 + *
1.95 + * XXX If this function is really only meant to be used by PKIX_Shutdown,
1.96 + * why don't we just put it in a private header file rather than the public
1.97 + * API. I think it may confuse users.
1.98 + *
1.99 + * This function should NOT be called by applications. It is only meant to
1.100 + * be used internally. The application needs only to call PKIX_Shutdown,
1.101 + * which in turn will call this function.
1.102 + *
1.103 + * This function deallocates any memory used by the Portability Layer (PL)
1.104 + * component of the libpkix library and shuts down any ongoing operations.
1.105 + * This function should only be called once. If it is called more than once,
1.106 + * the behavior is undefined.
1.107 + *
1.108 + * No PKIX_* types and functions should be used after this function is called
1.109 + * and returns successfully.
1.110 + *
1.111 + * PARAMETERS:
1.112 + * "platformInitNeeded"
1.113 + * Boolean value of whether PKIX initialized NSS: PKIX_TRUE if we
1.114 + * called nssInit, PKIX_FALSE otherwise
1.115 + * "plContext"
1.116 + * Platform-specific context pointer.
1.117 + * THREAD SAFETY:
1.118 + * Not Thread Safe
1.119 + *
1.120 + * This function makes use of global variables and should only be called once.
1.121 + * RETURNS:
1.122 + * Returns NULL if the function succeeds.
1.123 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.124 + */
1.125 +PKIX_Error *
1.126 +PKIX_PL_Shutdown(void *plContext);
1.127 +
1.128 +/* standard memory management operations (not reference-counted) */
1.129 +
1.130 +/*
1.131 + * FUNCTION: PKIX_PL_Malloc
1.132 + * DESCRIPTION:
1.133 + *
1.134 + * Allocates a block of "size" bytes. The bytes are not initialized. A
1.135 + * pointer to the newly allocated memory will be stored at "pMemory". The
1.136 + * memory allocated by PKIX_PL_Malloc() may only be freed by PKIX_PL_Free().
1.137 + * If "size" equals zero, this function stores NULL at "pMemory".
1.138 + *
1.139 + * PARAMETERS:
1.140 + * "size"
1.141 + * Number of bytes to allocate.
1.142 + * "pMemory"
1.143 + * Address where newly allocated pointer will be stored. Must be non-NULL.
1.144 + * "plContext"
1.145 + * Platform-specific context pointer.
1.146 + * THREAD SAFETY:
1.147 + * Thread safety depends on underlying thread safety of platform used by PL.
1.148 + * RETURNS:
1.149 + * Returns NULL if the function succeeds.
1.150 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.151 + */
1.152 +PKIX_Error *
1.153 +PKIX_PL_Malloc(
1.154 + PKIX_UInt32 size,
1.155 + void **pMemory,
1.156 + void *plContext);
1.157 +
1.158 +/*
1.159 + * FUNCTION: PKIX_PL_Calloc
1.160 + * DESCRIPTION:
1.161 + *
1.162 + * Allocates memory for an array of "nElem" elements, with each element
1.163 + * requiring "elSize" bytes, and with all the bits initialized to zero. A
1.164 + * pointer to the newly allocated memory will be stored at "pMemory". The
1.165 + * memory allocated by PKIX_PL_Calloc() may only be freed by PKIX_PL_Free().
1.166 + * If "nElem" equals zero or "elSize" equals zero, this function stores NULL
1.167 + * at "pMemory".
1.168 + *
1.169 + * PARAMETERS:
1.170 + * "nElem"
1.171 + * Number of elements needed.
1.172 + * "elSize"
1.173 + * Number of bytes needed per element.
1.174 + * "pMemory"
1.175 + * Address where newly allocated pointer will be stored. Must be non-NULL.
1.176 + * "plContext"
1.177 + * Platform-specific context pointer.
1.178 + * THREAD SAFETY:
1.179 + * Thread safety depends on underlying thread safety of platform used by PL.
1.180 + * RETURNS:
1.181 + * Returns NULL if the function succeeds.
1.182 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.183 + */
1.184 +PKIX_Error *
1.185 +PKIX_PL_Calloc(
1.186 + PKIX_UInt32 nElem,
1.187 + PKIX_UInt32 elSize,
1.188 + void **pMemory,
1.189 + void *plContext);
1.190 +
1.191 +/*
1.192 + * FUNCTION: PKIX_PL_Realloc
1.193 + * DESCRIPTION:
1.194 + *
1.195 + * Resizes an existing block of memory (pointed to by "ptr") to "size" bytes.
1.196 + * Stores a pointer to the resized memory at "pNewPtr". The "ptr" must
1.197 + * originate from either PKIX_PL_Malloc(), PKIX_PL_Realloc(), or
1.198 + * PKIX_PL_Calloc(). If "ptr" is NULL, this function behaves as if
1.199 + * PKIX_PL_Malloc were called. If "ptr" is not NULL and "size" equals zero,
1.200 + * the memory pointed to by "ptr" is deallocated and this function stores
1.201 + * NULL at "pPtr".
1.202 + *
1.203 + * PARAMETERS:
1.204 + * "ptr"
1.205 + * A pointer to an existing block of memory.
1.206 + * "size"
1.207 + * New size in bytes.
1.208 + * "pPtr"
1.209 + * Address where newly allocated pointer will be stored. Must be non-NULL.
1.210 + * "plContext"
1.211 + * Platform-specific context pointer.
1.212 + * THREAD SAFETY:
1.213 + * Thread safety depends on underlying thread safety of platform used by PL.
1.214 + * RETURNS:
1.215 + * Returns NULL if the function succeeds.
1.216 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.217 + */
1.218 +PKIX_Error *
1.219 +PKIX_PL_Realloc(
1.220 + void *ptr,
1.221 + PKIX_UInt32 size,
1.222 + void **pNewPtr,
1.223 + void *plContext);
1.224 +
1.225 +/*
1.226 + * FUNCTION: PKIX_PL_Free
1.227 + * DESCRIPTION:
1.228 + *
1.229 + * Frees a block of memory pointed to by "ptr". This value must originate with
1.230 + * either PKIX_PL_Malloc(), PKIX_PL_Calloc, or PKIX_PL_Realloc(). If "ptr" is
1.231 + * NULL, the function has no effect.
1.232 + *
1.233 + * PARAMETERS:
1.234 + * "ptr"
1.235 + * A pointer to an existing block of memory.
1.236 + * "plContext"
1.237 + * Platform-specific context pointer.
1.238 + * THREAD SAFETY:
1.239 + * Thread safety depends on underlying thread safety of platform used by PL.
1.240 + * RETURNS:
1.241 + * Returns NULL always.
1.242 + */
1.243 +PKIX_Error *
1.244 +PKIX_PL_Free(
1.245 + void *ptr,
1.246 + void *plContext);
1.247 +
1.248 +/* Callback Types
1.249 + *
1.250 + * The next few typedefs define function pointer types for the standard
1.251 + * functions associated with every object type. See the Implementation
1.252 + * Guidelines or the comments below for more information.
1.253 + */
1.254 +
1.255 +/*
1.256 + * TYPE: PKIX_PL_DestructorCallback
1.257 + * DESCRIPTION:
1.258 + *
1.259 + * This callback function destroys (or DecRef's) any pointers contained in
1.260 + * the user data for the Object pointed to by "object" before the Object is
1.261 + * destroyed.
1.262 + *
1.263 + * PARAMETERS:
1.264 + * "object"
1.265 + * Address of Object to destroy. Must be non-NULL.
1.266 + * "plContext"
1.267 + * Platform-specific context pointer.
1.268 + * THREAD SAFETY:
1.269 + * Thread Safe
1.270 + *
1.271 + * Multiple threads must be able to safely call this function without
1.272 + * worrying about conflicts (as long as they're not operating on the same
1.273 + * object and nobody else is performing an operation on the object at the
1.274 + * same time). Both of these conditions should be guaranteed by the fact that
1.275 + * the object's ref count was reduced to 0 in a lock that's still held when
1.276 + * this callback is called.
1.277 + * RETURNS:
1.278 + * Returns NULL if the function succeeds.
1.279 + * Returns an error if the function fails in a non-fatal way.
1.280 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.281 + */
1.282 +typedef PKIX_Error *
1.283 +(*PKIX_PL_DestructorCallback)(
1.284 + PKIX_PL_Object *object,
1.285 + void *plContext);
1.286 +
1.287 +/*
1.288 + * TYPE: PKIX_PL_EqualsCallback
1.289 + * DESCRIPTION:
1.290 + *
1.291 + * This callback function compares the Object pointed to by "firstObject" with
1.292 + * the Object pointed to by "secondObject" for equality and stores the result
1.293 + * at "pResult" (PKIX_TRUE if equal; PKIX_FALSE if not).
1.294 + *
1.295 + * PARAMETERS:
1.296 + * "firstObject"
1.297 + * Address of first object to compare. Must be non-NULL.
1.298 + * "secondObject"
1.299 + * Address of second object to compare. Must be non-NULL.
1.300 + * "pResult"
1.301 + * Address where Boolean will be stored. Must be non-NULL.
1.302 + * "plContext"
1.303 + * Platform-specific context pointer.
1.304 + * THREAD SAFETY:
1.305 + * Thread Safe
1.306 + *
1.307 + * Multiple threads must be able to safely call this function without
1.308 + * worrying about conflicts, even if they're operating on the same objects.
1.309 + * RETURNS:
1.310 + * Returns NULL if the function succeeds.
1.311 + * Returns an error if the function fails in a non-fatal way.
1.312 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.313 + */
1.314 +typedef PKIX_Error *
1.315 +(*PKIX_PL_EqualsCallback)(
1.316 + PKIX_PL_Object *firstObject,
1.317 + PKIX_PL_Object *secondObject,
1.318 + PKIX_Boolean *pResult,
1.319 + void *plContext);
1.320 +
1.321 +/*
1.322 + * TYPE: PKIX_PL_HashcodeCallback
1.323 + * DESCRIPTION:
1.324 + *
1.325 + * This callback function computes the hashcode of the Object pointed to by
1.326 + * "object" and stores the result at "pValue".
1.327 + *
1.328 + * PARAMETERS:
1.329 + * "object"
1.330 + * Address of Object whose hashcode is desired. Must be non-NULL.
1.331 + * "pValue"
1.332 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.333 + * "plContext"
1.334 + * Platform-specific context pointer.
1.335 + * THREAD SAFETY:
1.336 + * Thread Safe
1.337 + *
1.338 + * Multiple threads must be able to safely call this function without
1.339 + * worrying about conflicts, even if they're operating on the same object.
1.340 + * RETURNS:
1.341 + * Returns NULL if the function succeeds.
1.342 + * Returns an error if the function fails in a non-fatal way.
1.343 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.344 + */
1.345 +typedef PKIX_Error *
1.346 +(*PKIX_PL_HashcodeCallback)(
1.347 + PKIX_PL_Object *object,
1.348 + PKIX_UInt32 *pValue,
1.349 + void *plContext);
1.350 +
1.351 +/*
1.352 + * TYPE: PKIX_PL_ToStringCallback
1.353 + * DESCRIPTION:
1.354 + *
1.355 + * This callback function converts the Object pointed to by "object" to a
1.356 + * string representation and stores the result at "pString".
1.357 + *
1.358 + * PARAMETERS:
1.359 + * "object"
1.360 + * Object to get a string representation from. Must be non-NULL.
1.361 + * "pString"
1.362 + * Address where object pointer will be stored. Must be non-NULL.
1.363 + * "plContext"
1.364 + * Platform-specific context pointer.
1.365 + * THREAD SAFETY:
1.366 + * Thread Safe
1.367 + *
1.368 + * Multiple threads must be able to safely call this function without
1.369 + * worrying about conflicts, even if they're operating on the same object.
1.370 + * RETURNS:
1.371 + * Returns NULL if the function succeeds.
1.372 + * Returns an error if the function fails in a non-fatal way.
1.373 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.374 + */
1.375 +typedef PKIX_Error *
1.376 +(*PKIX_PL_ToStringCallback)(
1.377 + PKIX_PL_Object *object,
1.378 + PKIX_PL_String **pString,
1.379 + void *plContext);
1.380 +
1.381 +/*
1.382 + * TYPE: PKIX_PL_ComparatorCallback
1.383 + * DESCRIPTION:
1.384 + *
1.385 + * This callback function determines how the Object pointed to by
1.386 + * "firstObject" compares to the Object pointed to by "secondObject" and
1.387 + * stores the result at "pResult".
1.388 + *
1.389 + * Result is less than 0 if firstObject < secondObject
1.390 + * Result equals 0 if firstObject = secondObject
1.391 + * Result is greater than 0 if firstObject > secondObject
1.392 + *
1.393 + * PARAMETERS:
1.394 + * "firstObject"
1.395 + * Address of the first Object to compare. Must be non-NULL.
1.396 + * "secondObject"
1.397 + * Address of the second Object to compare. Must be non-NULL.
1.398 + * "pResult"
1.399 + * Address where PKIX_Int32 will be stored. Must be non-NULL.
1.400 + * "plContext"
1.401 + * Platform-specific context pointer.
1.402 + * THREAD SAFETY:
1.403 + * Thread Safe
1.404 + *
1.405 + * Multiple threads must be able to safely call this function without
1.406 + * worrying about conflicts, even if they're operating on the same objects.
1.407 + * RETURNS:
1.408 + * Returns NULL if the function succeeds.
1.409 + * Returns an error if the function fails in a non-fatal way.
1.410 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.411 + */
1.412 +typedef PKIX_Error *
1.413 +(*PKIX_PL_ComparatorCallback)(
1.414 + PKIX_PL_Object *firstObject,
1.415 + PKIX_PL_Object *secondObject,
1.416 + PKIX_Int32 *pResult,
1.417 + void *plContext);
1.418 +
1.419 +/*
1.420 + * TYPE: PKIX_PL_DuplicateCallback
1.421 + * DESCRIPTION:
1.422 + *
1.423 + * This callback function creates a copy of the Object pointed to by "object"
1.424 + * and stores it at "pNewObject". Changes to the copy will not affect the
1.425 + * original and vice versa.
1.426 + *
1.427 + * Note that if "object" is immutable, the Duplicate callback function simply
1.428 + * needs to increment the reference count on "object" and return a reference
1.429 + * to "object".
1.430 + *
1.431 + * PARAMETERS:
1.432 + * "object"
1.433 + * Address of the object to be copied. Must be non-NULL.
1.434 + * "pNewObject"
1.435 + * Address where object pointer will be stored. Must be non-NULL.
1.436 + * "plContext"
1.437 + * Platform-specific context pointer.
1.438 + * THREAD SAFETY:
1.439 + * Thread Safe
1.440 + *
1.441 + * Multiple threads must be able to safely call this function without
1.442 + * worrying about conflicts, even if they're operating on the same object.
1.443 + * RETURNS:
1.444 + * Returns NULL if the function succeeds.
1.445 + * Returns an error if the function fails in a non-fatal way.
1.446 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.447 + */
1.448 +typedef PKIX_Error *
1.449 +(*PKIX_PL_DuplicateCallback)(
1.450 + PKIX_PL_Object *object,
1.451 + PKIX_PL_Object **pNewObject,
1.452 + void *plContext);
1.453 +
1.454 +/* reference-counted objects */
1.455 +
1.456 +/*
1.457 + * FUNCTION: PKIX_PL_Object_Alloc
1.458 + * DESCRIPTION:
1.459 + *
1.460 + * Allocates a new Object of type "type" with "size" bytes and stores the
1.461 + * resulting pointer at "pObject". The reference count of the newly
1.462 + * allocated object will be initialized to 1. To improve performance, each
1.463 + * object maintains a small cache for the results of Hashcode and ToString.
1.464 + * Mutable objects should call InvalidateCache whenever changes are made to
1.465 + * the object's state (after creation). If an error occurs during allocation,
1.466 + * "pObject" will be set to NULL. If "size" equals zero, this function creates
1.467 + * an Object with a reference count of 1, and places a pointer to unallocated
1.468 + * memory at "pMemory".
1.469 + *
1.470 + * PARAMETERS:
1.471 + * "type"
1.472 + * The type code of this object. See pkixt.h for codes. The type code
1.473 + * must be previously registered with PKIX_PL_Object_RegisterType().
1.474 + * "size"
1.475 + * The number of bytes needed for this object.
1.476 + * "pMemory"
1.477 + * Address where object pointer will be stored. Must be non-NULL.
1.478 + * "plContext"
1.479 + * Platform-specific context pointer.
1.480 + * THREAD SAFETY:
1.481 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.482 + * RETURNS:
1.483 + * Returns NULL if the function succeeds.
1.484 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.485 + */
1.486 +PKIX_Error *
1.487 +PKIX_PL_Object_Alloc(
1.488 + PKIX_TYPENUM type,
1.489 + PKIX_UInt32 size,
1.490 + PKIX_PL_Object **pObject,
1.491 + void *plContext);
1.492 +
1.493 +/*
1.494 + * FUNCTION: PKIX_PL_Object_IsTypeRegistered
1.495 + * DESCRIPTION:
1.496 + *
1.497 + * Checks whether "type" has been registered by a previous call to
1.498 + * PKIX_PL_Object_RegisterType() and stores the Boolean result at "pBool".
1.499 + * This function will typically only be called by constructors for specific
1.500 + * types.
1.501 + *
1.502 + * PARAMETERS:
1.503 + * "type"
1.504 + * The type code to check if valid.
1.505 + * "pBool"
1.506 + * Address where Boolean will be stored. Must be non-NULL.
1.507 + * "plContext"
1.508 + * Platform-specific context pointer.
1.509 + * THREAD SAFETY:
1.510 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.511 + * RETURNS:
1.512 + * Returns NULL if the function succeeds.
1.513 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.514 + */
1.515 +PKIX_Error *
1.516 +PKIX_PL_Object_IsTypeRegistered(
1.517 + PKIX_UInt32 type,
1.518 + PKIX_Boolean *pBool,
1.519 + void *plContext);
1.520 +
1.521 +#ifdef PKIX_USER_OBJECT_TYPE
1.522 +/*
1.523 + * FUNCTION: PKIX_PL_Object_RegisterType
1.524 + * DESCRIPTION:
1.525 + *
1.526 + * Registers a new Object with type value "type" and associates it with a set
1.527 + * of functions ("destructor", "equalsFunction", "hashcodeFunction",
1.528 + * "toStringFunction", "comparator", "duplicateFunction"). The new type value
1.529 + * is also associated with a string pointed to by "description", which is used
1.530 + * by the default ToStringCallback. This function may only be called with a
1.531 + * particular "type" value once. If "destructor", "equalsFunction",
1.532 + * "hashcodeFunction", or "toStringFunction" are NULL, default functions will
1.533 + * be registered. However, if "comparator" and "duplicateFunction" are NULL,
1.534 + * no functions will be registered and calls to PKIX_PL_Object_Compare and
1.535 + * PKIX_PL_Object_Duplicate will result in an error.
1.536 + *
1.537 + * PARAMETERS:
1.538 + * "type"
1.539 + * The type code.
1.540 + * "description"
1.541 + * The string used by the default ToStringCallback. Default used if NULL.
1.542 + * "destructor"
1.543 + * The DestructorCallback function to be set. Default used if NULL.
1.544 + * "equalsFunction"
1.545 + * The EqualsCallback function to be set. Default used if NULL.
1.546 + * "hashcodeFunction"
1.547 + * The HashcodeCallback function to be set. Default used if NULL.
1.548 + * "toStringFunction"
1.549 + * The ToStringCallback function to be set. Default used if NULL.
1.550 + * "comparator"
1.551 + * The ComparatorCallback function to be set. None set if NULL. If no
1.552 + * callback function is set in this field, calls to
1.553 + * PKIX_PL_Object_Compare() will result in an error.
1.554 + * "duplicateFunction"
1.555 + * The DuplicateCallback function to be set. None set if NULL. If no
1.556 + * callback function is set in this field, calls to
1.557 + * PKIX_PL_Object_Duplicate() will result in an error.
1.558 + * "plContext"
1.559 + * Platform-specific context pointer.
1.560 + * THREAD SAFETY:
1.561 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.562 + * RETURNS:
1.563 + * Returns NULL if the function succeeds.
1.564 + * Returns an Object Error if "type" is already registered.
1.565 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.566 + */
1.567 +PKIX_Error *
1.568 +PKIX_PL_Object_RegisterType(
1.569 + PKIX_UInt32 type,
1.570 + char *description,
1.571 + PKIX_PL_DestructorCallback destructor,
1.572 + PKIX_PL_EqualsCallback equalsFunction,
1.573 + PKIX_PL_HashcodeCallback hashcodeFunction,
1.574 + PKIX_PL_ToStringCallback toStringFunction,
1.575 + PKIX_PL_ComparatorCallback comparator,
1.576 + PKIX_PL_DuplicateCallback duplicateFunction,
1.577 + void *plContext);
1.578 +
1.579 +#endif
1.580 +/*
1.581 + * FUNCTION: PKIX_PL_Object_InvalidateCache
1.582 + * DESCRIPTION:
1.583 + *
1.584 + * Invalidates the cache of the Object pointed to by "object". The cache
1.585 + * contains results of Hashcode and ToString. This function should be used by
1.586 + * mutable objects whenever changes are made to the Object's state (after
1.587 + * creation).
1.588 + *
1.589 + * For example, if ToString is called on a mutable Object, the result will be
1.590 + * computed, cached, and returned. If the Object's state does not change, a
1.591 + * subsequent call to ToString will recognize that the relevant result is
1.592 + * cached and will simply return the result (without calling the Object's
1.593 + * ToStringCallback to recompute it). However, when the Object's state
1.594 + * changes, the cache needs to be invalidated in order to force a subsequent
1.595 + * call to ToString to recompute the result.
1.596 + *
1.597 + * PARAMETERS:
1.598 + * "object"
1.599 + * Address of Object whose cache is to be invalidated. Must be non-NULL.
1.600 + * "plContext"
1.601 + * Platform-specific context pointer.
1.602 + *
1.603 + * THREAD SAFETY
1.604 + * Thread Safe - Object Type Table is locked during modification.
1.605 + *
1.606 + * Multiple threads can safely call this function without worrying about
1.607 + * conflicts, even if they're operating on the same object.
1.608 + * RETURNS:
1.609 + * Returns NULL if the function succeeds.
1.610 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.611 + */
1.612 +PKIX_Error *
1.613 +PKIX_PL_Object_InvalidateCache(
1.614 + PKIX_PL_Object *object,
1.615 + void *plContext);
1.616 +
1.617 +/*
1.618 + * FUNCTION: PKIX_PL_Object_IncRef
1.619 + * DESCRIPTION:
1.620 + *
1.621 + * Increments the reference count of the Object pointed to by "object".
1.622 + *
1.623 + * PARAMETERS:
1.624 + * "object"
1.625 + * Address of Object whose reference count is to be incremented.
1.626 + * Must be non-NULL.
1.627 + * "plContext"
1.628 + * Platform-specific context pointer.
1.629 + * THREAD SAFETY:
1.630 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.631 + * RETURNS:
1.632 + * Returns NULL if the function succeeds.
1.633 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.634 + */
1.635 +PKIX_Error *
1.636 +PKIX_PL_Object_IncRef(
1.637 + PKIX_PL_Object *object,
1.638 + void *plContext);
1.639 +
1.640 +/*
1.641 + * FUNCTION: PKIX_PL_Object_DecRef
1.642 + * DESCRIPTION:
1.643 + *
1.644 + * Decrements the reference count of the Object pointed to by "object". If the
1.645 + * resulting reference count is zero, the destructor (if any) registered for
1.646 + * the Object's type (by PKIX_PL_RegisterType) will be called and then the
1.647 + * Object will be destroyed.
1.648 + *
1.649 + * PARAMETERS:
1.650 + * "object"
1.651 + * Address of Object whose reference count is to be decremented.
1.652 + * Must be non-NULL.
1.653 + * "plContext"
1.654 + * Platform-specific context pointer.
1.655 + * THREAD SAFETY:
1.656 + * If destructor is not called, multiple threads can safely call this function
1.657 + * without worrying about conflicts, even if they're operating on the same
1.658 + * object. If destructor is called, thread safety depends on the callback
1.659 + * defined by PKIX_PL_RegisterType().
1.660 + * RETURNS:
1.661 + * Returns NULL if the function succeeds.
1.662 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.663 + */
1.664 +PKIX_Error *
1.665 +PKIX_PL_Object_DecRef(
1.666 + PKIX_PL_Object *object,
1.667 + void *plContext);
1.668 +
1.669 +/*
1.670 + * FUNCTION: PKIX_PL_Object_Equals
1.671 + * DESCRIPTION:
1.672 + *
1.673 + * Compares the Object pointed to by "firstObject" with the Object pointed to
1.674 + * by "secondObject" for equality using the callback function registered for
1.675 + * "firstObject"'s type, and stores the Boolean result at "pResult". While
1.676 + * typical callbacks will return PKIX_FALSE if the objects are of different
1.677 + * types, other callbacks may be capable of comparing objects of different
1.678 + * types [which may correctly result in cases where Equals(first, second)
1.679 + * differs from Equals(second, first)].
1.680 + *
1.681 + * PARAMETERS:
1.682 + * "firstObject"
1.683 + * Address of the first Object to compare. Must be non-NULL.
1.684 + * The EqualsCallback for this Object will be called.
1.685 + * "secondObject"
1.686 + * Address of the second Object to compare. Must be non-NULL.
1.687 + * "pResult"
1.688 + * Address where Boolean will be stored. Must be non-NULL.
1.689 + * "plContext"
1.690 + * Platform-specific context pointer.
1.691 + * THREAD SAFETY:
1.692 + * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
1.693 + * RETURNS:
1.694 + * Returns NULL if the function succeeds.
1.695 + * Returns an Object Error if the function fails in a non-fatal way.
1.696 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.697 + */
1.698 +PKIX_Error *
1.699 +PKIX_PL_Object_Equals(
1.700 + PKIX_PL_Object *firstObject,
1.701 + PKIX_PL_Object *secondObject,
1.702 + PKIX_Boolean *pResult,
1.703 + void *plContext);
1.704 +
1.705 +/*
1.706 + * FUNCTION: PKIX_PL_Object_Hashcode
1.707 + * DESCRIPTION:
1.708 + *
1.709 + * Computes a hashcode of the Object pointed to by "object" using the
1.710 + * callback registered for "object"'s type and stores it at "pValue". Two
1.711 + * objects which are equal should have the same hashcode. Once a call to
1.712 + * Hashcode has been made, the results are cached and subsequent calls to
1.713 + * Hashcode will return the cached value. For mutable objects, an
1.714 + * InvalidateCache function is provided, which should be called whenever
1.715 + * changes are made to the object's state (after creation).
1.716 + *
1.717 + * PARAMETERS:
1.718 + * "object"
1.719 + * Address of the Object whose hashcode is desired. Must be non-NULL.
1.720 + * The HashcodeCallback for this object will be called.
1.721 + * "pValue"
1.722 + * Address where PKIX_Int32 will be stored. Must be non-NULL.
1.723 + * "plContext"
1.724 + * Platform-specific context pointer.
1.725 + *
1.726 + * THREAD SAFETY:
1.727 + * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
1.728 + * RETURNS:
1.729 + * Returns NULL if the function succeeds.
1.730 + * Returns an Object Error if the function fails in a non-fatal way.
1.731 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.732 + */
1.733 +PKIX_Error *
1.734 +PKIX_PL_Object_Hashcode(
1.735 + PKIX_PL_Object *object,
1.736 + PKIX_UInt32 *pValue,
1.737 + void *plContext);
1.738 +
1.739 +/*
1.740 + * FUNCTION: PKIX_PL_Object_ToString
1.741 + * DESCRIPTION:
1.742 + *
1.743 + * Creates a string representation of the Object pointed to by "object" using
1.744 + * the callback registered for "object"'s type and stores it at "pString".
1.745 + * Once a call to ToString has been made, the results are cached and
1.746 + * subsequent calls to ToString will return the cached value. For mutable
1.747 + * objects, an InvalidateCache function is provided, which should be called
1.748 + * whenever changes are made to the object's state (after creation).
1.749 + *
1.750 + * PARAMETERS:
1.751 + * "object"
1.752 + * Address of Object whose string representation is desired.
1.753 + * Must be non-NULL. The ToStringCallback for this object will be called.
1.754 + * "pString"
1.755 + * Address where object pointer will be stored. Must be non-NULL.
1.756 + * "plContext"
1.757 + * Platform-specific context pointer.
1.758 + * THREAD SAFETY:
1.759 + * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
1.760 + * RETURNS:
1.761 + * Returns NULL if the function succeeds.
1.762 + * Returns an Object Error if the function fails in a non-fatal way.
1.763 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.764 + */
1.765 +PKIX_Error *
1.766 +PKIX_PL_Object_ToString(
1.767 + PKIX_PL_Object *object,
1.768 + PKIX_PL_String **pString,
1.769 + void *plContext);
1.770 +
1.771 +/*
1.772 + * FUNCTION: PKIX_PL_Object_Compare
1.773 + * DESCRIPTION:
1.774 + *
1.775 + * Compares the Object pointed to by "firstObject" and the Object pointed to
1.776 + * by "secondObject" using the comparator registered for "firstObject"'s type
1.777 + * and stores the result at "pResult". Different types may be compared. This
1.778 + * may correctly result in cases where Compare(first, second) is not the
1.779 + * opposite of Compare(second, first). The PKIX_Int32 value stored at
1.780 + * "pResult" will be:
1.781 + * Less than 0 if "firstObject" < "secondObject"
1.782 + * Equals to 0 if "firstObject" = "secondObject"
1.783 + * Greater than 0 if "firstObject" > "secondObject"
1.784 + *
1.785 + * PARAMETERS:
1.786 + * "firstObject"
1.787 + * Address of first Object to compare. Must be non-NULL.
1.788 + * The ComparatorCallback for this object will be called.
1.789 + * "secondObject"
1.790 + * Address of second object to compare. Must be non-NULL.
1.791 + * "pResult
1.792 + * Address where PKIX_Int32 will be stored. Must be non-NULL.
1.793 + * "plContext"
1.794 + * Platform-specific context pointer.
1.795 + * THREAD SAFETY:
1.796 + * Thread safety depends on the comparator defined by PKIX_PL_RegisterType().
1.797 + * RETURNS:
1.798 + * Returns NULL if the function succeeds.
1.799 + * Returns an Object Error if the function fails in a non-fatal way.
1.800 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.801 + */
1.802 +PKIX_Error *
1.803 +PKIX_PL_Object_Compare(
1.804 + PKIX_PL_Object *firstObject,
1.805 + PKIX_PL_Object *secondObject,
1.806 + PKIX_Int32 *pResult,
1.807 + void *plContext);
1.808 +
1.809 +/*
1.810 + * FUNCTION: PKIX_PL_Object_Duplicate
1.811 + * DESCRIPTION:
1.812 + *
1.813 + * Creates a duplicate copy of the Object pointed to by "object" using the
1.814 + * callback registered for "object"'s type and stores the copy at
1.815 + * "pNewObject". Changes to the new object will not affect the original and
1.816 + * vice versa.
1.817 + *
1.818 + * Note that if "object" is immutable, the Duplicate callback function simply
1.819 + * needs to increment the reference count on "object" and return a reference
1.820 + * to "object".
1.821 + *
1.822 + * PARAMETERS:
1.823 + * "object"
1.824 + * Address of Object to be duplicated. Must be non-NULL.
1.825 + * The DuplicateCallback for this Object will be called.
1.826 + * "pNewObject"
1.827 + * Address where object pointer will be stored. Must be non-NULL.
1.828 + * "plContext"
1.829 + * Platform-specific context pointer.
1.830 + * THREAD SAFETY:
1.831 + * Thread safety depends on the callback defined by PKIX_PL_RegisterType().
1.832 + * RETURNS:
1.833 + * Returns NULL if the function succeeds.
1.834 + * Returns an Object Error if the function fails in a non-fatal way.
1.835 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.836 + */
1.837 +PKIX_Error *
1.838 +PKIX_PL_Object_Duplicate(
1.839 + PKIX_PL_Object *object,
1.840 + PKIX_PL_Object **pNewObject,
1.841 + void *plContext);
1.842 +
1.843 +/*
1.844 + * FUNCTION: PKIX_PL_Object_GetType
1.845 + * DESCRIPTION:
1.846 + *
1.847 + * Retrieves the type code of the Object pointed to by "object" and stores it
1.848 + * at "pType". See pkixt.h for type codes.
1.849 + *
1.850 + * PARAMETERS:
1.851 + * "object"
1.852 + * Address of Object whose type is desired. Must be non-NULL.
1.853 + * "pType"
1.854 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.855 + * "plContext"
1.856 + * Platform-specific context pointer.
1.857 + * THREAD SAFETY:
1.858 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.859 + * RETURNS:
1.860 + * Returns NULL if the function succeeds.
1.861 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.862 + */
1.863 +PKIX_Error *
1.864 +PKIX_PL_Object_GetType(
1.865 + PKIX_PL_Object *object,
1.866 + PKIX_UInt32 *pType,
1.867 + void *plContext);
1.868 +
1.869 +/*
1.870 + * FUNCTION: PKIX_PL_Object_Lock
1.871 + * DESCRIPTION:
1.872 + *
1.873 + * Locks the Mutex associated with the Object pointed to by "object". When an
1.874 + * object is created, it is associated with an object-specific Mutex to allow
1.875 + * for synchronization when the fields of the object are modified.
1.876 + *
1.877 + * PARAMETERS:
1.878 + * "object"
1.879 + * Address of Object whose Mutex is to be locked. Must be non-NULL.
1.880 + * "plContext"
1.881 + * Platform-specific context pointer.
1.882 + * THREAD SAFETY:
1.883 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.884 + * RETURNS:
1.885 + * Returns NULL if the function succeeds.
1.886 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.887 + */
1.888 +PKIX_Error *
1.889 +PKIX_PL_Object_Lock(
1.890 + PKIX_PL_Object *object,
1.891 + void *plContext);
1.892 +
1.893 +/*
1.894 + * FUNCTION: PKIX_PL_Object_Unlock
1.895 + * DESCRIPTION:
1.896 + *
1.897 + * Unlocks the Mutex associated with the Object pointed to by "object". When
1.898 + * an object is created, it is associated with an object-specific Mutex to
1.899 + * allow for synchronization when the fields of the object are modified.
1.900 + *
1.901 + * PARAMETERS:
1.902 + * "object"
1.903 + * Address of Object whose Mutex is to be unlocked. Must be non-NULL.
1.904 + * "plContext"
1.905 + * Platform-specific context pointer.
1.906 + * THREAD SAFETY:
1.907 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.908 + * RETURNS:
1.909 + * Returns NULL if the function succeeds.
1.910 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.911 + */
1.912 +PKIX_Error *
1.913 +PKIX_PL_Object_Unlock(
1.914 + PKIX_PL_Object *object,
1.915 + void *plContext);
1.916 +
1.917 +/* mutexes (locks) */
1.918 +
1.919 +/*
1.920 + * FUNCTION: PKIX_PL_Mutex_Create
1.921 + * DESCRIPTION:
1.922 + *
1.923 + * Creates a new Mutex and stores it at "pNewLock".
1.924 + *
1.925 + * PARAMETERS:
1.926 + * "pNewLock"
1.927 + * Address where object pointer will be stored. Must be non-NULL.
1.928 + * "plContext"
1.929 + * Platform-specific context pointer.
1.930 + * THREAD SAFETY:
1.931 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.932 + * RETURNS:
1.933 + * Returns NULL if the function succeeds.
1.934 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.935 + */
1.936 +PKIX_Error *
1.937 +PKIX_PL_Mutex_Create(
1.938 + PKIX_PL_Mutex **pNewLock,
1.939 + void *plContext);
1.940 +
1.941 +/*
1.942 + * FUNCTION: PKIX_PL_Mutex_Lock
1.943 + * DESCRIPTION:
1.944 + *
1.945 + * Locks the Mutex pointed to by "lock". If the Mutex is already locked, this
1.946 + * function will block the current thread until the mutex can be locked by
1.947 + * this thread.
1.948 + *
1.949 + * PARAMETERS:
1.950 + * "lock"
1.951 + * Address of Mutex to lock. Must be non-NULL.
1.952 + * "plContext"
1.953 + * Platform-specific context pointer.
1.954 + * THREAD SAFETY:
1.955 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.956 + * RETURNS:
1.957 + * Returns NULL if the function succeeds.
1.958 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.959 + */
1.960 +PKIX_Error *
1.961 +PKIX_PL_Mutex_Lock(
1.962 + PKIX_PL_Mutex *lock,
1.963 + void *plContext);
1.964 +
1.965 +/*
1.966 + * FUNCTION: PKIX_PL_Mutex_Unlock
1.967 + * DESCRIPTION:
1.968 + *
1.969 + * Unlocks the Mutex pointed to by "lock" if the current thread holds the
1.970 + * Mutex.
1.971 + *
1.972 + * PARAMETERS:
1.973 + * "lock"
1.974 + * Address of Mutex to unlock. Must be non-NULL.
1.975 + * "plContext"
1.976 + * Platform-specific context pointer.
1.977 + * THREAD SAFETY:
1.978 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.979 + * RETURNS:
1.980 + * Returns NULL if the function succeeds.
1.981 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.982 + */
1.983 +PKIX_Error *
1.984 +PKIX_PL_Mutex_Unlock(
1.985 + PKIX_PL_Mutex *lock,
1.986 + void *plContext);
1.987 +
1.988 +/* monitor (locks) */
1.989 +
1.990 +/*
1.991 + * FUNCTION: PKIX_PL_MonitorLock_Create
1.992 + * DESCRIPTION:
1.993 + *
1.994 + * Creates a new PKIX_PL_MonitorLock and stores it at "pNewLock".
1.995 + *
1.996 + * PARAMETERS:
1.997 + * "pNewLock"
1.998 + * Address where object pointer will be stored. Must be non-NULL.
1.999 + * "plContext"
1.1000 + * Platform-specific context pointer.
1.1001 + * THREAD SAFETY:
1.1002 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1003 + * RETURNS:
1.1004 + * Returns NULL if the function succeeds.
1.1005 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1006 + */
1.1007 +PKIX_Error *
1.1008 +PKIX_PL_MonitorLock_Create(
1.1009 + PKIX_PL_MonitorLock **pNewLock,
1.1010 + void *plContext);
1.1011 +
1.1012 +/*
1.1013 + * FUNCTION: PKIX_PL_MonitorLock_Enter
1.1014 + * DESCRIPTION:
1.1015 + *
1.1016 + * Locks the MonitorLock pointed to by "lock". If the MonitorLock is already
1.1017 + * locked by other thread, this function will block the current thread. If
1.1018 + * the "lock" had been locked by current thread, this function will NOT block.
1.1019 + *
1.1020 + * PARAMETERS:
1.1021 + * "lock"
1.1022 + * Address of MonitorLock to lock. Must be non-NULL.
1.1023 + * "plContext"
1.1024 + * Platform-specific context pointer.
1.1025 + * THREAD SAFETY:
1.1026 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1027 + * RETURNS:
1.1028 + * Returns NULL if the function succeeds.
1.1029 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1030 + */
1.1031 +PKIX_Error *
1.1032 +PKIX_PL_MonitorLock_Enter(
1.1033 + PKIX_PL_MonitorLock *lock,
1.1034 + void *plContext);
1.1035 +
1.1036 +/*
1.1037 + * FUNCTION: PKIX_PL_MonitorLock_Exit
1.1038 + * DESCRIPTION:
1.1039 + *
1.1040 + * Unlocks the MonitorLock pointed to by "lock" if the lock counter of
1.1041 + * current thread holds the MonitorLock reach 0, the lock is released.
1.1042 + *
1.1043 + * PARAMETERS:
1.1044 + * "lock"
1.1045 + * Address of MonitorLock to unlock. Must be non-NULL.
1.1046 + * "plContext"
1.1047 + * Platform-specific context pointer.
1.1048 + * THREAD SAFETY:
1.1049 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1050 + * RETURNS:
1.1051 + * Returns NULL if the function succeeds.
1.1052 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1053 + */
1.1054 +PKIX_Error *
1.1055 +PKIX_PL_MonitorLock_Exit(
1.1056 + PKIX_PL_MonitorLock *lock,
1.1057 + void *plContext);
1.1058 +
1.1059 +/* strings and formatted printing */
1.1060 +
1.1061 +/*
1.1062 + * FUNCTION: PKIX_PL_String_Create
1.1063 + * DESCRIPTION:
1.1064 + *
1.1065 + * Creates a new String using the data pointed to by "pString", the
1.1066 + * PKIX_UInt32 pointed to by "stringLen", and the PKIX_UInt32 pointed to by
1.1067 + * "fmtIndicator" and stores it at "pString". If the format is PKIX_ESCASCII
1.1068 + * the "stringLen" parameter is ignored and the string extends until a zero
1.1069 + * byte is found. Once created, a String object is immutable.
1.1070 + *
1.1071 + * Valid formats are:
1.1072 + * PKIX_ESCASCII
1.1073 + * PKIX_ESCASCII_DEBUG
1.1074 + * PKIX_UTF8
1.1075 + * PKIX_UTF8_NULL_TERM
1.1076 + * PKIX_UTF16
1.1077 + *
1.1078 + * PARAMETERS:
1.1079 + * "fmtIndicator"
1.1080 + * Format that "stringRep" is encoded with. Must be non-NULL.
1.1081 + * "stringRep"
1.1082 + * Address of encoded string representation. Must be non-NULL.
1.1083 + * "stringLen"
1.1084 + * Length of data stored at stringRep.
1.1085 + * "pString"
1.1086 + * Address where object pointer will be stored. Must be non-NULL.
1.1087 + * "plContext"
1.1088 + * Platform-specific context pointer.
1.1089 + * THREAD SAFETY:
1.1090 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1091 + * RETURNS:
1.1092 + * Returns NULL if the function succeeds.
1.1093 + * Returns a String Error if the function fails in a non-fatal way.
1.1094 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1095 + */
1.1096 +PKIX_Error *
1.1097 +PKIX_PL_String_Create(
1.1098 + PKIX_UInt32 fmtIndicator,
1.1099 + const void *stringRep,
1.1100 + PKIX_UInt32 stringLen,
1.1101 + PKIX_PL_String **pString,
1.1102 + void *plContext);
1.1103 +
1.1104 +/*
1.1105 + * FUNCTION: PKIX_PL_Sprintf
1.1106 + * DESCRIPTION:
1.1107 + *
1.1108 + * Creates a formatted string at "pOut" using the given format "fmt" and a
1.1109 + * variable length list of arguments. The format flags are identical to
1.1110 + * standard C with the exception that %s expects a PKIX_PL_String*, rather
1.1111 + * than a char *, and that {%d, %i, %o, %u, %x, %X} expect PKIX_UInt32 or
1.1112 + * PKIX_Int32 instead of int or unsigned int.
1.1113 + *
1.1114 + * PARAMETERS:
1.1115 + * "pOut"
1.1116 + * Address where object pointer will be stored. Must be non-NULL.
1.1117 + * "plContext"
1.1118 + * Platform-specific context pointer.
1.1119 + * "fmt"
1.1120 + * Address of format string. Must be non-NULL.
1.1121 + * THREAD SAFETY:
1.1122 + * Not Thread Safe - Caller must have exclusive access to all arguments.
1.1123 + * (see Thread Safety Definitions in Programmer's Guide)
1.1124 + * RETURNS:
1.1125 + * Returns NULL if the function succeeds.
1.1126 + * Returns a String Error if the function fails in a non-fatal way.
1.1127 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1128 + */
1.1129 +PKIX_Error *
1.1130 +PKIX_PL_Sprintf(
1.1131 + PKIX_PL_String **pOut,
1.1132 + void *plContext,
1.1133 + const PKIX_PL_String *fmt, ...);
1.1134 +
1.1135 +/*
1.1136 + * FUNCTION: PKIX_PL_GetString
1.1137 + * DESCRIPTION:
1.1138 + *
1.1139 + * Retrieves the String associated with the value of "stringID" (if any) and
1.1140 + * stores it at "pString". If no such string is associated with "stringID",
1.1141 + * this function uses "defaultString" to create a String and stores it at
1.1142 + * "pString".
1.1143 + *
1.1144 + * PARAMETERS:
1.1145 + * "stringID"
1.1146 + * PKIX_UInt32 valud of string identifier.
1.1147 + * "defaultString"
1.1148 + * Address of a PKIX_ESCASCII encoded string representation.
1.1149 + * Must be non-NULL.
1.1150 + * "pString"
1.1151 + * Address where object pointer will be stored. Must be non-NULL.
1.1152 + * "plContext"
1.1153 + * Platform-specific context pointer.
1.1154 + * THREAD SAFETY:
1.1155 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1156 + * RETURNS:
1.1157 + * Returns NULL if the function succeeds.
1.1158 + * Returns a String Error if the function fails in a non-fatal way.
1.1159 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1160 + */
1.1161 +PKIX_Error *
1.1162 +PKIX_PL_GetString(
1.1163 + PKIX_UInt32 stringID,
1.1164 + char *defaultString,
1.1165 + PKIX_PL_String **pString,
1.1166 + void *plContext);
1.1167 +
1.1168 +/*
1.1169 + * FUNCTION: PKIX_PL_String_GetEncoded
1.1170 + * DESCRIPTION:
1.1171 + *
1.1172 + * Retrieves the value of the String pointed to by "string" in the encoding
1.1173 + * specified by "fmtIndicator" and stores the result in "pStringRep" and
1.1174 + * "pLength", respectively. Note that "pStringRep" is not reference counted
1.1175 + * and will need to be freed with PKIX_PL_Free().
1.1176 + *
1.1177 + * PARAMETERS:
1.1178 + * "string"
1.1179 + * Address of String whose encoded value is desired. Must be non-NULL.
1.1180 + * "fmtIndicator"
1.1181 + * Format of encoding. Supported formats are:
1.1182 + * PKIX_ESCASCII, PKIX_ESCASII_DEBUG, PKIX_UTF8, PKIX_UTF8_NULL_TERM, and
1.1183 + * PKIX_UTF16. XXX Where are these documented?
1.1184 + * "pStringRep"
1.1185 + * Address where pointer to encoded value will be stored.
1.1186 + * Must be non-NULL.
1.1187 + * "pLength"
1.1188 + * Address where byte length of encoded value will be stored.
1.1189 + * "plContext"
1.1190 + * Platform-specific context pointer.
1.1191 + * THREAD SAFETY:
1.1192 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1193 + * RETURNS:
1.1194 + * Returns NULL if the function succeeds.
1.1195 + * Returns a String Error if the function fails in a non-fatal way.
1.1196 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1197 + */
1.1198 +PKIX_Error *
1.1199 +PKIX_PL_String_GetEncoded(
1.1200 + PKIX_PL_String *string,
1.1201 + PKIX_UInt32 fmtIndicator,
1.1202 + void **pStringRep,
1.1203 + PKIX_UInt32 *pLength,
1.1204 + void *plContext);
1.1205 +
1.1206 +/*
1.1207 + * Hashtable
1.1208 + *
1.1209 + * A hashtable is a very efficient data structure used for mapping keys to
1.1210 + * values. Any non-null PKIX_PL_Object can be used as a key or as a value,
1.1211 + * provided that it correctly implements the PKIX_PL_EqualsCallback and the
1.1212 + * PKIX_PL_HashcodeCallback. A hashtable consists of several buckets, with
1.1213 + * each bucket capable of holding a linked list of key/value mappings. When
1.1214 + * adding, retrieving, or deleting a value, the hashcode of the key is used to
1.1215 + * determine which bucket's linked list is relevant. The corresponding
1.1216 + * key/value pair is then appended, retrieved, or deleted.
1.1217 + */
1.1218 +
1.1219 +/*
1.1220 + * FUNCTION: PKIX_PL_HashTable_Create
1.1221 + * DESCRIPTION:
1.1222 + *
1.1223 + * Creates a new Hashtable with an initial capacity of "numBuckets" buckets
1.1224 + * and "maxEntriesPerBucket" of entries limit for each bucket and stores it
1.1225 + * at "pResult".
1.1226 + *
1.1227 + * PARAMETERS:
1.1228 + * "numBuckets"
1.1229 + * The initial number of hash table buckets. Must be non-zero.
1.1230 + * "maxEntriesPerBucket"
1.1231 + * The limit of entries per bucket. Zero means no limit.
1.1232 + * "pResult"
1.1233 + * Address where object pointer will be stored. Must be non-NULL.
1.1234 + * "plContext"
1.1235 + * Platform-specific context pointer.
1.1236 + * THREAD SAFETY:
1.1237 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1238 + * RETURNS:
1.1239 + * Returns NULL if the function succeeds.
1.1240 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1241 + */
1.1242 +PKIX_Error *
1.1243 +PKIX_PL_HashTable_Create(
1.1244 + PKIX_UInt32 numBuckets,
1.1245 + PKIX_UInt32 maxEntriesPerBucket,
1.1246 + PKIX_PL_HashTable **pResult,
1.1247 + void *plContext);
1.1248 +
1.1249 +/*
1.1250 + * FUNCTION: PKIX_PL_HashTable_Add
1.1251 + * DESCRIPTION:
1.1252 + *
1.1253 + * Adds a key/value mapping using the Objects pointed to by "key" and "value"
1.1254 + * to the Hashtable pointed to by "ht".
1.1255 + *
1.1256 + * Function increments key/value reference counts. Caller is responsible to
1.1257 + * to decrement(destroy) key/value ref counts(objects).
1.1258 + *
1.1259 + * PARAMETERS:
1.1260 + * "ht"
1.1261 + * Address of Hashtable to be added to. Must be non-NULL.
1.1262 + * "key"
1.1263 + * Address of Object to be associated with "value". Must be non-NULL.
1.1264 + * "value"
1.1265 + * Address of Object to be added to Hashtable. Must be non-NULL.
1.1266 + * "plContext"
1.1267 + * Platform-specific context pointer.
1.1268 + * THREAD SAFETY:
1.1269 + * Not Thread Safe - assumes exclusive access to "ht"
1.1270 + * (see Thread Safety Definitions in Programmer's Guide)
1.1271 + * RETURNS:
1.1272 + * Returns NULL if the function succeeds.
1.1273 + * Returns a Hashtable Error if the function fails in a non-fatal way.
1.1274 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1275 + */
1.1276 +PKIX_Error *
1.1277 +PKIX_PL_HashTable_Add(
1.1278 + PKIX_PL_HashTable *ht,
1.1279 + PKIX_PL_Object *key,
1.1280 + PKIX_PL_Object *value,
1.1281 + void *plContext);
1.1282 +
1.1283 +/*
1.1284 + * FUNCTION: PKIX_PL_HashTable_Remove
1.1285 + * DESCRIPTION:
1.1286 + *
1.1287 + * Removes the Object value whose key is equal to the Object pointed to by
1.1288 + * "key" from the Hashtable pointed to by "ht". If no such object exists,
1.1289 + * this function throws an Error.
1.1290 + *
1.1291 + * Function frees "value" object. Caller is responsible to free "key"
1.1292 + * object.
1.1293 + *
1.1294 + * PARAMETERS:
1.1295 + * "ht"
1.1296 + * Address of Hashtable to remove object from. Must be non-NULL.
1.1297 + * "key"
1.1298 + * Address of Object used for lookup. Must be non-NULL.
1.1299 + * "plContext"
1.1300 + * Platform-specific context pointer.
1.1301 + * THREAD SAFETY:
1.1302 + * Not Thread Safe - assumes exclusive access to "ht"
1.1303 + * (see Thread Safety Definitions in Programmer's Guide)
1.1304 + * RETURNS:
1.1305 + * Returns NULL if the function succeeds.
1.1306 + * Returns a Hashtable Error if the function fails in a non-fatal way.
1.1307 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1308 + */
1.1309 +PKIX_Error *
1.1310 +PKIX_PL_HashTable_Remove(
1.1311 + PKIX_PL_HashTable *ht,
1.1312 + PKIX_PL_Object *key,
1.1313 + void *plContext);
1.1314 +
1.1315 +/*
1.1316 + * FUNCTION: PKIX_PL_HashTable_Lookup
1.1317 + * DESCRIPTION:
1.1318 + *
1.1319 + * Retrieves the Object whose key equals the Object pointed to by "key" from
1.1320 + * the Hashtable associated with "ht" and stores it at "pResult". If no
1.1321 + * Object is found, this function stores NULL at "pResult".
1.1322 + *
1.1323 + * PARAMETERS:
1.1324 + * "ht"
1.1325 + * Address of Hashtable to lookup Object from. Must be non-NULL.
1.1326 + * "key"
1.1327 + * Address of key Object used for lookup. Must be non-NULL.
1.1328 + * "pResult"
1.1329 + * Address where object pointer will be stored. Must be non-NULL.
1.1330 + * "plContext"
1.1331 + * Platform-specific context pointer.
1.1332 + * THREAD SAFETY:
1.1333 + * Conditionally Thread Safe
1.1334 + * (see Thread Safety Definitions in Programmer's Guide)
1.1335 + * RETURNS:
1.1336 + * Returns NULL if the function succeeds.
1.1337 + * Returns a Hashtable Error if the function fails in a non-fatal way.
1.1338 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1339 + */
1.1340 +PKIX_Error *
1.1341 +PKIX_PL_HashTable_Lookup(
1.1342 + PKIX_PL_HashTable *ht,
1.1343 + PKIX_PL_Object *key,
1.1344 + PKIX_PL_Object **pResult,
1.1345 + void *plContext);
1.1346 +
1.1347 +/*
1.1348 + * FUNCTION: PKIX_PL_ByteArray_Create
1.1349 + * DESCRIPTION:
1.1350 + *
1.1351 + * Creates a new ByteArray using "length" bytes of data pointed to by "array"
1.1352 + * and stores it at "pByteArray". Once created, a ByteArray is immutable.
1.1353 + *
1.1354 + * PARAMETERS:
1.1355 + * "array"
1.1356 + * Address of source data.
1.1357 + * "length"
1.1358 + * Number of bytes to copy.
1.1359 + * "pByteArray"
1.1360 + * Address where object pointer will be stored. Must be non-NULL.
1.1361 + * "plContext"
1.1362 + * Platform-specific context pointer.
1.1363 + * THREAD SAFETY:
1.1364 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1365 + * RETURNS:
1.1366 + * Returns NULL if the function succeeds.
1.1367 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1368 + */
1.1369 +PKIX_Error *
1.1370 +PKIX_PL_ByteArray_Create(
1.1371 + void *array,
1.1372 + PKIX_UInt32 length,
1.1373 + PKIX_PL_ByteArray **pByteArray,
1.1374 + void *plContext);
1.1375 +
1.1376 +/*
1.1377 + * FUNCTION: PKIX_PL_ByteArray_GetPointer
1.1378 + * DESCRIPTION:
1.1379 + *
1.1380 + * Allocates enough memory to hold the contents of the ByteArray pointed to
1.1381 + * by "byteArray", copies the data from the ByteArray pointed to by
1.1382 + * "byteArray" into the newly allocated memory, and stores a pointer to the
1.1383 + * memory at "pArray". Note that "pArray" is not reference counted. It will
1.1384 + * need to be freed with PKIX_PL_Free().
1.1385 + *
1.1386 + * PARAMETERS:
1.1387 + * "byteArray"
1.1388 + * Address of ByteArray whose data is desired. Must be non-NULL.
1.1389 + * "pArray"
1.1390 + * Address where object pointer will be stored. Must be non-NULL.
1.1391 + * "plContext"
1.1392 + * Platform-specific context pointer.
1.1393 + * THREAD SAFETY:
1.1394 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1395 + * RETURNS:
1.1396 + * Returns NULL if the function succeeds.
1.1397 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1398 + */
1.1399 +PKIX_Error *
1.1400 +PKIX_PL_ByteArray_GetPointer(
1.1401 + PKIX_PL_ByteArray *byteArray,
1.1402 + void **pArray,
1.1403 + void *plContext);
1.1404 +
1.1405 +/*
1.1406 + * FUNCTION: PKIX_PL_ByteArray_GetLength
1.1407 + * DESCRIPTION:
1.1408 + *
1.1409 + * Retrieves the length of the ByteArray pointed to by "byteArray" and stores
1.1410 + * the length at "pLength".
1.1411 + *
1.1412 + * PARAMETERS:
1.1413 + * "byteArray"
1.1414 + * Address of ByteArray whose length is desired. Must be non-NULL.
1.1415 + * "pLength"
1.1416 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.1417 + * "plContext"
1.1418 + * Platform-specific context pointer.
1.1419 + * THREAD SAFETY:
1.1420 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1421 + * RETURNS:
1.1422 + * Returns NULL if the function succeeds.
1.1423 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1424 + */
1.1425 +PKIX_Error *
1.1426 +PKIX_PL_ByteArray_GetLength(
1.1427 + PKIX_PL_ByteArray *byteArray,
1.1428 + PKIX_UInt32 *pLength,
1.1429 + void *plContext);
1.1430 +
1.1431 +/*
1.1432 + * FUNCTION: PKIX_PL_OID_Create
1.1433 + * DESCRIPTION:
1.1434 + *
1.1435 + * Creates a new OID using NSS oid tag.
1.1436 + *
1.1437 + * PARAMETERS:
1.1438 + * "idtag"
1.1439 + * nss oid id tag.
1.1440 + * "pOID"
1.1441 + * Address where object pointer will be stored. Must be non-NULL.
1.1442 + * "plContext"
1.1443 + * Platform-specific context pointer.
1.1444 + * THREAD SAFETY:
1.1445 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1446 + * RETURNS:
1.1447 + * Returns NULL if the function succeeds.
1.1448 + * Returns an OID Error if the function fails in a non-fatal way.
1.1449 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1450 + */
1.1451 +PKIX_Error *
1.1452 +PKIX_PL_OID_Create(
1.1453 + SECOidTag idtag,
1.1454 + PKIX_PL_OID **pOID,
1.1455 + void *plContext);
1.1456 +
1.1457 +/*
1.1458 + * FUNCTION: PKIX_PL_OID_CreateBySECItem
1.1459 + * DESCRIPTION:
1.1460 + *
1.1461 + * Creates a new OID using a DER encoded OID stored as SECItem.
1.1462 + *
1.1463 + * PARAMETERS:
1.1464 + * "derOid"
1.1465 + * Address of SECItem that holds DER encoded OID.
1.1466 + * "pOID"
1.1467 + * Address where object pointer will be stored. Must be non-NULL.
1.1468 + * "plContext"
1.1469 + * Platform-specific context pointer.
1.1470 + * THREAD SAFETY:
1.1471 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1472 + * RETURNS:
1.1473 + * Returns NULL if the function succeeds.
1.1474 + * Returns an OID Error if the function fails in a non-fatal way.
1.1475 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1476 + */
1.1477 +PKIX_Error *
1.1478 +PKIX_PL_OID_CreateBySECItem(
1.1479 + SECItem *derOid,
1.1480 + PKIX_PL_OID **pOID,
1.1481 + void *plContext);
1.1482 +
1.1483 +/*
1.1484 + * FUNCTION: PKIX_PL_BigInt_Create
1.1485 + * DESCRIPTION:
1.1486 + *
1.1487 + * Creates a new BigInt using the source String pointed to by "stringRep" and
1.1488 + * stores it at "pBigInt". Valid source Strings consist of an even number of
1.1489 + * hexadecimal digits, which are always interpreted as a positive number.
1.1490 + * Once created, a BigInt is immutable.
1.1491 + *
1.1492 + * The regexp format is:
1.1493 + * HexDigit ::= [0-9] | [A-F] | [a-f]
1.1494 + * DoubleHex ::= HexDigit HexDigit
1.1495 + * BigIntSrc ::= (DoubleHex)+
1.1496 + *
1.1497 + * Note that since we are using DoubleHex, the number of characters in the
1.1498 + * source MUST be even. Additionally, the first DoubleHex MUST NOT be "00"
1.1499 + * unless it is the only DoubleHex.
1.1500 + *
1.1501 + * Valid : "09"
1.1502 + * Valid : "00" (special case where first and only DoubleHex is "00")
1.1503 + * Invalid: "9" (not DoubleHex: odd number of characters)
1.1504 + * Invalid: "0009" (first DoubleHex is "00")
1.1505 + *
1.1506 + * XXX Why does this take a String object while OID_Create takes a char* ?
1.1507 + * Perhaps because OID_Create is often used with constant strings and
1.1508 + * this function isn't. That's a good reason, but we should explain it
1.1509 + * (if it's right)
1.1510 + * PARAMETERS:
1.1511 + * "stringRep"
1.1512 + * Address of String representing a BigInt. Must be non-NULL.
1.1513 + * "pBigInt"
1.1514 + * Address where object pointer will be stored. Must be non-NULL.
1.1515 + * "plContext"
1.1516 + * Platform-specific context pointer.
1.1517 + * THREAD SAFETY:
1.1518 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1519 + * RETURNS:
1.1520 + * Returns NULL if the function succeeds.
1.1521 + * Returns a BigInt Error if the function fails in a non-fatal way.
1.1522 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1523 + */
1.1524 +PKIX_Error *
1.1525 +PKIX_PL_BigInt_Create(
1.1526 + PKIX_PL_String *stringRep,
1.1527 + PKIX_PL_BigInt **pBigInt,
1.1528 + void *plContext);
1.1529 +
1.1530 +#ifdef __cplusplus
1.1531 +}
1.1532 +#endif
1.1533 +
1.1534 +/*
1.1535 + * FUNCTION: PKIX_PL_GetPLErrorCode
1.1536 + * DESCRIPTION:
1.1537 + *
1.1538 + * Returns error code from PL layer.
1.1539 + *
1.1540 + * THREAD SAFETY:
1.1541 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.1542 + * RETURNS:
1.1543 + * PL layer error code.
1.1544 + */
1.1545 +int
1.1546 +PKIX_PL_GetPLErrorCode();
1.1547 +
1.1548 +#endif /* _LIBPKIX_SYSTEM_H */
