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