]>
git.saurik.com Git - wxWidgets.git/blob - interface/debugrpt.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: documentation for wxDebugReportPreview class
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxDebugReportPreview
13 This class presents the debug report to the user and allows him to veto report
14 entirely or remove some parts of it. Although not mandatory, using this class
15 is strongly recommended as data included in the debug report might contain
16 sensitive private information and the user should be notified about it as well
17 as having a possibility to examine the data which had been gathered to check
18 whether this is effectively the case and discard the debug report if it is.
20 wxDebugReportPreview is an abstract base class, currently the only concrete
21 class deriving from it is
22 wxDebugReportPreviewStd.
27 class wxDebugReportPreview
31 Trivial default constructor.
33 wxDebugReportPreview();
36 dtor is trivial as well but should be virtual for a base class
38 ~wxDebugReportPreview();
41 Present the report to the user and allow him to modify it by removing some or
42 all of the files and, potentially, adding some notes. Return @true if the
43 report should be processed or @false if the user chose to cancel report
44 generation or removed all files from it.
46 bool Show(wxDebugReport
& dbgrpt
);
51 @class wxDebugReportCompress
54 wxDebugReportCompress is a wxDebugReport which
55 compresses all the files in this debug report into a single .ZIP file in its
56 @c @e Process() function.
61 class wxDebugReportCompress
: public wxDebugReport
65 Default constructor does nothing special.
67 wxDebugReportCompress();
70 Returns the full path of the compressed file (empty if creation failed).
72 const wxString
GetCompressedFileName();
80 wxDebugReport is used to generate a debug report, containing information about
81 the program current state. It is usually used from
82 wxApp::OnFatalException as shown in the
85 A wxDebugReport object contains one or more files. A few of them can be created
87 class itself but more can be created from the outside and then added to the
88 report. Also note that several virtual functions may be overridden to further
89 customize the class behaviour.
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 you
93 should still use wxDebugReportCompress to
94 compress it in a single file) or uploaded to a Web server using
95 wxDebugReportUpload (setting up the Web server
96 to accept uploads is your responsibility, of course). Other handlers, for
98 automatically emailing the report, can be defined as well but are not currently
99 included in wxWidgets.
108 The constructor creates a temporary directory where the files that will
109 be included in the report are created. Use
110 IsOk() to check for errors.
115 The destructor normally destroys the temporary directory created in the
117 with all the files it contains. Call Reset() to
118 prevent this from happening.
123 Adds all available information to the report. Currently this includes a
124 text (XML) file describing the process context and, under Win32, a minidump
127 void AddAll(Context context
= Context_Exception
);
130 Add an XML file containing the current or exception context and the
133 bool AddContext(Context ctx
);
136 The same as @ref addcontext() AddContext(Context_Current).
138 bool AddCurrentContext();
141 The same as @ref adddump() AddDump(Context_Current).
143 bool AddCurrentDump();
146 Adds the minidump file to the debug report.
148 Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
149 can be installed under older systems to make minidumps available).
151 bool AddDump(Context ctx
);
154 The same as @ref addcontext() AddContext(Context_Exception).
156 bool AddExceptionContext();
159 The same as @ref adddump() AddDump(Context_Exception).
161 bool AddExceptionDump();
164 Add another file to the report. If @e filename is an absolute path, it is
165 copied to a file in the debug report directory with the same name. Otherwise
166 the file should already exist in this directory
168 @e description only exists to be displayed to the user in the report summary
169 shown by wxDebugReportPreview.
171 void AddFile(const wxString
& filename
,
172 const wxString
& description
);
175 This is a convenient wrapper around AddFile(). It
176 creates the file with the given @e name and writes @e text to it, then
177 adds the file to the report. The @e filename shouldn't contain the path.
179 Returns @true if file could be added successfully, @false if an IO error
182 bool AddText(const wxString
& filename
, const wxString
& text
,
183 const wxString
& description
);
186 This function may be overridden to add arbitrary custom context to the XML
187 context file created by AddContext(). By
188 default, it does nothing.
190 void DoAddCustomContext(wxXmlNode
* nodeRoot
);
193 This function may be overridden to modify the contents of the exception tag in
194 the XML context file.
196 bool DoAddExceptionInfo(wxXmlNode
* nodeContext
);
199 This function may be overridden to modify the contents of the modules tag in
200 the XML context file.
202 bool DoAddLoadedModules(wxXmlNode
* nodeModules
);
205 This function may be overridden to modify the contents of the system tag in
206 the XML context file.
208 bool DoAddSystemInfo(wxXmlNode
* nodeSystemInfo
);
211 Returns the name of the temporary directory used for the files in this report.
213 This method should be used to construct the full name of the files which you
214 wish to add to the report using AddFile().
216 const wxString
GetDirectory();
219 Retrieves the name (relative to
220 wxDebugReport::GetDirectory) and the description of the
221 file with the given index. If @e n is greater than or equal to the number of
222 filse, @false is returned.
224 bool GetFile(size_t n
, wxString
* name
, wxString
* desc
);
227 Gets the current number files in this report.
229 size_t GetFilesCount();
232 Gets the name used as a base name for various files, by default
233 wxApp::GetAppName is used.
235 wxString
GetReportName();
238 Returns @true if the object was successfully initialized. If this method
240 @false the report can't be used.
242 #define bool IsOk() /* implementation is private */
245 Processes this report: the base class simply notifies the user that the
246 report has been generated. This is usually not enough -- instead you
247 should override this method to do something more useful to you.
252 Removes the file from report: this is used by
253 wxDebugReportPreview to allow the user to
254 remove files potentially containing private information from the report.
256 void RemoveFile(const wxString
& name
);
259 Resets the directory name we use. The object can't be used any more after
260 this as it becomes uninitialized and invalid.
267 @class wxDebugReportPreviewStd
268 @wxheader{debugrpt.h}
270 wxDebugReportPreviewStd is a standard debug report preview window. It displays
271 a GUIdialog allowing the user to examine the contents of a debug report, remove
272 files from and add notes to it.
277 class wxDebugReportPreviewStd
: public wxDebugReportPreview
281 Trivial default constructor.
283 wxDebugReportPreviewStd();
287 wxDebugReportPreview::Show for more
290 bool Show(wxDebugReport
& dbgrpt
);
295 @class wxDebugReportUpload
296 @wxheader{debugrpt.h}
298 This class is used to upload a compressed file using HTTP POST request. As this
299 class derives from wxDebugReportCompress, before upload the report is
300 compressed in a single .ZIP file.
305 class wxDebugReportUpload
: public wxDebugReportCompress
311 This class will upload the compressed file created by its base class to an HTML
312 multipart/form-data form at the specified address. The @e url is the upload
313 page address, @e input is the name of the @c "type=file" control on
314 the form used for the file name and @e action is the value of the form
315 action field. The report is uploaded using @c @e curl program which
316 should be available, the @e curl parameter may be used to specify the full
319 wxDebugReportUpload(const wxString
& url
, const wxString
& input
,
320 const wxString
& action
);
325 This function may be overridden in a derived class to show the output from
326 curl: this may be an HTML page or anything else that the server returned.
327 Value returned by this function becomes the return value of
328 wxDebugReport::Process.
330 bool OnServerReply();