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
 148         Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
 149         can be installed under older systems to make minidumps available).
 150     */
 151     bool AddDump(Context ctx);
 152
 153     /**
 154         The same as @ref addcontext() AddContext(Context_Exception).
 155     */
 156     bool AddExceptionContext();
 157
 158     /**
 159         The same as @ref adddump() AddDump(Context_Exception).
 160     */
 161     bool AddExceptionDump();
 162
 163     /**
 164         Add another file to the report. If @e filename is an absolute path, it is
 165         copied to a file in the debug report directory with the same name. Otherwise
 166         the file should already exist in this directory
 167
 168         @e description only exists to be displayed to the user in the report summary
 169         shown by wxDebugReportPreview.
 170     */
 171     void AddFile(const wxString& filename,
 172                  const wxString& description);
 173
 174     /**
 175         This is a convenient wrapper around AddFile(). It
 176         creates the file with the given @e name and writes @e text to it, then
 177         adds the file to the report. The @e filename shouldn't contain the path.
 178
 179         Returns @true if file could be added successfully, @false if an IO error
 180         occurred.
 181     */
 182     bool AddText(const wxString& filename, const wxString& text,
 183                  const wxString& description);
 184
 185     /**
 186         This function may be overridden to add arbitrary custom context to the XML
 187         context file created by AddContext(). By
 188         default, it does nothing.
 189     */
 190     void DoAddCustomContext(wxXmlNode * nodeRoot);
 191
 192     /**
 193         This function may be overridden to modify the contents of the exception tag in
 194         the XML context file.
 195     */
 196     bool DoAddExceptionInfo(wxXmlNode* nodeContext);
 197
 198     /**
 199         This function may be overridden to modify the contents of the modules tag in
 200         the XML context file.
 201     */
 202     bool DoAddLoadedModules(wxXmlNode* nodeModules);
 203
 204     /**
 205         This function may be overridden to modify the contents of the system tag in
 206         the XML context file.
 207     */
 208     bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
 209
 210     /**
 211         Returns the name of the temporary directory used for the files in this report.
 212
 213         This method should be used to construct the full name of the files which you
 214         wish to add to the report using AddFile().
 215     */
 216     const wxString GetDirectory();
 217
 218     /**
 219         Retrieves the name (relative to
 220         wxDebugReport::GetDirectory) and the description of the
 221         file with the given index. If @e n is greater than or equal to the number of
 222         filse, @false is returned.
 223     */
 224     bool GetFile(size_t n, wxString* name, wxString* desc);
 225
 226     /**
 227         Gets the current number files in this report.
 228     */
 229     size_t GetFilesCount();
 230
 231     /**
 232         Gets the name used as a base name for various files, by default
 233         wxApp::GetAppName is used.
 234     */
 235     wxString GetReportName();
 236
 237     /**
 238         Returns @true if the object was successfully initialized. If this method
 239         returns
 240         @false the report can't be used.
 241     */
 242 #define bool IsOk()     /* implementation is private */
 243
 244     /**
 245         Processes this report: the base class simply notifies the user that the
 246         report has been generated. This is usually not enough -- instead you
 247         should override this method to do something more useful to you.
 248     */
 249     bool Process();
 250
 251     /**
 252         Removes the file from report: this is used by
 253         wxDebugReportPreview to allow the user to
 254         remove files potentially containing private information from the report.
 255     */
 256     void RemoveFile(const wxString& name);
 257
 258     /**
 259         Resets the directory name we use. The object can't be used any more after
 260         this as it becomes uninitialized and invalid.
 261     */
 262     void Reset();
 263 };
 264
 265
 266 /**
 267     @class wxDebugReportPreviewStd
 268     @wxheader{debugrpt.h}
 269
 270     wxDebugReportPreviewStd is a standard debug report preview window. It displays
 271     a GUIdialog allowing the user to examine the contents of a debug report, remove
 272     files from and add notes to it.
 273
 274     @library{wxqa}
 275     @category{debugging}
 276 */
 277 class wxDebugReportPreviewStd : public wxDebugReportPreview
 278 {
 279 public:
 280     /**
 281         Trivial default constructor.
 282     */
 283     wxDebugReportPreviewStd();
 284
 285     /**
 286         Show the dialog, see
 287         wxDebugReportPreview::Show for more
 288         information.
 289     */
 290     bool Show(wxDebugReport& dbgrpt);
 291 };
 292
 293
 294 /**
 295     @class wxDebugReportUpload
 296     @wxheader{debugrpt.h}
 297
 298     This class is used to upload a compressed file using HTTP POST request. As this
 299     class derives from wxDebugReportCompress, before upload the report is
 300     compressed in a single .ZIP file.
 301
 302     @library{wxqa}
 303     @category{debugging}
 304 */
 305 class wxDebugReportUpload : public wxDebugReportCompress
 306 {
 307 public:
 308     /**
 309         )
 310
 311         This class will upload the compressed file created by its base class to an HTML
 312         multipart/form-data form at the specified address. The @e url is the upload
 313         page address, @e input is the name of the @c "type=file" control on
 314         the form used for the file name and @e action is the value of the form
 315         action field. The report is uploaded using @c @e curl program which
 316         should be available, the @e curl parameter may be used to specify the full
 317         path to it.
 318     */
 319     wxDebugReportUpload(const wxString& url, const wxString& input,
 320                         const wxString& action);
 321
 322     /**
 323         )
 324
 325         This function may be overridden in a derived class to show the output from
 326         curl: this may be an HTML page or anything else that the server returned.
 327         Value returned by this function becomes the return value of
 328         wxDebugReport::Process.
 329     */
 330     bool OnServerReply();
 331 };