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 licence
   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 name
 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 will be searched in the temporary directory returned
 224         by GetDirectory().
 225
 226         The argument @a description only exists to be displayed to the user in
 227         the report summary shown by wxDebugReportPreview.
 228
 229         @see GetDirectory(), AddText()
 230     */
 231     virtual void AddFile(const wxString& filename, const wxString& description);
 232
 233     /**
 234         This is a convenient wrapper around AddFile(). It creates the file with
 235         the given @a name and writes @a text to it, then adds the file to the
 236         report. The @a filename shouldn't contain the path.
 237
 238         @return @true if file could be added successfully, @false if an IO
 239                  error occurred.
 240     */
 241     bool AddText(const wxString& filename, const wxString& text,
 242                  const wxString& description);
 243
 244     /**
 245         This method should be used to construct the full name of the files
 246         which you wish to add to the report using AddFile().
 247
 248         @return The name of the temporary directory used for the files in this
 249                  report.
 250     */
 251     const wxString& GetDirectory() const;
 252
 253     /**
 254         Retrieves the name (relative to GetDirectory()) and the description of
 255         the file with the given index. If @a n is greater than or equal to the
 256         number of filse, @false is returned.
 257     */
 258     bool GetFile(size_t n, wxString* name, wxString* desc) const;
 259
 260     /**
 261         Gets the current number files in this report.
 262     */
 263     size_t GetFilesCount() const;
 264
 265     /**
 266         Gets the name used as a base name for various files, by default
 267         wxApp::GetAppName() is used.
 268     */
 269     virtual wxString GetReportName() const;
 270
 271     /**
 272         Returns @true if the object was successfully initialized. If this
 273         method returns @false the report can't be used.
 274     */
 275     bool IsOk() const;
 276
 277     /**
 278         Processes this report: the base class simply notifies the user that the
 279         report has been generated. This is usually not enough -- instead you
 280         should override this method to do something more useful to you.
 281     */
 282     bool Process();
 283
 284     /**
 285         Removes the file from report: this is used by wxDebugReportPreview to
 286         allow the user to remove files potentially containing private
 287         information from the report.
 288     */
 289     void RemoveFile(const wxString& name);
 290
 291     /**
 292         Resets the directory name we use. The object can't be used any more
 293         after this as it becomes uninitialized and invalid.
 294     */
 295     void Reset();
 296
 297 protected:
 298
 299     /**
 300         This function may be overridden to add arbitrary custom context to the
 301         XML context file created by AddContext(). By default, it does nothing.
 302     */
 303     virtual void DoAddCustomContext(wxXmlNode* nodeRoot);
 304
 305     /**
 306         This function may be overridden to modify the contents of the exception
 307         tag in the XML context file.
 308     */
 309     virtual bool DoAddExceptionInfo(wxXmlNode* nodeContext);
 310
 311     /**
 312         This function may be overridden to modify the contents of the modules
 313         tag in the XML context file.
 314     */
 315     virtual bool DoAddLoadedModules(wxXmlNode* nodeModules);
 316
 317     /**
 318         This function may be overridden to modify the contents of the system
 319         tag in the XML context file.
 320     */
 321     virtual bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
 322 };
 323
 324
 325
 326 /**
 327     @class wxDebugReportPreviewStd
 328
 329     wxDebugReportPreviewStd is a standard debug report preview window. It
 330     displays a dialog allowing the user to examine the contents of a debug
 331     report, remove files from and add notes to it.
 332
 333     @library{wxqa}
 334     @category{debugging}
 335 */
 336 class wxDebugReportPreviewStd : public wxDebugReportPreview
 337 {
 338 public:
 339     /**
 340         Trivial default constructor.
 341     */
 342     wxDebugReportPreviewStd();
 343
 344     /**
 345         Shows the dialog.
 346
 347         @see wxDebugReportPreview::Show()
 348     */
 349     bool Show(wxDebugReport& dbgrpt) const;
 350 };
 351
 352
 353
 354 /**
 355     @class wxDebugReportUpload
 356
 357     This class is used to upload a compressed file using HTTP POST request. As
 358     this class derives from wxDebugReportCompress, before upload the report is
 359     compressed in a single ZIP file.
 360
 361     @library{wxqa}
 362     @category{debugging}
 363 */
 364 class wxDebugReportUpload : public wxDebugReportCompress
 365 {
 366 public:
 367     /**
 368         This class will upload the compressed file created by its base class to
 369         an HTML multipart/form-data form at the specified address. The @a url
 370         is the upload page address, @a input is the name of the @c "type=file"
 371         control on the form used for the file name and @a action is the value
 372         of the form action field. The report is uploaded using the @e curl
 373         program which should be available, the @e curl parameter may be used to
 374         specify the full path to it.
 375     */
 376     wxDebugReportUpload(const wxString& url, const wxString& input,
 377                         const wxString& action,
 378                         const wxString& curl = "curl");
 379
 380 protected:
 381     /**
 382         This function may be overridden in a derived class to show the output
 383         from curl: this may be an HTML page or anything else that the server
 384         returned. Value returned by this function becomes the return value of
 385         wxDebugReport::Process().
 386     */
 387     virtual bool OnServerReply(const wxArrayString& reply);
 388 };
 389