apt-pkg/contrib/error.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: error.h,v 1.8 2001/05/07 05:06:52 jgg Exp $
   4 /* ######################################################################
   5
   6    Global Erorr Class - Global error mechanism
   7
   8    This class has a single global instance. When a function needs to
   9    generate an error condition, such as a read error, it calls a member
  10    in this class to add the error to a stack of errors.
  11
  12    By using a stack the problem with a scheme like errno is removed and
  13    it allows a very detailed account of what went wrong to be transmitted
  14    to the UI for display. (Errno has problems because each function sets
  15    errno to 0 if it didn't have an error thus eraseing erno in the process
  16    of cleanup)
  17
  18    Several predefined error generators are provided to handle common
  19    things like errno. The general idea is that all methods return a bool.
  20    If the bool is true then things are OK, if it is false then things
  21    should start being undone and the stack should unwind under program
  22    control.
  23
  24    A Warning should not force the return of false. Things did not fail, but
  25    they might have had unexpected problems. Errors are stored in a FIFO
  26    so Pop will return the first item..
  27
  28    I have some thoughts about extending this into a more general UI<->
  29    Engine interface, ie allowing the Engine to say 'The disk is full' in
  30    a dialog that says 'Panic' and 'Retry'.. The error generator functions
  31    like errno, Warning and Error return false always so this is normal:
  32      if (open(..))
  33         return _error->Errno(..);
  34
  35    This source is placed in the Public Domain, do with it what you will
  36    It was originally written by Jason Gunthorpe.
  37
  38    ##################################################################### */
  39                                                                         /*}}}*/
  40 #ifndef PKGLIB_ERROR_H
  41 #define PKGLIB_ERROR_H
  42
  43
  44
  45 #ifdef __GNUG__
  46 // Methods have a hidden this parameter that is visible to this attribute
  47 #define APT_MFORMAT1 __attribute__ ((format (printf, 2, 3)))
  48 #define APT_MFORMAT2 __attribute__ ((format (printf, 3, 4)))
  49 #else
  50 #define APT_MFORMAT1
  51 #define APT_MFORMAT2
  52 #endif
  53
  54 #include <string>
  55 #include <system.h>
  56
  57 using std::string;
  58
  59 class GlobalError
  60 {
  61    struct Item
  62    {
  63       string Text;
  64       bool Error;
  65       Item *Next;
  66    };
  67
  68    Item *List;
  69    bool PendingFlag;
  70    void Insert(Item *I);
  71
  72    public:
  73
  74    // Call to generate an error from a library call.
  75    bool Errno(const char *Function,const char *Description,...) APT_MFORMAT2 __cold;
  76    bool WarningE(const char *Function,const char *Description,...) APT_MFORMAT2 __cold;
  77
  78    /* A warning should be considered less severe than an error, and may be
  79       ignored by the client. */
  80    bool Error(const char *Description,...) APT_MFORMAT1 __cold;
  81    bool Warning(const char *Description,...) APT_MFORMAT1 __cold;
  82
  83    // Simple accessors
  84    inline bool PendingError() {return PendingFlag;};
  85    inline bool empty() {return List == 0;};
  86    bool PopMessage(string &Text);
  87    void Discard();
  88
  89    // Usefull routine to dump to cerr
  90    void DumpErrors();
  91
  92    GlobalError();
  93 };
  94
  95 // The 'extra-ansi' syntax is used to help with collisions.
  96 GlobalError *_GetErrorObj();
  97 #define _error _GetErrorObj()
  98
  99 #undef APT_MFORMAT1
 100 #undef APT_MFORMAT2
 101
 102 #endif