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