added interface headers with latest discussed changes
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
331
interface/debugrpt.h
Normal file
331
interface/debugrpt.h
Normal file
@@ -0,0 +1,331 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: debugrpt.h
|
||||
// Purpose: documentation for wxDebugReportPreview class
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/**
|
||||
@class wxDebugReportPreview
|
||||
@wxheader{debugrpt.h}
|
||||
|
||||
This class presents the debug report to the user and allows him to veto report
|
||||
entirely or remove some parts of it. Although not mandatory, using this class
|
||||
is strongly recommended as data included in the debug report might contain
|
||||
sensitive private information and the user should be notified about it as well
|
||||
as having a possibility to examine the data which had been gathered to check
|
||||
whether this is effectively the case and discard the debug report if it is.
|
||||
|
||||
wxDebugReportPreview is an abstract base class, currently the only concrete
|
||||
class deriving from it is
|
||||
wxDebugReportPreviewStd.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
*/
|
||||
class wxDebugReportPreview
|
||||
{
|
||||
public:
|
||||
/**
|
||||
Trivial default constructor.
|
||||
*/
|
||||
wxDebugReportPreview();
|
||||
|
||||
/**
|
||||
dtor is trivial as well but should be virtual for a base class
|
||||
*/
|
||||
~wxDebugReportPreview();
|
||||
|
||||
/**
|
||||
Present the report to the user and allow him to modify it by removing some or
|
||||
all of the files and, potentially, adding some notes. Return @true if the
|
||||
report should be processed or @false if the user chose to cancel report
|
||||
generation or removed all files from it.
|
||||
*/
|
||||
bool Show(wxDebugReport& dbgrpt);
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxDebugReportCompress
|
||||
@wxheader{debugrpt.h}
|
||||
|
||||
wxDebugReportCompress is a wxDebugReport which
|
||||
compresses all the files in this debug report into a single .ZIP file in its
|
||||
@c @e Process() function.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
*/
|
||||
class wxDebugReportCompress : public wxDebugReport
|
||||
{
|
||||
public:
|
||||
/**
|
||||
Default constructor does nothing special.
|
||||
*/
|
||||
wxDebugReportCompress();
|
||||
|
||||
/**
|
||||
Returns the full path of the compressed file (empty if creation failed).
|
||||
*/
|
||||
const wxString GetCompressedFileName();
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxDebugReport
|
||||
@wxheader{debugrpt.h}
|
||||
|
||||
wxDebugReport is used to generate a debug report, containing information about
|
||||
the program current state. It is usually used from
|
||||
wxApp::OnFatalException as shown in the
|
||||
sample.
|
||||
|
||||
A wxDebugReport object contains one or more files. A few of them can be created
|
||||
by the
|
||||
class itself but more can be created from the outside and then added to the
|
||||
report. Also note that several virtual functions may be overridden to further
|
||||
customize the class behaviour.
|
||||
|
||||
Once a report is fully assembled, it can simply be left in the temporary
|
||||
directory so that the user can email it to the developers (in which case you
|
||||
should still use wxDebugReportCompress to
|
||||
compress it in a single file) or uploaded to a Web server using
|
||||
wxDebugReportUpload (setting up the Web server
|
||||
to accept uploads is your responsibility, of course). Other handlers, for
|
||||
example for
|
||||
automatically emailing the report, can be defined as well but are not currently
|
||||
included in wxWidgets.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
*/
|
||||
class wxDebugReport
|
||||
{
|
||||
public:
|
||||
/**
|
||||
The constructor creates a temporary directory where the files that will
|
||||
be included in the report are created. Use
|
||||
IsOk() to check for errors.
|
||||
*/
|
||||
wxDebugReport();
|
||||
|
||||
/**
|
||||
The destructor normally destroys the temporary directory created in the
|
||||
constructor
|
||||
with all the files it contains. Call Reset() to
|
||||
prevent this from happening.
|
||||
*/
|
||||
~wxDebugReport();
|
||||
|
||||
/**
|
||||
Adds all available information to the report. Currently this includes a
|
||||
text (XML) file describing the process context and, under Win32, a minidump
|
||||
file.
|
||||
*/
|
||||
void AddAll(Context context = Context_Exception);
|
||||
|
||||
/**
|
||||
Add an XML file containing the current or exception context and the
|
||||
stack trace.
|
||||
*/
|
||||
bool AddContext(Context ctx);
|
||||
|
||||
/**
|
||||
The same as @ref addcontext() AddContext(Context_Current).
|
||||
*/
|
||||
bool AddCurrentContext();
|
||||
|
||||
/**
|
||||
The same as @ref adddump() AddDump(Context_Current).
|
||||
*/
|
||||
bool AddCurrentDump();
|
||||
|
||||
/**
|
||||
Adds the minidump file to the debug report.
|
||||
|
||||
Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
|
||||
can be installed under older systems to make minidumps available).
|
||||
*/
|
||||
bool AddDump(Context ctx);
|
||||
|
||||
/**
|
||||
The same as @ref addcontext() AddContext(Context_Exception).
|
||||
*/
|
||||
bool AddExceptionContext();
|
||||
|
||||
/**
|
||||
The same as @ref adddump() AddDump(Context_Exception).
|
||||
*/
|
||||
bool AddExceptionDump();
|
||||
|
||||
/**
|
||||
Add another file to the report. If @e filename is an absolute path, it is
|
||||
copied to a file in the debug report directory with the same name. Otherwise
|
||||
the file should already exist in this directory
|
||||
|
||||
@e description only exists to be displayed to the user in the report summary
|
||||
shown by wxDebugReportPreview.
|
||||
*/
|
||||
void AddFile(const wxString& filename,
|
||||
const wxString& description);
|
||||
|
||||
/**
|
||||
This is a convenient wrapper around AddFile(). It
|
||||
creates the file with the given @e name and writes @e text to it, then
|
||||
adds the file to the report. The @e filename shouldn't contain the path.
|
||||
|
||||
Returns @true if file could be added successfully, @false if an IO error
|
||||
occurred.
|
||||
*/
|
||||
bool AddText(const wxString& filename, const wxString& text,
|
||||
const wxString& description);
|
||||
|
||||
/**
|
||||
This function may be overridden to add arbitrary custom context to the XML
|
||||
context file created by AddContext(). By
|
||||
default, it does nothing.
|
||||
*/
|
||||
void DoAddCustomContext(wxXmlNode * nodeRoot);
|
||||
|
||||
/**
|
||||
This function may be overridden to modify the contents of the exception tag in
|
||||
the XML context file.
|
||||
*/
|
||||
bool DoAddExceptionInfo(wxXmlNode* nodeContext);
|
||||
|
||||
/**
|
||||
This function may be overridden to modify the contents of the modules tag in
|
||||
the XML context file.
|
||||
*/
|
||||
bool DoAddLoadedModules(wxXmlNode* nodeModules);
|
||||
|
||||
/**
|
||||
This function may be overridden to modify the contents of the system tag in
|
||||
the XML context file.
|
||||
*/
|
||||
bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
|
||||
|
||||
/**
|
||||
Returns the name of the temporary directory used for the files in this report.
|
||||
|
||||
This method should be used to construct the full name of the files which you
|
||||
wish to add to the report using AddFile().
|
||||
*/
|
||||
const wxString GetDirectory();
|
||||
|
||||
/**
|
||||
Retrieves the name (relative to
|
||||
wxDebugReport::GetDirectory) and the description of the
|
||||
file with the given index. If @e n is greater than or equal to the number of
|
||||
filse, @false is returned.
|
||||
*/
|
||||
bool GetFile(size_t n, wxString* name, wxString* desc);
|
||||
|
||||
/**
|
||||
Gets the current number files in this report.
|
||||
*/
|
||||
size_t GetFilesCount();
|
||||
|
||||
/**
|
||||
Gets the name used as a base name for various files, by default
|
||||
wxApp::GetAppName is used.
|
||||
*/
|
||||
wxString GetReportName();
|
||||
|
||||
/**
|
||||
Returns @true if the object was successfully initialized. If this method
|
||||
returns
|
||||
@false the report can't be used.
|
||||
*/
|
||||
#define bool IsOk() /* implementation is private */
|
||||
|
||||
/**
|
||||
Processes this report: the base class simply notifies the user that the
|
||||
report has been generated. This is usually not enough -- instead you
|
||||
should override this method to do something more useful to you.
|
||||
*/
|
||||
bool Process();
|
||||
|
||||
/**
|
||||
Removes the file from report: this is used by
|
||||
wxDebugReportPreview to allow the user to
|
||||
remove files potentially containing private information from the report.
|
||||
*/
|
||||
void RemoveFile(const wxString& name);
|
||||
|
||||
/**
|
||||
Resets the directory name we use. The object can't be used any more after
|
||||
this as it becomes uninitialized and invalid.
|
||||
*/
|
||||
void Reset();
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxDebugReportPreviewStd
|
||||
@wxheader{debugrpt.h}
|
||||
|
||||
wxDebugReportPreviewStd is a standard debug report preview window. It displays
|
||||
a GUIdialog allowing the user to examine the contents of a debug report, remove
|
||||
files from and add notes to it.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
*/
|
||||
class wxDebugReportPreviewStd : public wxDebugReportPreview
|
||||
{
|
||||
public:
|
||||
/**
|
||||
Trivial default constructor.
|
||||
*/
|
||||
wxDebugReportPreviewStd();
|
||||
|
||||
/**
|
||||
Show the dialog, see
|
||||
wxDebugReportPreview::Show for more
|
||||
information.
|
||||
*/
|
||||
bool Show(wxDebugReport& dbgrpt);
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxDebugReportUpload
|
||||
@wxheader{debugrpt.h}
|
||||
|
||||
This class is used to upload a compressed file using HTTP POST request. As this
|
||||
class derives from wxDebugReportCompress, before upload the report is
|
||||
compressed in a single .ZIP file.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
*/
|
||||
class wxDebugReportUpload : public wxDebugReportCompress
|
||||
{
|
||||
public:
|
||||
/**
|
||||
)
|
||||
|
||||
This class will upload the compressed file created by its base class to an HTML
|
||||
multipart/form-data form at the specified address. The @e url is the upload
|
||||
page address, @e input is the name of the @c "type=file" control on
|
||||
the form used for the file name and @e action is the value of the form
|
||||
action field. The report is uploaded using @c @e curl program which
|
||||
should be available, the @e curl parameter may be used to specify the full
|
||||
path to it.
|
||||
*/
|
||||
wxDebugReportUpload(const wxString& url, const wxString& input,
|
||||
const wxString& action);
|
||||
|
||||
/**
|
||||
)
|
||||
|
||||
This function may be overridden in a derived class to show the output from
|
||||
curl: this may be an HTML page or anything else that the server returned.
|
||||
Value returned by this function becomes the return value of
|
||||
wxDebugReport::Process.
|
||||
*/
|
||||
bool OnServerReply();
|
||||
};
|
||||
Reference in New Issue
Block a user