/** @file  psErrorCodes.h
 *
 *  @brief Contains the error codes for the error classes
 *
 *  @ingroup ErrorHandling
 *
 *  @author Robert DeSonia, MHPCC
 *
 *  @version $Revision: 1.1 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2005-07-12 19:12:01 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_ERROR_CODES_H
#define PS_ERROR_CODES_H

#include "psType.h"

/** @addtogroup ErrorHandling
 *  @{
 */

/** enumeration of the static error code classes
 */
typedef enum {
    PS_ERR_NONE = 0,                   ///< not an error
    PS_ERR_BASE = 256,
    /**< base error.  Any psErrorCode less than this should be taken to be
     *   valid values of errno
     */
    PS_ERR_${ErrorCode},
    PS_ERR_N_ERR_CLASSES               ///< end marker - should not be used as a true error
} psErrorCode;

/** An error code with description
 */
typedef struct
{
    psErrorCode code;                  ///< An error code
    const char *description;           ///< the associated description
}
psErrorDescription;

/** Allocates a new psErrorDescription
 *
 *  @return psErrorDescription*        new psErrorDescription struct.
 */
psErrorDescription* psErrorDescriptionAlloc(
    psErrorCode code,                  ///< An error code
    const char *description            ///< the associated description
);

/** Retrieves the description of an error code.
 *
 *  The routine psErrorCodeString returns the string associated with an error
 *  code.
 *
 *  @return const char*     the description associated with the given code.
 */
const char *psErrorCodeString(
    psErrorCode code                   ///< the associated error code
);

/** Register an error code
 *
 *  Any project needed to use psLib must define the necessary error codes and
 *  associated message strings.  This function registers an array of error
 *  codes with the error handling subsystem.
 *
 */
void psErrorRegister(
    const psErrorDescription* errors,  ///< Array of error codes to register
    psS32 nerror                         ///< number of errors in input array
);

/** Clears error codes registered via psErrorRegister.
 *
 *  @return psBool    TRUE if given errorcode was removed, otherwise FALSE.
 */
psBool p_psErrorUnregister(
    psErrorCode code                   ///< the error code to find and remove
);

/// @}

#endif // #ifndef PS_ERROR_CODES_H
