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