include/wx/debugrpt.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/debugrpt.h
   3 // Purpose:     declaration of wxDebugReport class
   4 // Author:      Vadim Zeitlin
   5 // Created:     2005-01-17
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2005 Vadim Zeitlin <vadim@wxwindows.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_DEBUGRPT_H_
  12 #define _WX_DEBUGRPT_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_DEBUGREPORT && wxUSE_XML
  17
  18 #include "wx/string.h"
  19 #include "wx/arrstr.h"
  20
  21 class WXDLLIMPEXP_FWD_XML wxXmlNode;
  22
  23 // ----------------------------------------------------------------------------
  24 // wxDebugReport: generate a debug report, processing is done in derived class
  25 // ----------------------------------------------------------------------------
  26
  27 class WXDLLIMPEXP_QA wxDebugReport
  28 {
  29 public:
  30     // this is used for the functions which may report either the current state
  31     // or the state during the last (fatal) exception
  32     enum Context { Context_Current, Context_Exception };
  33
  34
  35     // ctor creates a temporary directory where we create the files which will
  36     // be included in the report, use IsOk() to check for errors
  37     wxDebugReport();
  38
  39     // dtor normally destroys the temporary directory created in the ctor (with
  40     // all the files it contains), call Reset() to prevent this from happening
  41     virtual ~wxDebugReport();
  42
  43     // return the name of the directory used for this report
  44     const wxString& GetDirectory() const { return m_dir; }
  45
  46     // return true if the object was successfully initialized
  47     bool IsOk() const { return !GetDirectory().empty(); }
  48
  49     // reset the directory name we use, the object can't be used any more after
  50     // this as it becomes invalid/uninitialized
  51     void Reset() { m_dir.clear(); }
  52
  53
  54     // add another file to the report: the file must already exist, its name
  55     // can be either absolute in which case it is copied to the debug report
  56     // directory or relative to GetDirectory()
  57     //
  58     // description is shown to the user in the report summary
  59     virtual void AddFile(const wxString& filename, const wxString& description);
  60
  61     // convenience function: write the given text to a file with the given name
  62     // and then add it to the report (the difference with AddFile() is that the
  63     // file will be created by this function and doesn't have to already exist)
  64     bool AddText(const wxString& filename,
  65                  const wxString& text,
  66                  const wxString& description);
  67
  68 #if wxUSE_STACKWALKER
  69     // add an XML file containing the current or exception context and the
  70     // stack trace
  71     bool AddCurrentContext() { return AddContext(Context_Current); }
  72     bool AddExceptionContext() { return AddContext(Context_Exception); }
  73     virtual bool AddContext(Context ctx);
  74 #endif
  75
  76 #if wxUSE_CRASHREPORT
  77     // add a file with crash report
  78     bool AddCurrentDump() { return AddDump(Context_Current); }
  79     bool AddExceptionDump() { return AddDump(Context_Exception); }
  80     virtual bool AddDump(Context ctx);
  81 #endif // wxUSE_CRASHREPORT
  82
  83     // add all available information to the report
  84     void AddAll(Context context = Context_Exception);
  85
  86
  87     // process this report: the base class simply notifies the user that the
  88     // report has been generated, this is usually not enough -- instead you
  89     // should override this method to do something more useful to you
  90     bool Process();
  91
  92     // get the name used as base name for various files, by default
  93     // wxApp::GetName()
  94     virtual wxString GetReportName() const;
  95
  96     // get the files in this report
  97     size_t GetFilesCount() const { return m_files.GetCount(); }
  98     bool GetFile(size_t n, wxString *name, wxString *desc) const;
  99
 100     // remove the file from report: this is used by wxDebugReportPreview to
 101     // allow the user to remove files potentially containing private
 102     // information from the report
 103     void RemoveFile(const wxString& name);
 104
 105 protected:
 106 #if wxUSE_STACKWALKER
 107     // used by AddContext()
 108     virtual bool DoAddSystemInfo(wxXmlNode *nodeSystemInfo);
 109     virtual bool DoAddLoadedModules(wxXmlNode *nodeModules);
 110     virtual bool DoAddExceptionInfo(wxXmlNode *nodeContext);
 111     virtual void DoAddCustomContext(wxXmlNode * WXUNUSED(nodeRoot)) { }
 112 #endif
 113
 114     // used by Process()
 115     virtual bool DoProcess();
 116
 117 private:
 118     // name of the report directory
 119     wxString m_dir;
 120
 121     // the arrays of files in this report and their descriptions
 122     wxArrayString m_files,
 123                   m_descriptions;
 124 };
 125
 126 #if wxUSE_ZIPSTREAM
 127
 128 // ----------------------------------------------------------------------------
 129 // wxDebugReportCompress: compress all files of this debug report in a .ZIP
 130 // ----------------------------------------------------------------------------
 131
 132 class WXDLLIMPEXP_QA wxDebugReportCompress : public wxDebugReport
 133 {
 134 public:
 135     wxDebugReportCompress() { }
 136
 137     // you can optionally specify the directory and/or name of the file where
 138     // the debug report should be generated, a default location under the
 139     // directory containing temporary files will be used if you don't
 140     //
 141     // both of these functions should be called before Process()ing the report
 142     // if they're called at all
 143     void SetCompressedFileDirectory(const wxString& dir);
 144     void SetCompressedFileBaseName(const wxString& name);
 145
 146     // returns the full path of the compressed file (empty if creation failed)
 147     const wxString& GetCompressedFileName() const { return m_zipfile; }
 148
 149 protected:
 150     virtual bool DoProcess();
 151
 152 private:
 153     // user-specified file directory/base name, use defaults if empty
 154     wxString m_zipDir,
 155              m_zipName;
 156
 157     // full path to the ZIP file we created
 158     wxString m_zipfile;
 159 };
 160
 161 // ----------------------------------------------------------------------------
 162 // wxDebugReportUploader: uploads compressed file using HTTP POST request
 163 // ----------------------------------------------------------------------------
 164
 165 class WXDLLIMPEXP_QA wxDebugReportUpload : public wxDebugReportCompress
 166 {
 167 public:
 168     // this class will upload the compressed file created by its base class to
 169     // an HTML multipart/form-data form at the specified address
 170     //
 171     // the URL is the base address, input is the name of the "type=file"
 172     // control on the form used for the file name and action is the value of
 173     // the form action field
 174     wxDebugReportUpload(const wxString& url,
 175                         const wxString& input,
 176                         const wxString& action,
 177                         const wxString& curl = wxT("curl"));
 178
 179 protected:
 180     virtual bool DoProcess();
 181
 182     // this function may be overridden in a derived class to show the output
 183     // from curl: this may be an HTML page or anything else that the server
 184     // returned
 185     //
 186     // return value becomes the return value of Process()
 187     virtual bool OnServerReply(const wxArrayString& WXUNUSED(reply))
 188     {
 189         return true;
 190     }
 191
 192 private:
 193     // the full URL to use with HTTP POST request
 194     wxString m_uploadURL;
 195
 196     // the name of the input field containing the file name in the form at
 197     // above URL
 198     wxString m_inputField;
 199
 200     // the curl command (by default it is just "curl" but could be full path to
 201     // curl or a wrapper script with curl-compatible syntax)
 202     wxString m_curlCmd;
 203 };
 204
 205 #endif // wxUSE_ZIPSTREAM
 206
 207
 208 // ----------------------------------------------------------------------------
 209 // wxDebugReportPreview: presents the debug report to the user and allows him
 210 //                       to veto report entirely or remove some parts of it
 211 // ----------------------------------------------------------------------------
 212
 213 class WXDLLIMPEXP_QA wxDebugReportPreview
 214 {
 215 public:
 216     // ctor is trivial
 217     wxDebugReportPreview() { }
 218
 219     // present the report to the user and allow him to modify it by removing
 220     // some or all of the files and, potentially, adding some notes
 221     //
 222     // return true if the report should be processed or false if the user chose
 223     // to cancel report generation or removed all files from it
 224     virtual bool Show(wxDebugReport& dbgrpt) const = 0;
 225
 226     // dtor is trivial as well but should be virtual for a base class
 227     virtual ~wxDebugReportPreview() { }
 228 };
 229
 230 #if wxUSE_GUI
 231
 232 // ----------------------------------------------------------------------------
 233 // wxDebugReportPreviewStd: standard debug report preview window
 234 // ----------------------------------------------------------------------------
 235
 236 class WXDLLIMPEXP_QA wxDebugReportPreviewStd : public wxDebugReportPreview
 237 {
 238 public:
 239     wxDebugReportPreviewStd() { }
 240
 241     virtual bool Show(wxDebugReport& dbgrpt) const;
 242 };
 243
 244 #endif // wxUSE_GUI
 245
 246 #endif // wxUSE_DEBUGREPORT && wxUSE_XML
 247
 248 #endif // _WX_DEBUGRPT_H_