#ifndef _apl_system_errapi_h_
#define _apl_system_errapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Error Handling (ERR)
**
** DESCRIPTION:
**  This file provides methods for handling errors encountered by the
**  various APL interfaces and the application.  The implementation of the 
**  methods are platform dependent.
**
** CONFIGURATION 
** -------------
**  COMPILE:        none.
**                                            
**  APPLICATION:    none.
**
**  PLATFORM:       Data Types:    
**                      PLATFORM_APL_ERRCODE_T
**                      PLATFORM_APL_ERRDATA_T
**
**                  Definitions:
**                      PLATFORM_APL_ERRFATAL_START_OF_APL_PLATFORM_ERRORS
**                      PLATFORM_APL_ERRFATAL_START_OF_APL_ERRORS
**                      PLATFORM_APL_ERRFATAL_START_OF_APPERRORS
**
**  NOTES:
**  1. Unless explicitly stated, NONE of the following methods may be called
**     from interrtup service routines.
**  2. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as macros.
----------------------------------------------------------------------------*/
                    
#include "apl/types/types.h"            /* For: basic types */
#include "apl/system/errcodes.h"        /* For: error code definitions */


/*-------------- MAGIC CONSTANTS -------------------------------------------*/
/** Start of APL platform specific Fatal Error Codes */
#define APL_ERRFATAL_START_OF_APL_PLATFORM_ERRORS   PLATFORM_APL_ERRFATAL_START_OF_APL_PLATFORM_ERRORS  

/** Start of APL general Fatal Error Codes */
#define APL_ERRFATAL_START_OF_APL_ERRORS            PLATFORM_APL_ERRFATAL_START_OF_APL_ERRORS  

/** Start of Application Fatal Error Codes */
#define APL_ERRFATAL_START_OF_APPERRORS             PLATFORM_APL_ERRFATAL_START_OF_APPERRORS  



/*-------------- TYPES -----------------------------------------------------*/
/** Error codes Data type */
#define AplErrCode                          PLATFORM_APL_ERRCODE_T

/** Error data Data type */
#define AplErrData                          PLATFORM_APL_ERRDATA_T


/*-------------- INLINE IMPLEMENTATION -------------------------------------*/
#include "platform/errapi.h"


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method is used to report/handle fatal errors that are detected by
    the application and the APL interfaces including the underlying platform
    implementations. 
    
    This is a callback into the application since ONLY it has the knowledge 
    on what to do with errors.  APL provides a default implementation of
    the interface (platform dependent), but the application can easily 
    provide its own.
    
    The application is allowed to call this method.  The application defines 
    its own error codes starting with APL_ERRFATAL_START_OF_APPERRORS.

    NOTES: 
        o The semantics of this method is that it NEVER returns!
        o Whether or not this method may be called from an interrupt service 
          routine is platform dependent.  See platform implementation and/or
          documentation.  

    Prototype:
        void Apl_fatalError( AplErrCode error );
 */
#define Apl_fatalError                      _Apl_fatalError

/** This method is the same as Apl_fatalError(), except it allows the 
    caller to provide additional error information via the 'xinfo'
    argument.

    Prototype:
        void Apl_fatalErrorWithData( AplErrCode error, AplErrData xinfo );
 */
#define Apl_fatalErrorWithData              _Apl_fatalErrorWithData


/*--------------------------------------------------------------------------*/
#endif  /* end _apl_system_errapi_h_ */