Removing more CodeWarrior project files.
[wxWidgets.git] / interface / wx / debugrpt.h
0 / 349 (  0%)
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: debugrpt.h
3// Purpose: interface of wxDebugReport*
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxDebugReportPreview
11
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.
19
20 wxDebugReportPreview is an abstract base class, currently the only concrete
21 class deriving from it is wxDebugReportPreviewStd.
22
23 @library{wxqa}
24 @category{debugging}
25*/
26class wxDebugReportPreview
27{
28public:
29 /**
30 Default constructor.
31 */
32 wxDebugReportPreview();
33
34 /**
35 Destructor is trivial as well but should be virtual for a base class.
36 */
37 virtual ~wxDebugReportPreview();
38
39 /**
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
43 @return @true if the report should be processed or @false if the user
44 chose to cancel report generation or removed all files from
45 it.
46 */
47 virtual bool Show(wxDebugReport& dbgrpt) const = 0;
48};
49
50
51
52/**
53 @class wxDebugReportCompress
54
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.
58
59 @library{wxqa}
60 @category{debugging}
61*/
62class wxDebugReportCompress : public wxDebugReport
63{
64public:
65 /**
66 Default constructor does nothing special.
67 */
68 wxDebugReportCompress();
69
70 /**
71 Returns the full path of the compressed file (empty if creation
72 failed).
73 */
74 const wxString& GetCompressedFileName() const;
75};
76
77
78
79/**
80 @class wxDebugReport
81
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.
85
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.
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
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
111
112 @library{wxqa}
113 @category{debugging}
114*/
115class wxDebugReport
116{
117public:
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
127 /**
128 The constructor creates a temporary directory where the files that will
129 be included in the report are created. Use IsOk() to check for errors.
130 */
131 wxDebugReport();
132
133 /**
134 The destructor normally destroys the temporary directory created in the
135 constructor with all the files it contains. Call Reset() to prevent
136 this from happening.
137 */
138 virtual ~wxDebugReport();
139
140 /**
141 Adds all available information to the report. Currently this includes a
142 text (XML) file describing the process context and, under Win32, a
143 minidump file.
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 */
151 virtual bool AddContext(Context ctx);
152
153 /**
154 The same as calling AddContext(Context_Current).
155 */
156 bool AddCurrentContext();
157
158 /**
159 The same as calling AddDump(Context_Current).
160 */
161 bool AddCurrentDump();
162
163 /**
164 Adds the minidump file to the debug report.
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).
169 */
170 virtual bool AddDump(Context ctx);
171
172 /**
173 The same as calling AddContext(Context_Exception).
174 */
175 bool AddExceptionContext();
176
177 /**
178 The same as calling AddDump(Context_Exception).
179 */
180 bool AddExceptionDump();
181
182 /**
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()
190 */
191 virtual void AddFile(const wxString& filename, const wxString& description);
192
193 /**
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
198 @return @true if file could be added successfully, @false if an IO
199 error occurred.
200 */
201 bool AddText(const wxString& filename, const wxString& text,
202 const wxString& description);
203
204 /**
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
208 @return The name of the temporary directory used for the files in this
209 report.
210 */
211 const wxString& GetDirectory() const;
212
213 /**
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.
217 */
218 bool GetFile(size_t n, wxString* name, wxString* desc) const;
219
220 /**
221 Gets the current number files in this report.
222 */
223 size_t GetFilesCount() const;
224
225 /**
226 Gets the name used as a base name for various files, by default
227 wxApp::GetAppName() is used.
228 */
229 virtual wxString GetReportName() const;
230
231 /**
232 Returns @true if the object was successfully initialized. If this
233 method returns @false the report can't be used.
234 */
235 bool IsOk() const;
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 /**
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.
248 */
249 void RemoveFile(const wxString& name);
250
251 /**
252 Resets the directory name we use. The object can't be used any more
253 after this as it becomes uninitialized and invalid.
254 */
255 void Reset();
256
257protected:
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);
282};
283
284
285
286/**
287 @class wxDebugReportPreviewStd
288
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.
292
293 @library{wxqa}
294 @category{debugging}
295*/
296class wxDebugReportPreviewStd : public wxDebugReportPreview
297{
298public:
299 /**
300 Trivial default constructor.
301 */
302 wxDebugReportPreviewStd();
303
304 /**
305 Shows the dialog.
306
307 @see wxDebugReportPreview::Show()
308 */
309 bool Show(wxDebugReport& dbgrpt) const;
310};
311
312
313
314/**
315 @class wxDebugReportUpload
316
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.
320
321 @library{wxqa}
322 @category{debugging}
323*/
324class wxDebugReportUpload : public wxDebugReportCompress
325{
326public:
327 /**
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.
335 */
336 wxDebugReportUpload(const wxString& url, const wxString& input,
337 const wxString& action,
338 const wxString& curl = "curl");
339
340protected:
341 /**
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().
346 */
347 virtual bool OnServerReply(const wxArrayString& reply);
348};
349