- initial import of revision 374 from cnc
[apt.git] / apt-pkg / contrib / error.h
1 // -*- mode: cpp; mode: fold -*-
2 // Description                                                          /*{{{*/
3 // $Id: error.h,v 1.2 2003/01/29 13:04:48 niemeyer 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 #ifdef __GNUG__
44 #pragma interface "apt-pkg/error.h"
45 #endif 
46
47 #ifdef __GNUG__
48 // Methods have a hidden this parameter that is visible to this attribute
49 #define APT_MFORMAT1 __attribute__ ((format (printf, 2, 3)))
50 #define APT_MFORMAT2 __attribute__ ((format (printf, 3, 4)))
51 #else
52 #define APT_MFORMAT1
53 #define APT_MFORMAT2    
54 #endif    
55     
56 #include <string>
57
58 using std::string;
59
60 class GlobalError
61 {
62    struct Item
63    {
64       string Text;
65       bool Error;
66       Item *Next;
67    };
68    
69    Item *List;
70    bool PendingFlag;
71    void Insert(Item *I);
72
73    // CNC:2003-02-24 - Introduced a stack of errors. This allows one to
74    //                  delay error handling until a later time.
75    struct State
76    {
77       Item *List;
78       bool PendingFlag;
79       State *Next;
80    };
81
82    State *Stack;
83    
84    public:
85
86    // CNC:2003-02-24 - See above.
87    void PushState();
88    bool PopState();
89    bool PopBackState();
90
91 #ifndef SWIG
92    // Call to generate an error from a library call.
93    bool Errno(const char *Function,const char *Description,...) APT_MFORMAT2;
94    bool WarningE(const char *Function,const char *Description,...) APT_MFORMAT2;
95
96    /* A warning should be considered less severe than an error, and may be
97       ignored by the client. */
98    bool Error(const char *Description,...) APT_MFORMAT1;
99    bool Warning(const char *Description,...) APT_MFORMAT1;
100 #else
101    // Call to generate an error from a library call.
102    bool Errno(const char *Function,const char *Description) APT_MFORMAT2;
103    bool WarningE(const char *Function,const char *Description) APT_MFORMAT2;
104
105    /* A warning should be considered less severe than an error, and may be
106       ignored by the client. */
107    bool Error(const char *Description) APT_MFORMAT1;
108    bool Warning(const char *Description) APT_MFORMAT1;
109 #endif
110
111    // Simple accessors
112    inline bool PendingError() {return PendingFlag;};
113    inline bool empty() {return List == 0;};
114    bool PopMessage(string &Text);
115    void Discard();
116
117    // Usefull routine to dump to cerr
118    void DumpErrors();
119    
120    GlobalError();
121 };
122
123 // The 'extra-ansi' syntax is used to help with collisions. 
124 GlobalError *_GetErrorObj();
125 #define _error _GetErrorObj()
126
127 #undef APT_MFORMAT1
128 #undef APT_MFORMAT2
129
130 #endif
131
132 // vim:sts=3:sw=3