interface/debugrpt.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        debugrpt.h
   3 // Purpose:     interface of wxDebugReportPreview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDebugReportPreview
  11     @wxheader{debugrpt.h}
  12
  13     This class presents the debug report to the user and allows him to veto report
  14     entirely or remove some parts of it. Although not mandatory, using this class
  15     is strongly recommended as data included in the debug report might contain
  16     sensitive private information and the user should be notified about it as well
  17     as having a possibility to examine the data which had been gathered to check
  18     whether this is effectively the case and discard the debug report if it is.
  19
  20     wxDebugReportPreview is an abstract base class, currently the only concrete
  21     class deriving from it is
  22     wxDebugReportPreviewStd.
  23
  24     @library{wxqa}
  25     @category{debugging}
  26 */
  27 class wxDebugReportPreview
  28 {
  29 public:
  30     /**
  31         Trivial default constructor.
  32     */
  33     wxDebugReportPreview();
  34
  35     /**
  36         dtor is trivial as well but should be virtual for a base class
  37     */
  38     ~wxDebugReportPreview();
  39
  40     /**
  41         Present the report to the user and allow him to modify it by removing some or
  42         all of the files and, potentially, adding some notes. Return @true if the
  43         report should be processed or @false if the user chose to cancel report
  44         generation or removed all files from it.
  45     */
  46     bool Show(wxDebugReport& dbgrpt) const;
  47 };
  48
  49
  50
  51 /**
  52     @class wxDebugReportCompress
  53     @wxheader{debugrpt.h}
  54
  55     wxDebugReportCompress is a wxDebugReport which
  56     compresses all the files in this debug report into a single .ZIP file in its
  57     @c @e Process() function.
  58
  59     @library{wxqa}
  60     @category{debugging}
  61 */
  62 class wxDebugReportCompress : public wxDebugReport
  63 {
  64 public:
  65     /**
  66         Default constructor does nothing special.
  67     */
  68     wxDebugReportCompress();
  69
  70     /**
  71         Returns the full path of the compressed file (empty if creation failed).
  72     */
  73     const wxString GetCompressedFileName() const;
  74 };
  75
  76
  77
  78 /**
  79     @class wxDebugReport
  80     @wxheader{debugrpt.h}
  81
  82     wxDebugReport is used to generate a debug report, containing information about
  83     the program current state. It is usually used from
  84     wxApp::OnFatalException as shown in the
  85     sample().
  86
  87     A wxDebugReport object contains one or more files. A few of them can be created
  88     by the
  89     class itself but more can be created from the outside and then added to the
  90     report. Also note that several virtual functions may be overridden to further
  91     customize the class behaviour.
  92
  93     Once a report is fully assembled, it can simply be left in the temporary
  94     directory so that the user can email it to the developers (in which case you
  95     should still use wxDebugReportCompress to
  96     compress it in a single file) or uploaded to a Web server using
  97     wxDebugReportUpload (setting up the Web server
  98     to accept uploads is your responsibility, of course). Other handlers, for
  99     example for
 100     automatically emailing the report, can be defined as well but are not currently
 101     included in wxWidgets.
 102
 103     @library{wxqa}
 104     @category{debugging}
 105 */
 106 class wxDebugReport
 107 {
 108 public:
 109     /**
 110         The constructor creates a temporary directory where the files that will
 111         be included in the report are created. Use
 112         IsOk() to check for errors.
 113     */
 114     wxDebugReport();
 115
 116     /**
 117         The destructor normally destroys the temporary directory created in the
 118         constructor
 119         with all the files it contains. Call Reset() to
 120         prevent this from happening.
 121     */
 122     ~wxDebugReport();
 123
 124     /**
 125         Adds all available information to the report. Currently this includes a
 126         text (XML) file describing the process context and, under Win32, a minidump
 127         file.
 128     */
 129     void AddAll(Context context = Context_Exception);
 130
 131     /**
 132         Add an XML file containing the current or exception context and the
 133         stack trace.
 134     */
 135     bool AddContext(Context ctx);
 136
 137     /**
 138         The same as @ref addcontext() AddContext(Context_Current).
 139     */
 140     bool AddCurrentContext();
 141
 142     /**
 143         The same as @ref adddump() AddDump(Context_Current).
 144     */
 145     bool AddCurrentDump();
 146
 147     /**
 148         Adds the minidump file to the debug report.
 149         Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
 150         can be installed under older systems to make minidumps available).
 151     */
 152     bool AddDump(Context ctx);
 153
 154     /**
 155         The same as @ref addcontext() AddContext(Context_Exception).
 156     */
 157     bool AddExceptionContext();
 158
 159     /**
 160         The same as @ref adddump() AddDump(Context_Exception).
 161     */
 162     bool AddExceptionDump();
 163
 164     /**
 165         Add another file to the report. If @a filename is an absolute path, it is
 166         copied to a file in the debug report directory with the same name. Otherwise
 167         the file should already exist in this directory
 168         @a description only exists to be displayed to the user in the report summary
 169         shown by wxDebugReportPreview.
 170     */
 171     void AddFile(const wxString& filename,
 172                  const wxString& description);
 173
 174     /**
 175         This is a convenient wrapper around AddFile(). It
 176         creates the file with the given @e name and writes @a text to it, then
 177         adds the file to the report. The @a filename shouldn't contain the path.
 178         Returns @true if file could be added successfully, @false if an IO error
 179         occurred.
 180     */
 181     bool AddText(const wxString& filename, const wxString& text,
 182                  const wxString& description);
 183
 184     /**
 185         This function may be overridden to add arbitrary custom context to the XML
 186         context file created by AddContext(). By
 187         default, it does nothing.
 188     */
 189     void DoAddCustomContext(wxXmlNode* nodeRoot);
 190
 191     /**
 192         This function may be overridden to modify the contents of the exception tag in
 193         the XML context file.
 194     */
 195     bool DoAddExceptionInfo(wxXmlNode* nodeContext);
 196
 197     /**
 198         This function may be overridden to modify the contents of the modules tag in
 199         the XML context file.
 200     */
 201     bool DoAddLoadedModules(wxXmlNode* nodeModules);
 202
 203     /**
 204         This function may be overridden to modify the contents of the system tag in
 205         the XML context file.
 206     */
 207     bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
 208
 209     /**
 210         Returns the name of the temporary directory used for the files in this report.
 211         This method should be used to construct the full name of the files which you
 212         wish to add to the report using AddFile().
 213     */
 214     const wxString GetDirectory() const;
 215
 216     /**
 217         Retrieves the name (relative to
 218         wxDebugReport::GetDirectory) and the description of the
 219         file with the given index. If @a n is greater than or equal to the number of
 220         filse, @false is returned.
 221     */
 222     bool GetFile(size_t n, wxString* name, wxString* desc) const;
 223
 224     /**
 225         Gets the current number files in this report.
 226     */
 227     size_t GetFilesCount() const;
 228
 229     /**
 230         Gets the name used as a base name for various files, by default
 231         wxApp::GetAppName is used.
 232     */
 233     wxString GetReportName() const;
 234
 235     /**
 236         Returns @true if the object was successfully initialized. If this method
 237         returns
 238         @false the report can't be used.
 239     */
 240     bool IsOk() const;
 241
 242     /**
 243         Processes this report: the base class simply notifies the user that the
 244         report has been generated. This is usually not enough -- instead you
 245         should override this method to do something more useful to you.
 246     */
 247     bool Process();
 248
 249     /**
 250         Removes the file from report: this is used by
 251         wxDebugReportPreview to allow the user to
 252         remove files potentially containing private information from the report.
 253     */
 254     void RemoveFile(const wxString& name);
 255
 256     /**
 257         Resets the directory name we use. The object can't be used any more after
 258         this as it becomes uninitialized and invalid.
 259     */
 260     void Reset();
 261 };
 262
 263
 264
 265 /**
 266     @class wxDebugReportPreviewStd
 267     @wxheader{debugrpt.h}
 268
 269     wxDebugReportPreviewStd is a standard debug report preview window. It displays
 270     a GUIdialog allowing the user to examine the contents of a debug report, remove
 271     files from and add notes to it.
 272
 273     @library{wxqa}
 274     @category{debugging}
 275 */
 276 class wxDebugReportPreviewStd : public wxDebugReportPreview
 277 {
 278 public:
 279     /**
 280         Trivial default constructor.
 281     */
 282     wxDebugReportPreviewStd();
 283
 284     /**
 285         Show the dialog, see
 286         wxDebugReportPreview::Show for more
 287         information.
 288     */
 289     bool Show(wxDebugReport& dbgrpt) const;
 290 };
 291
 292
 293
 294 /**
 295     @class wxDebugReportUpload
 296     @wxheader{debugrpt.h}
 297
 298     This class is used to upload a compressed file using HTTP POST request. As this
 299     class derives from wxDebugReportCompress, before upload the report is
 300     compressed in a single .ZIP file.
 301
 302     @library{wxqa}
 303     @category{debugging}
 304 */
 305 class wxDebugReportUpload : public wxDebugReportCompress
 306 {
 307 public:
 308     /**
 309         )
 310         This class will upload the compressed file created by its base class to an HTML
 311         multipart/form-data form at the specified address. The @a url is the upload
 312         page address, @a input is the name of the @c "type=file" control on
 313         the form used for the file name and @a action is the value of the form
 314         action field. The report is uploaded using @c @e curl program which
 315         should be available, the @e curl parameter may be used to specify the full
 316         path to it.
 317     */
 318     wxDebugReportUpload(const wxString& url, const wxString& input,
 319                         const wxString& action);
 320
 321     /**
 322         )
 323         This function may be overridden in a derived class to show the output from
 324         curl: this may be an HTML page or anything else that the server returned.
 325         Value returned by this function becomes the return value of
 326         wxDebugReport::Process.
 327     */
 328     bool OnServerReply();
 329 };
 330