interface/wx/debugrpt.h

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