interface/debugrpt.h

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