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