diff options
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_util.h')
| -rwxr-xr-x | security/nss/lib/libpkix/include/pkix_util.h | 941 |
1 files changed, 941 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_util.h b/security/nss/lib/libpkix/include/pkix_util.h new file mode 100755 index 0000000000..e42f608c17 --- /dev/null +++ b/security/nss/lib/libpkix/include/pkix_util.h @@ -0,0 +1,941 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +/* + * These functions provide support for a number of other functions + * by creating and manipulating data structures used by those functions. + * + */ + +#ifndef _PKIX_UTIL_H +#define _PKIX_UTIL_H + +#include "pkixt.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* General + * + * Please refer to the libpkix Programmer's Guide for detailed information + * about how to use the libpkix library. Certain key warnings and notices from + * that document are repeated here for emphasis. + * + * All identifiers in this file (and all public identifiers defined in + * libpkix) begin with "PKIX_". Private identifiers only intended for use + * within the library begin with "pkix_". + * + * A function returns NULL upon success, and a PKIX_Error pointer upon failure. + * + * Unless otherwise noted, for all accessor (gettor) functions that return a + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a + * shared object. Therefore, the caller should treat this shared object as + * read-only and should not modify this shared object. When done using the + * shared object, the caller should release the reference to the object by + * using the PKIX_PL_Object_DecRef function. + * + * While a function is executing, if its arguments (or anything referred to by + * its arguments) are modified, free'd, or destroyed, the function's behavior + * is undefined. + * + */ + +/* PKIX_Logger + * + * PKIX_Loggers provide a standard way for the caller to insert custom logging + * facilities. These are used by libpkix to log errors, debug information, + * status, etc. The LogCallback allows custom logging to take place. + * Additionally, a Logger can be initialized with a loggerContext, which is + * where the caller can specify configuration data such as the name of a + * logfile or database. Note that this loggerContext must be a PKIX_PL_Object, + * allowing it to be reference-counted and allowing it to provide the standard + * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate). + * + * Once the caller has created the Logger object(s) (and set the loggerContext + * (if any) and the Log callback), the caller then registers these Loggers + * with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log + * entries will then be logged using the specified Loggers. If multiple + * Loggers are specified, every log entry will be logged with each of them. + * + * XXX Maybe give some guidance somewhere on how much detail each logging + * level should have and where component boundaries should be. Maybe in + * Implementor's Guide or Programmer's Guide. + */ + +#define PKIX_LOGGER_LEVEL_TRACE 5 +#define PKIX_LOGGER_LEVEL_DEBUG 4 +#define PKIX_LOGGER_LEVEL_WARNING 3 +#define PKIX_LOGGER_LEVEL_ERROR 2 +#define PKIX_LOGGER_LEVEL_FATALERROR 1 + +#define PKIX_LOGGER_LEVEL_MAX 5 + +/* + * FUNCTION: PKIX_Logger_LogCallback + * DESCRIPTION: + * + * This callback function logs a log entry containing the String pointed to + * by "message", the integer value of logLevel, and the String pointed to by + * "logComponent". A log entry can be associated with a particular log + * level (i.e. level 3) and a particular log component (i.e. "CertStore"). + * For example, someone reading the log may only be interested in very general + * log entries so they look only for log level 1. Similarly, they may only be + * interested in log entries pertaining to the CertStore component so they + * look only for that log component. This function can be used before calling + * PKIX_Initialize. + * + * PARAMETERS: + * "logger" + * Address of logger whose LogCallback is to be used. Must be non-NULL. + * "message" + * Address of String that is to be logged used "logger". Must be non-NULL. + * "logLevel" + * Integer value representing the log level for this entry. The higher the + * level, the more detail. Must be non-NULL. + * "logComponent" + * PKIXERRORNUM value (defined in pkixt.h) designating the log component + * for this entry. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same objects. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_Logger_LogCallback)( + PKIX_Logger *logger, + PKIX_PL_String *message, + PKIX_UInt32 logLevel, + PKIX_ERRORCLASS logComponent, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_Create + * DESCRIPTION: + * + * Creates a new Logger using the Object pointed to by "loggerContext" + * (if any) and stores it at "pLogger". The new Logger uses the LogCallback + * pointed to by "callback". The Logger's maximum logging level is initially + * set to a very high level and its logging component is set to NULL (all + * components). + * + * PARAMETERS: + * "callback" + * The LogCallback function to be used. Must be non-NULL. + * "loggerContext" + * Address of Object representing the Logger's context (if any). + * "pLogger" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_Create( + PKIX_Logger_LogCallback callback, + PKIX_PL_Object *loggerContext, + PKIX_Logger **pLogger, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_GetLogCallback + * DESCRIPTION: + * + * Retrieves a pointer to "logger's" Log callback function and puts it in + * "pCallback". + * + * PARAMETERS: + * "logger" + * Address of Logger whose Log callback is desired. Must be non-NULL. + * "pCallback" + * Address where Log callback function pointer will be stored. + * Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_GetLogCallback( + PKIX_Logger *logger, + PKIX_Logger_LogCallback *pCallback, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_GetLoggerContext + * DESCRIPTION: + * + * Retrieves a pointer to a PKIX_PL_Object representing the context (if any) + * of the Logger pointed to by "logger" and stores it at "pLoggerContext". + * + * PARAMETERS: + * "logger" + * Address of Logger whose context is to be stored. Must be non-NULL. + * "pLoggerContext" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_GetLoggerContext( + PKIX_Logger *logger, + PKIX_PL_Object **pLoggerContext, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_GetMaxLoggingLevel + * DESCRIPTION: + * + * Retrieves a pointer to a PKIX_UInt32 representing the maximum logging + * level of the Logger pointed to by "logger" and stores it at "pLevel". Only + * log entries whose log level is less than or equal to this maximum logging + * level will be logged. + * + * PARAMETERS: + * "logger" + * Address of Logger whose maximum logging level is to be stored. + * Must be non-NULL. + * "pLevel" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_GetMaxLoggingLevel( + PKIX_Logger *logger, + PKIX_UInt32 *pLevel, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_SetMaxLoggingLevel + * DESCRIPTION: + * + * Sets the maximum logging level of the Logger pointed to by "logger" with + * the integer value of "level". + * + * PARAMETERS: + * "logger" + * Address of Logger whose maximum logging level is to be set. + * Must be non-NULL. + * "level" + * Maximum logging level to be set + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "logger" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_SetMaxLoggingLevel( + PKIX_Logger *logger, + PKIX_UInt32 level, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_GetLoggingComponent + * DESCRIPTION: + * + * Retrieves a pointer to a String representing the logging component of the + * Logger pointed to by "logger" and stores it at "pComponent". Only log + * entries whose log component matches the specified logging component will + * be logged. + * + * PARAMETERS: + * "logger" + * Address of Logger whose logging component is to be stored. + * Must be non-NULL. + * "pComponent" + * Address where PKIXERRORNUM will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_GetLoggingComponent( + PKIX_Logger *logger, + PKIX_ERRORCLASS *pComponent, + void *plContext); + +/* + * FUNCTION: PKIX_Logger_SetLoggingComponent + * DESCRIPTION: + * + * Sets the logging component of the Logger pointed to by "logger" with the + * PKIXERRORNUM pointed to by "component". To match a small set of components, + * create a Logger for each. + * + * PARAMETERS: + * "logger" + * Address of Logger whose logging component is to be set. + * Must be non-NULL. + * "component" + * PKIXERRORNUM value representing logging component to be set. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "logger" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Logger_SetLoggingComponent( + PKIX_Logger *logger, + PKIX_ERRORCLASS component, + void *plContext); + +/* + * FUNCTION: PKIX_GetLoggers + * DESCRIPTION: + * + * Retrieves a pointer to the List of Loggers (if any) being used for logging + * by libpkix and stores it at "pLoggers". If no loggers are being used, this + * function stores an empty List at "pLoggers". + * + * Note that the List returned by this function is immutable. + * + * PARAMETERS: + * "pLoggers" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_GetLoggers( + PKIX_List **pLoggers, /* list of PKIX_Logger */ + void *plContext); + +/* + * FUNCTION: PKIX_SetLoggers + * DESCRIPTION: + * + * Sets the Loggers to be used by libpkix to the List of Loggers pointed to + * by "loggers". If "loggers" is NULL, no Loggers will be used. + * + * PARAMETERS: + * "loggers" + * Address of List of Loggers to be set. NULL for no Loggers. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_SetLoggers( + PKIX_List *loggers, /* list of PKIX_Logger */ + void *plContext); + +/* + * FUNCTION: PKIX_AddLogger + * DESCRIPTION: + * + * Adds the Logger pointed to by "logger" to the List of Loggers used by + * libpkix. + * + * PARAMETERS: + * "logger" + * Address of Logger to be added. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Logger Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_AddLogger( + PKIX_Logger *logger, + void *plContext); + +/* Functions pertaining to the PKIX_Error type */ + +/* Error + * + * An Error object is returned by a function upon encountering some error + * condition. Each Error is associated with an errorCode specified in pkixt.h. + * The remaining components of an Error are optional. An Error's description + * specifies a text message describing the Error. An Error's supplementary info + * specifies additional information that might be useful. Finally, an Error's + * cause specifies the underlying Error (if any) that resulted in this Error + * being returned, thereby allowing Errors to be chained so that an entire + * "error stack trace" can be represented. Once created, an Error is immutable. + * + * Note that the Error's supplementary info must be an Object (although any + * object type), allowing it to be reference-counted and allowing it to + * provide the standard Object functions (Equals, Hashcode, ToString, Compare, + * Duplicate). + * + * Errors are classified as either being fatal or non-fatal. If a function + * fails in an unrecoverable way, it returns an Error whose errorCode is + * PKIX_FATAL_ERROR. If such an error is encountered, the caller should + * not attempt to recover since something seriously wrong has happened + * (e.g. corrupted memory, memory finished, etc.). All other errorCodes + * are considered non-fatal errors and can be handled by the caller as they + * see fit. + */ + +/* + * FUNCTION: PKIX_Error_Create + * DESCRIPTION: + * + * Creates a new Error using the value of "errorCode", the Error pointed to by + * "cause" (if any), the Object pointed to by "info" (if any), and the String + * pointed to by "desc" and stores it at "pError". If any error occurs during + * error allocation, it will be returned without chaining, since new errors + * cannot be created. Once created, an Error is immutable. + * + * PARAMETERS: + * "errorCode" + * Value of error code. + * "cause" + * Address of Error representing error's cause. + * NULL if none or unspecified. + * "info" + * Address of Object representing error's supplementary information. + * NULL if none. + * "desc" + * Address of String representing error's description. NULL if none. + * "pError" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_Create( + PKIX_ERRORCLASS errClass, + PKIX_Error *cause, + PKIX_PL_Object *info, + PKIX_ERRORCODE errCode, + PKIX_Error **pError, + void *plContext); + +/* + * FUNCTION: PKIX_Error_GetErrorClass + * DESCRIPTION: + * + * Retrieves the error class of the Error pointed to by "error" and + * stores it at "pClass". Supported error codes are defined in pkixt.h. + * + * PARAMETERS: + * "error" + * Address of Error whose error code is desired. Must be non-NULL. + * "pClass" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_GetErrorClass( + PKIX_Error *error, + PKIX_ERRORCLASS *pClass, + void *plContext); + +/* + * FUNCTION: PKIX_Error_GetErrorCode + * DESCRIPTION: + * + * Retrieves the error code of the Error pointed to by "error" and + * stores it at "pCode". Supported error codes are defined in pkixt.h. + * + * PARAMETERS: + * "error" + * Address of Error whose error code is desired. Must be non-NULL. + * "pCode" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_GetErrorCode( + PKIX_Error *error, + PKIX_ERRORCODE *pCode, + void *plContext); + +/* + * FUNCTION: PKIX_Error_GetCause + * DESCRIPTION: + * + * Retrieves the cause of the Error pointed to by "error" and stores it at + * "pCause". If no cause was specified, NULL will be stored at "pCause". + * + * PARAMETERS: + * "error" + * Address of Error whose cause is desired. Must be non-NULL. + * "pCause" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_GetCause( + PKIX_Error *error, + PKIX_Error **pCause, + void *plContext); + +/* + * FUNCTION: PKIX_Error_GetSupplementaryInfo + * DESCRIPTION: + * + * Retrieves the supplementary info of the Error pointed to by "error" and + * stores it at "pInfo". + * + * PARAMETERS: + * "error" + * Address of Error whose info is desired. Must be non-NULL. + * "pInfo" + * Address where info pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_GetSupplementaryInfo( + PKIX_Error *error, + PKIX_PL_Object **pInfo, + void *plContext); + +/* + * FUNCTION: PKIX_Error_GetDescription + * DESCRIPTION: + * + * Retrieves the description of the Error pointed to by "error" and stores it + * at "pDesc". If no description was specified, NULL will be stored at + * "pDesc". + * + * PARAMETERS: + * "error" + * Address of Error whose description is desired. Must be non-NULL. + * "pDesc" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Error Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Error_GetDescription( + PKIX_Error *error, + PKIX_PL_String **pDesc, + void *plContext); + +/* PKIX_List + * + * Represents a collection of items. NULL is considered a valid item. + */ + +/* + * FUNCTION: PKIX_List_Create + * DESCRIPTION: + * + * Creates a new List and stores it at "pList". The List is initially empty + * and holds no items. To initially add items to the List, use + * PKIX_List_AppendItem + * + * PARAMETERS: + * "pList" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_Create( + PKIX_List **pList, + void *plContext); + +/* + * FUNCTION: PKIX_List_SetImmutable + * DESCRIPTION: + * + * Sets the List pointed to by "list" to be immutable. If a caller tries to + * change a List after it has been marked immutable (i.e. by calling + * PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or + * PKIX_List_DeleteItem), an Error is returned. + * + * PARAMETERS: + * "list" + * Address of List to be marked immutable. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "list" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_SetImmutable( + PKIX_List *list, + void *plContext); + +/* + * FUNCTION: PKIX_List_IsImmutable + * DESCRIPTION: + * + * Checks whether the List pointed to by "list" is immutable and stores + * the Boolean result at "pImmutable". If a caller tries to change a List + * after it has been marked immutable (i.e. by calling PKIX_List_AppendItem, + * PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an + * Error is returned. + * + * PARAMETERS: + * "list" + * Address of List whose immutability is to be determined. + * Must be non-NULL. + * "pImmutable" + * Address where PKIX_Boolean will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_IsImmutable( + PKIX_List *list, + PKIX_Boolean *pImmutable, + void *plContext); + +/* + * FUNCTION: PKIX_List_GetLength + * DESCRIPTION: + * + * Retrieves the length of the List pointed to by "list" and stores it at + * "pLength". + * + * PARAMETERS: + * "list" + * Address of List whose length is desired. Must be non-NULL. + * "pLength" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_GetLength( + PKIX_List *list, + PKIX_UInt32 *pLength, + void *plContext); + +/* + * FUNCTION: PKIX_List_IsEmpty + * DESCRIPTION: + * + * Checks whether the List pointed to by "list" is empty and stores + * the Boolean result at "pEmpty". + * + * PARAMETERS: + * "list" + * Address of List whose emptiness is to be determined. Must be non-NULL. + * "pEmpty" + * Address where PKIX_Boolean will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_IsEmpty( + PKIX_List *list, + PKIX_Boolean *pEmpty, + void *plContext); + +/* + * FUNCTION: PKIX_List_AppendItem + * DESCRIPTION: + * + * Appends the Object pointed to by "item" after the last non-NULL item in + * List pointed to by "list", if any. Note that a List may validly contain + * NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result + * in ("a", NULL, "b", "c"). + * + * PARAMETERS: + * "list" + * Address of List to append to. Must be non-NULL. + * "item" + * Address of new item to append. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "list" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_AppendItem( + PKIX_List *list, + PKIX_PL_Object *item, + void *plContext); + +/* + * FUNCTION: PKIX_List_InsertItem + * DESCRIPTION: + * + * Inserts the Object pointed to by "item" into the List pointed to by "list" + * at the given "index". The index counts from zero and must be less than the + * List's length. Existing list entries at or after this index will be moved + * to the next highest index. + * + * XXX why not allow equal to length which would be equivalent to AppendItem? + * + * PARAMETERS: + * "list" + * Address of List to insert into. Must be non-NULL. + * "index" + * Position to insert into. Must be less than List's length. + * "item" + * Address of new item to append. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "list" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_InsertItem( + PKIX_List *list, + PKIX_UInt32 index, + PKIX_PL_Object *item, + void *plContext); + +/* + * FUNCTION: PKIX_List_GetItem + * DESCRIPTION: + * + * Copies the "list"'s item at "index" into "pItem". The index counts from + * zero and must be less than the list's length. Increments the reference + * count on the returned object, if non-NULL. + * + * PARAMETERS: + * "list" + * Address of List to get item from. Must be non-NULL. + * "index" + * Index of list to get item from. Must be less than List's length. + * "pItem" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_GetItem( + PKIX_List *list, + PKIX_UInt32 index, + PKIX_PL_Object **pItem, + void *plContext); + +/* + * FUNCTION: PKIX_List_SetItem + * DESCRIPTION: + * + * Sets the item at "index" of the List pointed to by "list" with the Object + * pointed to by "item". The index counts from zero and must be less than the + * List's length. The previous entry at this index will have its reference + * count decremented and the new entry will have its reference count + * incremented. + * + * PARAMETERS: + * "list" + * Address of List to modify. Must be non-NULL. + * "index" + * Position in List to set. Must be less than List's length. + * "item" + * Address of Object to set at "index". + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "list" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_SetItem( + PKIX_List *list, + PKIX_UInt32 index, + PKIX_PL_Object *item, + void *plContext); + +/* + * FUNCTION: PKIX_List_DeleteItem + * + * Deletes the item at "index" from the List pointed to by "list". The index + * counts from zero and must be less than the List's length. Note that this + * function does not destroy the List. It simply decrements the reference + * count of the item at "index" in the List, deletes that item from the list + * and moves all subsequent entries to a lower index in the list. If there is + * only a single element in the List and that element is deleted, then the + * List will be empty. + * + * PARAMETERS: + * "list" + * Address of List to delete from. Must be non-NULL. + * "index" + * Position in List to delete. Must be less than List's length. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "list" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_DeleteItem( + PKIX_List *list, + PKIX_UInt32 index, + void *plContext); + +/* + * FUNCTION: PKIX_List_ReverseList + * DESCRIPTION: + * + * Creates a new List whose elements are in the reverse order as the elements + * of the Object pointed to by "list" and stores the copy at "pReversedList". + * If "list" is empty, the new reversed List will be a copy of "list". + * Changes to the new object will not affect the original and vice versa. + * + * PARAMETERS: + * "list" + * Address of List whose elements are to be reversed. Must be non-NULL. + * "pReversedList" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_List_ReverseList( + PKIX_List *list, + PKIX_List **pReversedList, + void *plContext); + +#ifdef __cplusplus +} +#endif + +#endif /* _PKIX_UTIL_H */ |