More initial reviews of d* interface headers.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53278 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -1,6 +1,6 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: debugrpt.h
|
||||
// Purpose: interface of wxDebugReportPreview
|
||||
// Purpose: interface of wxDebugReport*
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
@@ -10,16 +10,16 @@
|
||||
@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.
|
||||
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.
|
||||
class deriving from it is wxDebugReportPreviewStd.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
@@ -28,22 +28,24 @@ class wxDebugReportPreview
|
||||
{
|
||||
public:
|
||||
/**
|
||||
Trivial default constructor.
|
||||
Default constructor.
|
||||
*/
|
||||
wxDebugReportPreview();
|
||||
|
||||
/**
|
||||
dtor is trivial as well but should be virtual for a base class
|
||||
Destructor is trivial as well but should be virtual for a base class.
|
||||
*/
|
||||
~wxDebugReportPreview();
|
||||
virtual ~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.
|
||||
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.
|
||||
|
||||
@returns @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) const;
|
||||
virtual bool Show(wxDebugReport& dbgrpt) const;
|
||||
};
|
||||
|
||||
|
||||
@@ -52,9 +54,9 @@ public:
|
||||
@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.
|
||||
wxDebugReportCompress is a wxDebugReport which compresses all the files in
|
||||
this debug report into a single ZIP file in its wxDebugReport::Process()
|
||||
function.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
@@ -68,7 +70,8 @@ public:
|
||||
wxDebugReportCompress();
|
||||
|
||||
/**
|
||||
Returns the full path of the compressed file (empty if creation failed).
|
||||
Returns the full path of the compressed file (empty if creation
|
||||
failed).
|
||||
*/
|
||||
const wxString GetCompressedFileName() const;
|
||||
};
|
||||
@@ -79,26 +82,35 @@ public:
|
||||
@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().
|
||||
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 @ref page_samples_debugrpt.
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
A typical usage example:
|
||||
|
||||
@code
|
||||
wxDebugReport report;
|
||||
wxDebugReportPreviewStd preview;
|
||||
|
||||
report.AddCurrentContext(); // could also use AddAll()
|
||||
report.AddCurrentDump(); // to do both at once
|
||||
|
||||
if ( preview.Show(report) )
|
||||
report.Process();
|
||||
@endcode
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
@@ -106,25 +118,32 @@ public:
|
||||
class wxDebugReport
|
||||
{
|
||||
public:
|
||||
/**
|
||||
This enum is used for functions that report either the current state or
|
||||
the state during the last (fatal) exception.
|
||||
*/
|
||||
enum Context {
|
||||
Context_Current,
|
||||
Context_Exception
|
||||
};
|
||||
|
||||
/**
|
||||
The constructor creates a temporary directory where the files that will
|
||||
be included in the report are created. Use
|
||||
IsOk() to check for errors.
|
||||
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.
|
||||
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.
|
||||
text (XML) file describing the process context and, under Win32, a
|
||||
minidump file.
|
||||
*/
|
||||
void AddAll(Context context = Context_Exception);
|
||||
|
||||
@@ -135,89 +154,93 @@ public:
|
||||
bool AddContext(Context ctx);
|
||||
|
||||
/**
|
||||
The same as @ref addcontext() AddContext(Context_Current).
|
||||
The same as calling AddContext(Context_Current).
|
||||
*/
|
||||
bool AddCurrentContext();
|
||||
|
||||
/**
|
||||
The same as @ref adddump() AddDump(Context_Current).
|
||||
The same as calling 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).
|
||||
|
||||
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).
|
||||
The same as calling AddContext(Context_Exception).
|
||||
*/
|
||||
bool AddExceptionContext();
|
||||
|
||||
/**
|
||||
The same as @ref adddump() AddDump(Context_Exception).
|
||||
The same as calling AddDump(Context_Exception).
|
||||
*/
|
||||
bool AddExceptionDump();
|
||||
|
||||
/**
|
||||
Add another file to the report. If @a 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
|
||||
@a description only exists to be displayed to the user in the report summary
|
||||
shown by wxDebugReportPreview.
|
||||
Add another file to the report. If @a 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
|
||||
@a description only exists to be displayed to the user in the report
|
||||
summary shown by wxDebugReportPreview.
|
||||
|
||||
@see GetDirectory(), AddText()
|
||||
*/
|
||||
void AddFile(const wxString& filename,
|
||||
const wxString& description);
|
||||
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 @a text to it, then
|
||||
adds the file to the report. The @a filename shouldn't contain the path.
|
||||
Returns @true if file could be added successfully, @false if an IO error
|
||||
occurred.
|
||||
This is a convenient wrapper around AddFile(). It creates the file with
|
||||
the given @a name and writes @a text to it, then adds the file to the
|
||||
report. The @a 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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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().
|
||||
This method should be used to construct the full name of the files
|
||||
which you wish to add to the report using AddFile().
|
||||
|
||||
@returns The name of the temporary directory used for the files in this
|
||||
report.
|
||||
*/
|
||||
const wxString GetDirectory() const;
|
||||
|
||||
/**
|
||||
Retrieves the name (relative to
|
||||
wxDebugReport::GetDirectory) and the description of the
|
||||
file with the given index. If @a n is greater than or equal to the number of
|
||||
filse, @false is returned.
|
||||
Retrieves the name (relative to GetDirectory()) and the description of
|
||||
the file with the given index. If @a n is greater than or equal to the
|
||||
number of filse, @false is returned.
|
||||
*/
|
||||
bool GetFile(size_t n, wxString* name, wxString* desc) const;
|
||||
|
||||
@@ -228,14 +251,13 @@ public:
|
||||
|
||||
/**
|
||||
Gets the name used as a base name for various files, by default
|
||||
wxApp::GetAppName is used.
|
||||
wxApp::GetAppName() is used.
|
||||
*/
|
||||
wxString GetReportName() const;
|
||||
|
||||
/**
|
||||
Returns @true if the object was successfully initialized. If this method
|
||||
returns
|
||||
@false the report can't be used.
|
||||
Returns @true if the object was successfully initialized. If this
|
||||
method returns @false the report can't be used.
|
||||
*/
|
||||
bool IsOk() const;
|
||||
|
||||
@@ -247,15 +269,15 @@ public:
|
||||
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.
|
||||
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.
|
||||
Resets the directory name we use. The object can't be used any more
|
||||
after this as it becomes uninitialized and invalid.
|
||||
*/
|
||||
void Reset();
|
||||
};
|
||||
@@ -266,9 +288,9 @@ public:
|
||||
@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.
|
||||
wxDebugReportPreviewStd is a standard debug report preview window. It
|
||||
displays a dialog allowing the user to examine the contents of a debug
|
||||
report, remove files from and add notes to it.
|
||||
|
||||
@library{wxqa}
|
||||
@category{debugging}
|
||||
@@ -282,9 +304,9 @@ public:
|
||||
wxDebugReportPreviewStd();
|
||||
|
||||
/**
|
||||
Show the dialog, see
|
||||
wxDebugReportPreview::Show for more
|
||||
information.
|
||||
Shows the dialog.
|
||||
|
||||
@see wxDebugReportPreview::Show()
|
||||
*/
|
||||
bool Show(wxDebugReport& dbgrpt) const;
|
||||
};
|
||||
@@ -295,9 +317,9 @@ public:
|
||||
@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.
|
||||
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}
|
||||
@@ -306,25 +328,24 @@ 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 @a url is the upload
|
||||
page address, @a input is the name of the @c "type=file" control on
|
||||
the form used for the file name and @a 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.
|
||||
This class will upload the compressed file created by its base class to
|
||||
an HTML multipart/form-data form at the specified address. The @a url
|
||||
is the upload page address, @a input is the name of the @c "type=file"
|
||||
control on the form used for the file name and @a action is the value
|
||||
of the form action field. The report is uploaded using the @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);
|
||||
const wxString& action,
|
||||
const wxString& curl = "curl");
|
||||
|
||||
/**
|
||||
)
|
||||
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.
|
||||
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();
|
||||
bool OnServerReply(const wxArrayString& reply);
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user