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