Error handling

When an error occurs inside a module, the function should call CSSM_SetError. The CSSM_SetError function takes the module's GUID and an error number as inputs. The module's GUID is used to identify where the error occurred. The error number is used to describe the error.

The error number set by a module subservice should fall into one of two ranges. The first range of error numbers is predefined by OCSF. These are errors that are common to all modules implementing a given subservice function. They are defined in the header file, cssmerr.h, which is distributed as part of OCSF. The second range of error numbers is used to define module-specific error codes. These module-specific error codes should be in the range of CSSM_XX_PRIVATE_ERROR to CSSM_xx_END_ERROR, where XX stands for the service abbreviation (CSP, TP, CL, DL). CSSM_XX_PRIVATE_ERROR and CSSM_XX_END_ERROR are also defined in the header file cssmerr.h. A module developer is responsible for making the definition and interpretation of their module-specific error codes available to applications.

When no error has occurred, but the appropriate return value from a function is CSSM_FALSE, that function should call CSSM_ClearError before returning. When the application receives a CSSM_FALSE return value, it is responsible for checking whether an error has occurred by calling CSSM_GetError. If the module function has called CSSM_ClearError, the calling application receives a CSSM_OK response from the CSSM_GetError function, indicating no error has occurred.