interface/wx/debugrpt.h

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