src/external/3rd/library/perforce/include/error.h

   1 /*
   2  * Copyright 1995, 1996 Perforce Software.  All rights reserved.
   3  */
   4
   5 /*
   6  * Error.h - accumulate and report layered errors
   7  *
   8  * Class Defined:
   9  *
  10  *      Error - holder of layered error
  11  *
  12  *          The basic idea of Error is that the top level caller
  13  *          should have one on its stack and hand it by reference
  14  *          down to all lower layers.  If any operation fails, it
  15  *          can add its description of the error to the structure
  16  *          with Set().  After each operation that can potentially
  17  *          fail, the caller should use Test() to check for errors.
  18  *          The top level should do the check and then call Report()
  19  *          if necessary.
  20  *
  21  *          Caveat: All messages now have named parameters, be very
  22  *                  careful not to nest messages that can have the same
  23  *                  parameter name.
  24  *
  25  * Public methods:
  26  *
  27  *      Error::Clear() - clean an Error struct
  28  *      Error::Test() - see if an error is present ( i.e. > E_INFO )
  29  *      Error::IsFatal() - is most severe error fatal?
  30  *      Error::IsWarning() - is most severe error just a warning?
  31  *      Error::IsInfo() - is most severe error just information?
  32  *      Error::GetSeverity() - return ErrorSeverity of most severe error
  33  *      Error::GetGeneric() - return Generic code of most severe error
  34  *
  35  *      Error::operator = - copy Error structs
  36  *
  37  *      Error::Set() - add an error message into an Error struct
  38  *      Error::operator << - add argument to error message
  39  *      Error::Sys() - add a system error message into an Error struct
  40  *      Error::Net() - add a network error message into an Error struct
  41  *
  42  *      Error::GetId() - get an individual Error item
  43  *      Error::Fmt() - format an error message
  44  *
  45  *      Error::Marshall() - pack an Error into a StrBuf/StrDict
  46  *      Error::UnMarshall() - unpack an Error from a StrBuf/StrDict
  47  *
  48  *      Error::Dump() - dump out error struct, for debugging
  49  */
  50
  51 # ifndef __ERROR_H__
  52 # define __ERROR_H__
  53
  54 class StrBuf;
  55 class StrDict;
  56 class StrPtr;
  57 class ErrorPrivate;
  58
  59 /*
  60  * ErrorSeverity - how bad is the error?
  61  */
  62
  63 enum ErrorSeverity {
  64
  65         E_EMPTY = 0,    // nothing yet
  66         E_INFO = 1,     // something good happened
  67         E_WARN = 2,     // something not good happened
  68         E_FAILED = 3,   // user did somthing wrong
  69         E_FATAL = 4     // system broken -- nothing can continue
  70
  71 } ;
  72
  73 /*
  74  * ErrorID - an error code and message
  75  * ErrorOf() - construct an ErrorID from bits
  76  *
  77  *      sev - ErrorSeverity (4 bits)
  78  *      arg - # of arguments, error specific (4 bits)
  79  *      gen - generic error, defined in errornum.h (8 bits)
  80  *      sub - subsystem id, defined in errornum.h (6 bits)
  81  *      cod - code within subsystem, error specific (10 bits)
  82  */
  83
  84 struct ErrorId {
  85         int             code;           // ErrorOf
  86         const char      *fmt;
  87
  88         int     SubCode() const         { return (code >> 0) & 0x3ff; }
  89         int     Subsystem() const       { return (code >> 10) & 0x3f; }
  90         int     Generic() const         { return (code >> 16) & 0xff; }
  91         int     ArgCount() const        { return (code >> 24) & 0x0f; }
  92         int     Severity() const        { return (code >> 28) & 0x0f; }
  93         int     UniqueCode() const      { return code & 0xffff; }
  94
  95 } ;
  96
  97 # define ErrorOf( sub, cod, sev, gen, arg ) \
  98         ((sev<<28)|(arg<<24)|(gen<<16)|(sub<<10)|cod)
  99
 100 enum ErrorFmtOps {
 101         EF_PLAIN = 0x00,        // for info messages
 102         EF_INDENT = 0x01,       // indent each line with \t
 103         EF_NEWLINE = 0x02,      // terminate buffer with \n
 104         EF_NOXLATE = 0x04       // don't use P4LANGUAGE formats
 105 } ;
 106
 107 /*
 108  * class Error - hold layered errors.
 109  */
 110
 111 class Error {
 112
 113     public:
 114                         Error() { ep = 0; severity = E_EMPTY; }
 115                         ~Error();
 116
 117         void            operator =( const Error &source );
 118
 119         void            Clear() { severity = E_EMPTY; }
 120
 121         int             Test() const { return severity > E_INFO; }
 122         int             IsInfo() const { return severity == E_INFO; }
 123         int             IsWarning() const { return severity == E_WARN; }
 124         int             IsError() const { return severity >= E_FAILED; }
 125         int             IsFatal() const { return severity == E_FATAL; }
 126
 127         int             GetSeverity() const { return severity; }
 128         const char *    FmtSeverity() const { return severityText[severity]; }
 129         int             GetGeneric() const { return generic; }
 130
 131         // Set errors, the new way
 132
 133         Error &         Set( const ErrorId &id );
 134
 135         Error &         Set( ErrorSeverity s, const char *fmt )
 136                         {
 137                             ErrorId id;
 138                             id.code = ErrorOf( 0, 0, s, 0, 0 );
 139                             id.fmt = fmt;
 140                             return Set( id );
 141                         }
 142
 143         Error &         operator <<( const StrPtr &arg );
 144         Error &         operator <<( const StrPtr *arg );
 145         Error &         operator <<( const char *arg );
 146         Error &         operator <<( int arg );
 147
 148         // Save system errors
 149
 150         void            Sys( const char *op, const char *arg );
 151         void            Net( const char *op, const char *arg );
 152
 153         // Output
 154
 155         ErrorId *       GetId( int i ) const;
 156
 157         void            Fmt( StrBuf &buf, int opts ) const;
 158         void            Fmt( StrBuf *buf, int opts = EF_NEWLINE ) const
 159                         { Fmt( *buf, opts ); }
 160
 161         // Moving across client/server boundary
 162         // 0 is pre-2002.1
 163         // 1 is 2002.1
 164         // 2 is 2002.1 loopback (not used by client)
 165
 166         void            Marshall0( StrBuf &out );
 167         void            Marshall1( StrDict &out );
 168         void            Marshall2( StrBuf &out );
 169
 170         void            UnMarshall0( const StrPtr &in );
 171         void            UnMarshall1( StrDict &in );
 172         void            UnMarshall2( const StrPtr &in );
 173
 174         // Debugging
 175
 176         void            Dump( const char *trace );
 177
 178     private:
 179
 180         // Remainder is the actual error info
 181
 182         ErrorSeverity   severity;       // of worst error
 183         int             generic;        // of worst error
 184
 185         ErrorPrivate    *ep;            // for actual error data
 186
 187         static const char *severityText[];
 188 } ;
 189
 190 # endif /* __ERROR_H__ */