ncbidiag.hpp

ncbi源码

/// SDiagErrCodeDescription --
///
/// Structure used to store the errors code and subcode description.

struct NCBI_XNCBI_EXPORT SDiagErrCodeDescription {
    /// Constructor.
    SDiagErrCodeDescription(void);

    /// Destructor.
    SDiagErrCodeDescription(const string& message,     ///< Message
                            const string& explanation, ///< Explanation of msg.
                            int           severity = -1
                                                       ///< Do not override
                                                       ///< if set to -1
                           )
        : m_Message(message),
          m_Explanation(explanation),
          m_Severity(severity)
    {
        return;
    }

public:
    string m_Message;     ///< Error message (short)
    string m_Explanation; ///< Error message (with detailed explanation)
    int    m_Severity;    
                          ///< Message severity (if less that 0, then use
                          ///< current diagnostic severity level)
};



/////////////////////////////////////////////////////////////////////////////
///
/// CDiagErrCodeInfo --
///
/// Stores mapping of error codes and their descriptions.

class NCBI_XNCBI_EXPORT CDiagErrCodeInfo
{
public:
    /// Constructor.
    CDiagErrCodeInfo(void);

    /// Constructor -- can throw runtime_error.
    CDiagErrCodeInfo(const string& file_name);  

    /// Constructor -- can throw runtime_error.
    CDiagErrCodeInfo(CNcbiIstream& is);

    /// Destructor.
    ~CDiagErrCodeInfo(void);

    /// Read error description from specified file.
    ///
    /// Read error descriptions from the specified file,
    /// store it in memory.
    bool Read(const string& file_name);

    /// Read error description from specified stream.
    ///
    /// Read error descriptions from the specified stream,
    /// store it in memory.
    bool Read(CNcbiIstream& is);
    
    /// Delete all stored error descriptions from memory.
    void Clear(void);

    /// Get description for specified error code.
    ///
    /// Get description message for the error by its code.
    /// @return
    ///   TRUE if error description exists for this code;
    ///   return FALSE otherwise.
    bool GetDescription(const ErrCode&           err_code, 
                        SDiagErrCodeDescription* description) const;

    /// Set error description for specified error code.
    ///
    /// If description for this code already exist, then it
    /// will be overwritten.
    void SetDescription(const ErrCode&                 err_code, 
                        const SDiagErrCodeDescription& description);

    /// Check if error description exists.
    ///
    ///  Return TRUE if description for specified error code exists, 
    /// otherwise return FALSE.
    bool HaveDescription(const ErrCode& err_code) const;

private:

    /// Define map for error messages.
    typedef map<ErrCode, SDiagErrCodeDescription> TInfo;

    /// Map storing error codes and descriptions.
    TInfo m_Info;
};



/// Diagnostic message file.
#define DIAG_MESSAGE_FILE "MessageFile"

/// Set handler for processing error codes.
///
/// By default this handler is unset. 
/// NcbiApplication can init itself only if registry key DIAG_MESSAGE_FILE
/// section DEBUG) is specified. The value of this key should be a name 
/// of the file with the error codes explanations.
/// @sa
///   http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/programming_manual/diag.html#errcodes
NCBI_XNCBI_EXPORT
extern void SetDiagErrCodeInfo(CDiagErrCodeInfo* info,
                               bool              can_delete = true);

/// Indicates whether an error-code processing handler has been set.
NCBI_XNCBI_EXPORT
extern bool IsSetDiagErrCodeInfo();

/// Get handler for processing error codes.
NCBI_XNCBI_EXPORT
extern CDiagErrCodeInfo* GetDiagErrCodeInfo(bool take_ownership = false);


/* @} */


///////////////////////////////////////////////////////
// All inline function implementations and internal data
// types, etc. are in this file

#include <corelib/ncbidiag.inl>


END_NCBI_SCOPE




/*
 * ==========================================================================
 *
 * $Log: ncbidiag.hpp,v $
 * Revision 1000.4  2004/06/01 19:07:58  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.72
 *
 * Revision 1.72  2004/04/26 19:28:24  ucko
 * Make previous change compiler-dependent due to MSVC bugginess.
 *
 * Revision 1.71  2004/04/26 14:35:47  ucko
 * Move CNcbiDiag::operator<< to ncbidiag.inl to make GCC 3.4 happy.
 *
 * Revision 1.70  2004/03/18 20:19:48  gouriano
 * make it possible to convert multi-line diagnostic message into single-line
 *
 * Revision 1.69  2004/03/16 15:35:19  vasilche
 * Added LOG_POST_ONCE and ERR_POST_ONCE macros
 *
 * Revision 1.68  2004/03/12 21:16:56  gorelenk
 * Added NCBI_XNCBI_EXPORT to member-function SetFile of class CNcbiDiag.
 *
 * Revision 1.67  2004/03/10 18:40:21  gorelenk
 * Added/Removed NCBI_XNCBI_EXPORT prefixes.
 *
 * Revision 1.66  2004/03/10 17:34:05  gorelenk
 * Removed NCBI_XNCBI_EXPORT prefix for classes members-functions
 * that are implemented as a inline functions.
 *
 * Revision 1.65  2004/01/28 14:49:04  ivanov
 * Added export specifier to SDiagErrCodeDescription
 *
 * Revision 1.64  2004/01/27 17:04:10  ucko
 * Don't attempt to declare references as mutable -- the referents are fixed,
 * and one can always change their contents through any non-const reference.
 * (IBM's VisualAge compiler forbids such declarations.)
 * Add missing declarations for SetDiagFixedPostLevel and IsSetDiagErrCodeInfo.
 *
 * Revision 1.63  2003/11/12 20:30:25  ucko
 * Make extra flags for severity-trace messages tunable.
 *
 * Revision 1.62  2003/11/07 13:04:45  ivanov
 * Added export specifier for SDiagMessage
 *
 * Revision 1.61  2003/11/06 21:40:34  vakatov
 * A somewhat more natural handling of the 'eDPF_Default' flag -- replace
 * it by the current global flags, then merge these with other flags (if any)
 *
 * Revision 1.60  2003/08/01 14:16:27  siyan
 * Fixed error in CDiagFactory documentation.
 *
 * Revision 1.59  2003/07/21 18:42:29  siyan
 * Documentation changes.
 *
 * Revision 1.58  2003/04/25 20:52:34  lavr
 * Introduce draft version of IgnoreDiagDieLevel()
 *
 * Revision 1.57  2003/04/25 16:00:03  vakatov
 * Document an ugly, absolutely not recommended for use, very special case
 * for SetDiagDieLevel() which prevents the application from exiting when
 * an error with FATAL severity is posted.
 *
 * Revision 1.56  2003/04/11 17:55:44  lavr
 * Proper indentation of some fragments
 *
 * Revision 1.55  2003/03/31 15:36:51  siyan
 * Added doxygen support
 *
 * Revision 1.54  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.53  2002/09/24 18:28:20  vasilche
 * Fixed behavour of CNcbiDiag::DiagValidate() in release mode
 *
 * Revision 1.52  2002/09/19 20:05:41  vasilche
 * Safe initialization of static mutexes
 *
 * Revision 1.51  2002/09/16 20:49:06  vakatov
 * Cosmetics and comments
 *
 * Revision 1.50  2002/08/20 19:13:09  gouriano
 * added DiagWriteFlags into SDiagMessage::Write
 *
 * Revision 1.49  2002/08/16 15:02:50  ivanov
 * Added class CDiagAutoPrefix
 *
 * Revision 1.48  2002/08/01 18:48:07  ivanov
 * Added stuff to store and output error verbose messages for error codes
 *
 * Revision 1.47  2002/07/15 18:17:50  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.46  2002/07/10 16:18:42  ivanov
 * Added CNcbiDiag::StrToSeverityLevel().
 * Rewrite and rename SetDiagFixedStrPostLevel() -> SetDiagFixedPostLevel()
 *
 * Revision 1.45  2002/07/09 16:38:00  ivanov
 * Added GetSeverityChangeEnabledFirstTime().
 * Fix usage forced set severity post level from environment variable
 * to work without NcbiApplication::AppMain()
 *
 * Revision 1.44  2002/07/02 18:26:08  ivanov
 * Added CDiagBuffer::DisableDiagPostLevelChange()
 *
 * Revision 1.43  2002/06/26 18:36:37  gouriano
 * added CNcbiException class
 *
 * Revision 1.42  2002/04/23 19:57:25  vakatov
 * Made the whole CNcbiDiag class "mutable" -- it helps eliminate
 * numerous warnings issued by SUN Forte6U2 compiler.
 * Do not use #NO_INCLASS_TMPL anymore -- apparently all modern
 * compilers seem to be supporting in-class template methods.
 *
 * Revision 1.41  2002/04/16 18:38:02  ivanov
 * SuppressDiagPopupMessages() moved to "test/test_assert.h"
 *
 * Revision 1.40  2002/04/11 20:39:16  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.39  2002/04/11 19:58:03  ivanov
 * Added function SuppressDiagPopupMessages()
 *
 * Revision 1.38  2002/04/10 14:45:04  ivanov
 * Abort() moved from static to extern and added to header file
 *
 * Revision 1.37  2002/04/01 22:34:35  ivanov
 * Added SetAbortHandler() function to set user abort handler
 *
 * Revision 1.36  2002/02/07 19:45:53  ucko
 * Optionally transfer ownership in GetDiagHandler.
 *
 * Revision 1.35  2001/11/14 15:14:58  ucko
 * Revise diagnostic handling to be more object-oriented.
 *
 * Revision 1.34  2001/10/29 15:37:29  ucko
 * Rewrite dummy new/delete bodies to avoid GCC warnings.
 *
 * Revision 1.33  2001/10/29 15:25:55  ucko
 * Give (prohibited) CDiagRestorer::new/delete dummy bodies.
 *
 * Revision 1.32  2001/10/29 15:16:11  ucko
 * Preserve default CGI diagnostic settings, even if customized by app.
 *
 * Revision 1.31  2001/10/16 23:44:04  vakatov
 * + SetDiagPostAllFlags()
 *
 * Revision 1.30  2001/08/09 16:24:05  lavr
 * Added eDPF_OmitInfoSev to log message format flags
 *
 * Revision 1.29  2001/07/26 21:28:49  lavr
 * Remove printing DateTime stamp by default
 *
 * Revision 1.28  2001/07/25 19:12:41  lavr
 * Added date/time stamp for message logging
 *
 * Revision 1.27  2001/06/14 03:37:28  vakatov
 * For the ErrCode manipulator, use CNcbiDiag:: method rather than a friend
 *
 * Revision 1.26  2001/06/13 23:19:36  vakatov
 * Revamped previous revision (prefix and error codes)
 *
 * Revision 1.25  2001/06/13 20:51:52  ivanov
 * + PushDiagPostPrefix(), PopPushDiagPostPrefix() - stack post prefix messages.
 * + ERR_POST_EX, LOG_POST_EX - macros for posting with error codes.
 * + ErrCode(code[,subcode]) - CNcbiDiag error code manipulator.
 * + eDPF_ErrCode, eDPF_ErrSubCode - new post flags.
 *
 * Revision 1.24  2001/05/17 14:50:58  lavr
 * Typos corrected
 *
 * Revision 1.23  2000/11/29 16:58:23  vakatov
 * Added LOG_POST() macro -- to print the posted message only
 *
 * Revision 1.22  2000/10/24 19:54:44  vakatov
 * Diagnostics to go to CERR by default (was -- disabled by default)
 *
 * Revision 1.21  2000/04/18 19:50:10  vakatov
 * Get rid of the old-fashioned C-like "typedef enum {...} E;"
 *
 * Revision 1.20  2000/04/04 22:31:57  vakatov
 * SetDiagTrace() -- auto-set basing on the application
 * environment and/or registry
 *
 * Revision 1.19  2000/03/10 14:17:40  vasilche
 * Added missing namespace specifier to macro.
 *
 * Revision 1.18  2000/02/18 16:54:02  vakatov
 * + eDiag_Critical
 *
 * Revision 1.17  2000/01/20 16:52:29  vakatov
 * SDiagMessage::Write() to replace SDiagMessage::Compose()
 * + operator<<(CNcbiOstream& os, const SDiagMessage& mess)
 * + IsSetDiagHandler(), IsDiagStream()
 *
 * Revision 1.16  1999/12/29 22:30:22  vakatov
 * Use "exit()" rather than "abort()" in non-#_DEBUG mode
 *
 * Revision 1.15  1999/12/28 18:55:24  vasilche
 * Reduced size of compiled object files:
 * 1. avoid inline or implicit virtual methods (especially destructors).
 * 2. avoid std::string's methods usage in inline methods.
 * 3. avoid string literals ("xxx") in inline methods.
 *
 * Revision 1.14  1999/12/27 19:44:15  vakatov
 * Fixes for R1.13:
 * ERR_POST() -- use eDPF_Default rather than eDPF_Trace;  forcibly flush
 * ("<< Endm") the diag. stream. Get rid of the eDPF_CopyFilename, always
 * make a copy of the file name.
 *
 * Revision 1.13  1999/09/27 16:23:20  vasilche
 * Changed implementation of debugging macros (_TRACE, _THROW*, _ASSERT etc),
 * so that they will be much easier for compilers to eat.
 *
 * Revision 1.12  1999/05/04 00:03:06  vakatov
 * Removed the redundant severity arg from macro ERR_POST()
 *
 * Revision 1.11  1999/04/30 19:20:57  vakatov
 * Added more details and more control on the diagnostics
 * See #ERR_POST, EDiagPostFlag, and ***DiagPostFlag()
 *
 * Revision 1.10  1999/03/15 16:08:09  vakatov
 * Fixed "{...}" macros to "do {...} while(0)" lest it to mess up with "if"s
 *
 * Revision 1.9  1999/03/12 18:04:06  vakatov
 * Added ERR_POST macro to perform a plain "standard" error posting
 *
 * Revision 1.8  1998/12/30 21:52:16  vakatov
 * Fixed for the new SunPro 5.0 beta compiler that does not allow friend
 * templates and member(in-class) templates
 *
 * Revision 1.7  1998/12/28 17:56:27  vakatov
 * New CVS and development tree structure for the NCBI C++ projects
 *
 * Revision 1.6  1998/11/06 22:42:37  vakatov
 * Introduced BEGIN_, END_ and USING_ NCBI_SCOPE macros to put NCBI C++
 * API to namespace "ncbi::" and to use it by default, respectively
 * Introduced THROWS_NONE and THROWS(x) macros for the exception
 * specifications
 * Other fixes and rearrangements throughout the most of "corelib" code
 *
 * Revision 1.5  1998/11/04 23:46:35  vakatov
 * Fixed the "ncbidbg/diag" header circular dependencies
 *
 * Revision 1.4  1998/11/03 20:51:24  vakatov
 * Adaptation for the SunPro compiler glitchs(see conf. #NO_INCLASS_TMPL)
 *
 * Revision 1.3  1998/10/30 20:08:20  vakatov
 * Fixes to (first-time) compile and test-run on MSVS++
 *
 * Revision 1.2  1998/10/27 23:06:58  vakatov
 * Use NCBI C++ interface to iostream's
 * ==========================================================================
 */

#endif  /* CORELIB___NCBIDIAG__HPP */