mi32/errhandler.h

Go to the documentation of this file.

/**
 * \file mi32/errhandler.h
 * \brief Error reporting and handling functions
 *
 * \if NODOC
 * $Id: errhandler.h_v 1.3 2005/06/24 19:10:08 mju Exp $
 *
 * $Log: errhandler.h_v $
 * Revision 1.3  2005/06/24 19:10:08  mju
 * Fix comment at end.
 *
 * Revision 1.2  2005/06/22 15:38:15  mju
 * Adjust comment.
 *
 * Revision 1.1  2005/06/22 15:26:11  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_ERRHANDLER_H
#define  INC_MI32_ERRHANDLER_H

#ifndef  INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#ifdef MISYSTEMDLL
   #define LIBEXPORT MI_DLLEXPORT
#else
   #define LIBEXPORT MI_DLLIMPORT
#endif


#ifdef   __cplusplus
class MISTRING;
#endif

//!\addtogroup ErrorPosn Error Reporting Functions
//!@{

#ifndef GENERATING_DOXYGEN_OUTPUT
#if defined(__cplusplus)
extern "C" {
#endif
#endif

//! Clear the last reported error and the error stack.
LIBEXPORT void ClearLastErr (void);

//! Get the details string set by SetErrDetails().
//! Do not free the returned string.
LIBEXPORT const MIUNICODE* GetErrDetails ();

#if defined(__cplusplus) 

//! Get MISTRING reference to current error message.
//! This allows subsequent use of the << operator on the string to substitute
//! or append additional error values for %-format or $-position codes.
LIBEXPORT MISTRING& GetErrString (
   );

//! Get the last error message (Unicode).
//! Do not free the returned string.
LIBEXPORT const MIUNICODE* GetErrStrUC (
   ERRVALUE errcode,                   //!< Error code to retrieve string for
   int *errlevel = 0                   //!< Error level returned (NULL if don't care)
   );


//! Get the first line of the last error message (Unicode).
//! Do not free the returned string.
LIBEXPORT const MIUNICODE* GetErrStrLine1UC (
   ERRVALUE errcode,                   //!< Error code to retrieve string for
   int *errlevel = 0                   //!< Error level returned (NULL if don't care)
   );

//! Determine if error position recording is disabled.
//! @return true if disabled, false if not.
LIBEXPORT bool IsErrPosnDisabled ();

#else
#ifndef GENERATING_DOXYGEN_OUTPUT
//! Version of above without default parameter for 3rd party libs
//! that don't compile with C++ but that we still have to patch
//! to use Mio

LIBEXPORT const MIUNICODE* GetErrStrUC (
   ERRVALUE errcode,                   //!< Error code to retrieve string for
   int *errlevel                       //!< Error level returned (NULL if don't care)
   );

LIBEXPORT const MIUNICODE* GetErrStrLine1UC (
   ERRVALUE errcode,                   //!< Error code to retrieve string for
   int *errlevel                       //!< Error level returned (NULL if don't care)
   );

#endif // GENERATING_DOXYGEN_OUTPUT
#endif

//! Get last error code.
LIBEXPORT ERRVALUE GetLastErrCode ();

//! Set the details string for an error.  
//! This can be used to report any extra details about an error.
//! If set, the standard error dialog will have a "detial..." button
//! which will let the user see the details.
LIBEXPORT void SetErrDetails (
   const MIUNICODE*
   );

#ifndef GENERATING_DOXYGEN_OUTPUT
LIBEXPORT int _SetErrPosn (int, const char*, int);
LIBEXPORT int _SetErrPosnC (int, const char*, int);
#endif // GENERATING_DOXYGEN_OUTPUT

//! Record an error code and it's position.
//!
//! Note, this is really a macro which calls an internal function
//! and also passes it RCSID and __LINE__
//! For this to work, the following line must exist near the top
//! of the module (just below the main comment block)
//! @code
//!    #define RCSID "$Id: errhandler.h_v 1.3 2005/06/24 19:10:08 mju Exp $"
//! @endcode
//!
//! Note: The example above shows what the RCSID for this include file looks
//! like. If you're using RCS, it will fill in everything between the <tt>Id:</tt> and the <tt>$</tt>.
//! The actual source module will be specific to the file in which RCSID is defined, and
//! will be extracted from the RCSID string along with the revision number and date for
//! display in error traces.
#define  SetErrPosn(e)  _SetErrPosn(e,RCSID,__LINE__)

//! Clear current error stack and set error position.
//!
//! Same as SetErrPosn(), but clears the error stack first.
//!
//! @see SetErrPosn()
#define  SetErrPosnC(e) _SetErrPosnC(e,RCSID,__LINE__)


//! Set the current error position and goto Error label.
//!
//! Note, This is really a #define macro.
//!
//! It does the same thing as SetErrPosn(), then does a 
//! <tt>goto Error;</tt> 
#define  SetErrPosnGoto(e)    { err=SetErrPosn(e); goto Error; }

//! Clear the error stack, set the current error position and goto Error label.
//!
//! Note, This is really a #define macro.
//! It does the same thing as SetErrPosnC(), then does a 
//! <tt>goto Error;</tt> 
#define  SetErrPosnGotoC(e)   { err=SetErrPosnC(e); goto Error; }


//! Disable error position reporting.
//!
//! This is important when cleaning up after an error.  It often happens that
//! if you get an error, you need to cleanup (close files, etc) before returning.
//! If something in your cleanup code also causes an error, it will wipe out
//! the error trace that you're trying to report.  Therefore, always bracket
//! cleanup code with SetErrPosnDiaable()/SetErrPosnEnable().
LIBEXPORT void SetErrPosnDisable (void);

//! Reenable error position reporting.
//!
//! @see SetErrPosnDisable()
LIBEXPORT void SetErrPosnEnable (void);

#if defined(__cplusplus)
}                       
#endif

//!@}


#if defined(__cplusplus)
//! Sentry class to disable and enable error positioning using this class and scoping
class ERRORPOSNDISABLE {
   public:
      ERRORPOSNDISABLE (
         ) { SetErrPosnDisable(); }
      
      ~ERRORPOSNDISABLE (
         ) { SetErrPosnEnable(); }
   };

#endif

#undef LIBEXPORT

#endif   // INC_MI32_ERRHANDLER_H

---