This describes the error handling features in OCSF that provide a consistent mechanism across all layers of OCSF for returning errors to the caller. All OCSF API functions return one of these:

• CSSM_RETURN - An enumerated type consisting of CSSM_OK and CSSM_FAIL. If it is CSSM_FAIL, an error code indicating the reason for failure can be obtained by calling CSSM_GetError.
• CSSM_BOOL - OCSF functions returning this data type return either CSSM_TRUE or CSSM_FALSE. If the function returns CSSM_FALSE, an error code may be available (but not always) by calling CSSM_GetError.
• A pointer to a data structure, a handle, a file size, or whatever is logical for the function to return. An error code may be available (but not always) by calling CSSM_GetError.

The information returned from CSSM_GetError includes both the error number and a Globally Unique ID (GUID) that associates the error with the module that set it. The GUID of each module can be obtained by calling CSSM_ListModules. CSSM_CompareGuids can then be called to determine from which module an error came.

Each module must have a mechanism for reporting their errors to the calling application. In general, there are two types of errors a module can return:

Errors defined by OCSF that are common to a particular type of service provider module Errors reserved for use by individual service provider modules

Since some errors are predefined by OCSF, those errors have a set of predefined numeric values that are reserved by OCSF and cannot be redefined by modules. For errors that are particular to a module, a different set of predefined values has been reserved for their use. Table 39 lists the range of error numbers defined for OCSF and service provider modules. OCSF Errors lists the errors defined by OCSF.

The calling application must determine how to handle the error returned by CSSM_GetError. Detailed descriptions of the error values will be available in the corresponding specification, the cssmerr.h header file, and the information for specific modules. If a routine does not know how to handle the error, it may choose to pass the error to its caller.

Error values returned by a function should not be overwritten, if at all possible. For example, if a CSP call returns an error indicating that it could not encrypt the data, the caller should not overwrite it with an error simply indicating that the CSP failed, as it destroys valuable error handling and debugging information. However, after processing an error, the application should reset the error to zero using CSSM_ClearError, in order to prevent the error from being handled again later.

Errors are kept on a thread basis, and each error API affects only the current thread's error information.