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

#ifndef PS_ERROR_CODES_H
#define PS_ERROR_CODES_H

#include "psType.h"

/* N.B., lines between '//~Start' and '//~End' are automatic generated from
 * the template following the '//~Start'.  The template is used to generate
 * the other lines by, for each error class in psErrorCodes.dat, the following
 * substitutions are made:
 *     $1  The error code name (first word in the psErrorCodes.dat lines)
 *     $2  The error description (rest of the line in psErrorCodes.dat)
 *     $n  The order of the source line in psErrorCodes.dat (comments excluded)
 * 
 * DO NOT EDIT THE LINES BETWEEN //~Start and //~End!  ANY CHANGES WILL BE OVERWRITTEN.
 */

/** @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
     */

    //~Start     PS_ERR_$1,   ///< $2
    PS_ERR_UNKNOWN,   ///< unknown error
    PS_ERR_IO,   ///< I/O error
    PS_ERR_LOCATION_INVALID,   ///< specified location is unknown
    PS_ERR_MEMORY_CORRUPTION,   ///< memory corruption detected
    PS_ERR_MEMORY_DEREF_USAGE,   ///< dereferenced memory still used
    PS_ERR_BAD_PARAMETER_VALUE,   ///< parameter is out-of-range
    PS_ERR_BAD_PARAMETER_TYPE,   ///< parameter is of unsupported type
    PS_ERR_BAD_PARAMETER_NULL,   ///< parameter is null
    PS_ERR_BAD_PARAMETER_SIZE,   ///< size of parameter's data is outside of acceptable range.
    PS_ERR_UNEXPECTED_NULL,   ///< unexpected NULL found
    PS_ERR_OS_CALL_FAILED,   ///< unexpected result from an OS standard library call
    //~End
    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
