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