]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/debugrpt.h
Don't specialize std::numeric_limits<> for wxLongLong when using VC6.
[wxWidgets.git] / interface / wx / debugrpt.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: debugrpt.h
1db8f1dc 3// Purpose: interface of wxDebugReport*
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
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 26class wxDebugReportPreview
23324ae1
FM
27{
28public:
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*/
62class wxDebugReportCompress : public wxDebugReport
63{
64public:
65 /**
66 Default constructor does nothing special.
67 */
68 wxDebugReportCompress();
69
fdf20a26
VZ
70 /**
71 Set the directory where the debug report should be generated.
72
73 By default, the debug report is generated under user temporary files
74 directory. This is usually fine if it is meant to be processed in some
75 way (e.g. automatically uploaded to a remote server) but if the user is
76 asked to manually upload or send the report, it may be more convenient
77 to generate it in e.g. the users home directory and this function
78 allows to do this.
79
80 Notice that it should be called before wxDebugReport::Process() or it
81 has no effect.
82
83 @param dir
84 The full path to an existing directory where the debug report file
85 should be generated.
86
87 @since 2.9.1
88 */
89 void SetCompressedFileDirectory(const wxString& dir);
90
91 /**
92 Set the base name of the generated debug report file.
93
94 This function is similar to SetCompressedFileDirectory() but allows to
95 change the base name of the file. Notice that the file extension will
96 always be @c .zip.
97
98 By default, a unique name constructed from wxApp::GetAppName(), the
99 current process id and the current date and time is used.
100
d86f721a 101 @param name
fdf20a26
VZ
102 The base name (i.e. without extension) of the file.
103
104 @since 2.9.1
105 */
106 void SetCompressedFileBaseName(const wxString& name);
107
23324ae1 108 /**
1db8f1dc
BP
109 Returns the full path of the compressed file (empty if creation
110 failed).
23324ae1 111 */
b91c4601 112 const wxString& GetCompressedFileName() const;
23324ae1
FM
113};
114
115
e54c96f1 116
23324ae1
FM
117/**
118 @class wxDebugReport
7c913512 119
1db8f1dc
BP
120 wxDebugReport is used to generate a debug report, containing information
121 about the program current state. It is usually used from
122 wxApp::OnFatalException() as shown in the @ref page_samples_debugrpt.
7c913512 123
1db8f1dc
BP
124 A wxDebugReport object contains one or more files. A few of them can be
125 created by the class itself but more can be created from the outside and
126 then added to the report. Also note that several virtual functions may be
127 overridden to further customize the class behaviour.
7c913512 128
23324ae1 129 Once a report is fully assembled, it can simply be left in the temporary
1db8f1dc
BP
130 directory so that the user can email it to the developers (in which case
131 you should still use wxDebugReportCompress to compress it in a single file)
132 or uploaded to a Web server using wxDebugReportUpload (setting up the Web
133 server to accept uploads is your responsibility, of course). Other
134 handlers, for example for automatically emailing the report, can be defined
135 as well but are not currently included in wxWidgets.
136
137 A typical usage example:
138
139 @code
140 wxDebugReport report;
141 wxDebugReportPreviewStd preview;
142
143 report.AddCurrentContext(); // could also use AddAll()
144 report.AddCurrentDump(); // to do both at once
145
146 if ( preview.Show(report) )
147 report.Process();
148 @endcode
7c913512 149
23324ae1
FM
150 @library{wxqa}
151 @category{debugging}
152*/
7c913512 153class wxDebugReport
23324ae1
FM
154{
155public:
1db8f1dc
BP
156 /**
157 This enum is used for functions that report either the current state or
158 the state during the last (fatal) exception.
159 */
160 enum Context {
161 Context_Current,
162 Context_Exception
163 };
164
23324ae1
FM
165 /**
166 The constructor creates a temporary directory where the files that will
1db8f1dc 167 be included in the report are created. Use IsOk() to check for errors.
23324ae1
FM
168 */
169 wxDebugReport();
170
171 /**
172 The destructor normally destroys the temporary directory created in the
1db8f1dc
BP
173 constructor with all the files it contains. Call Reset() to prevent
174 this from happening.
23324ae1 175 */
adaaa686 176 virtual ~wxDebugReport();
23324ae1
FM
177
178 /**
179 Adds all available information to the report. Currently this includes a
1db8f1dc
BP
180 text (XML) file describing the process context and, under Win32, a
181 minidump file.
23324ae1
FM
182 */
183 void AddAll(Context context = Context_Exception);
184
185 /**
186 Add an XML file containing the current or exception context and the
187 stack trace.
188 */
adaaa686 189 virtual bool AddContext(Context ctx);
23324ae1
FM
190
191 /**
1db8f1dc 192 The same as calling AddContext(Context_Current).
23324ae1
FM
193 */
194 bool AddCurrentContext();
195
196 /**
1db8f1dc 197 The same as calling AddDump(Context_Current).
23324ae1
FM
198 */
199 bool AddCurrentDump();
200
201 /**
202 Adds the minidump file to the debug report.
1db8f1dc
BP
203
204 Minidumps are only available under recent Win32 versions
205 (@c dbghlp32.dll can be installed under older systems to make minidumps
206 available).
23324ae1 207 */
da1ed74c 208 virtual bool AddDump(Context ctx);
23324ae1
FM
209
210 /**
1db8f1dc 211 The same as calling AddContext(Context_Exception).
23324ae1
FM
212 */
213 bool AddExceptionContext();
214
215 /**
1db8f1dc 216 The same as calling AddDump(Context_Exception).
23324ae1
FM
217 */
218 bool AddExceptionDump();
219
220 /**
1db8f1dc
BP
221 Add another file to the report. If @a filename is an absolute path, it
222 is copied to a file in the debug report directory with the same name.
c02f03d5
FM
223 Otherwise the file will be searched in the temporary directory returned
224 by GetDirectory().
225
226 The argument @a description only exists to be displayed to the user in
227 the report summary shown by wxDebugReportPreview.
1db8f1dc
BP
228
229 @see GetDirectory(), AddText()
23324ae1 230 */
adaaa686 231 virtual void AddFile(const wxString& filename, const wxString& description);
23324ae1
FM
232
233 /**
1db8f1dc
BP
234 This is a convenient wrapper around AddFile(). It creates the file with
235 the given @a name and writes @a text to it, then adds the file to the
236 report. The @a filename shouldn't contain the path.
237
d29a9a8a 238 @return @true if file could be added successfully, @false if an IO
1db8f1dc 239 error occurred.
23324ae1
FM
240 */
241 bool AddText(const wxString& filename, const wxString& text,
242 const wxString& description);
243
23324ae1 244 /**
1db8f1dc
BP
245 This method should be used to construct the full name of the files
246 which you wish to add to the report using AddFile().
247
d29a9a8a 248 @return The name of the temporary directory used for the files in this
1db8f1dc 249 report.
23324ae1 250 */
b91c4601 251 const wxString& GetDirectory() const;
23324ae1
FM
252
253 /**
1db8f1dc
BP
254 Retrieves the name (relative to GetDirectory()) and the description of
255 the file with the given index. If @a n is greater than or equal to the
d13b34d3 256 number of files, then @false is returned.
23324ae1 257 */
328f5751 258 bool GetFile(size_t n, wxString* name, wxString* desc) const;
23324ae1
FM
259
260 /**
261 Gets the current number files in this report.
262 */
328f5751 263 size_t GetFilesCount() const;
23324ae1
FM
264
265 /**
7c913512 266 Gets the name used as a base name for various files, by default
1db8f1dc 267 wxApp::GetAppName() is used.
23324ae1 268 */
adaaa686 269 virtual wxString GetReportName() const;
23324ae1
FM
270
271 /**
1db8f1dc
BP
272 Returns @true if the object was successfully initialized. If this
273 method returns @false the report can't be used.
23324ae1 274 */
328f5751 275 bool IsOk() const;
23324ae1
FM
276
277 /**
278 Processes this report: the base class simply notifies the user that the
279 report has been generated. This is usually not enough -- instead you
280 should override this method to do something more useful to you.
281 */
282 bool Process();
283
284 /**
1db8f1dc
BP
285 Removes the file from report: this is used by wxDebugReportPreview to
286 allow the user to remove files potentially containing private
287 information from the report.
23324ae1
FM
288 */
289 void RemoveFile(const wxString& name);
290
291 /**
1db8f1dc
BP
292 Resets the directory name we use. The object can't be used any more
293 after this as it becomes uninitialized and invalid.
23324ae1
FM
294 */
295 void Reset();
5e6e278d
FM
296
297protected:
298
299 /**
300 This function may be overridden to add arbitrary custom context to the
301 XML context file created by AddContext(). By default, it does nothing.
302 */
303 virtual void DoAddCustomContext(wxXmlNode* nodeRoot);
304
305 /**
306 This function may be overridden to modify the contents of the exception
307 tag in the XML context file.
308 */
309 virtual bool DoAddExceptionInfo(wxXmlNode* nodeContext);
310
311 /**
312 This function may be overridden to modify the contents of the modules
313 tag in the XML context file.
314 */
315 virtual bool DoAddLoadedModules(wxXmlNode* nodeModules);
316
317 /**
318 This function may be overridden to modify the contents of the system
319 tag in the XML context file.
320 */
321 virtual bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
23324ae1
FM
322};
323
324
e54c96f1 325
23324ae1
FM
326/**
327 @class wxDebugReportPreviewStd
7c913512 328
1db8f1dc
BP
329 wxDebugReportPreviewStd is a standard debug report preview window. It
330 displays a dialog allowing the user to examine the contents of a debug
331 report, remove files from and add notes to it.
7c913512 332
23324ae1
FM
333 @library{wxqa}
334 @category{debugging}
335*/
336class wxDebugReportPreviewStd : public wxDebugReportPreview
337{
338public:
339 /**
340 Trivial default constructor.
341 */
342 wxDebugReportPreviewStd();
343
344 /**
1db8f1dc
BP
345 Shows the dialog.
346
347 @see wxDebugReportPreview::Show()
23324ae1 348 */
328f5751 349 bool Show(wxDebugReport& dbgrpt) const;
23324ae1
FM
350};
351
352
e54c96f1 353
23324ae1
FM
354/**
355 @class wxDebugReportUpload
7c913512 356
1db8f1dc
BP
357 This class is used to upload a compressed file using HTTP POST request. As
358 this class derives from wxDebugReportCompress, before upload the report is
359 compressed in a single ZIP file.
7c913512 360
23324ae1
FM
361 @library{wxqa}
362 @category{debugging}
363*/
364class wxDebugReportUpload : public wxDebugReportCompress
365{
366public:
367 /**
1db8f1dc
BP
368 This class will upload the compressed file created by its base class to
369 an HTML multipart/form-data form at the specified address. The @a url
370 is the upload page address, @a input is the name of the @c "type=file"
371 control on the form used for the file name and @a action is the value
372 of the form action field. The report is uploaded using the @e curl
373 program which should be available, the @e curl parameter may be used to
374 specify the full path to it.
23324ae1
FM
375 */
376 wxDebugReportUpload(const wxString& url, const wxString& input,
1db8f1dc
BP
377 const wxString& action,
378 const wxString& curl = "curl");
23324ae1 379
5e6e278d 380protected:
23324ae1 381 /**
1db8f1dc
BP
382 This function may be overridden in a derived class to show the output
383 from curl: this may be an HTML page or anything else that the server
384 returned. Value returned by this function becomes the return value of
385 wxDebugReport::Process().
23324ae1 386 */
b91c4601 387 virtual bool OnServerReply(const wxArrayString& reply);
23324ae1 388};
e54c96f1 389