X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/debugrpt.h diff --git a/interface/debugrpt.h b/interface/debugrpt.h index bdb44b9922..bb40cb1997 100644 --- a/interface/debugrpt.h +++ b/interface/debugrpt.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: debugrpt.h -// Purpose: documentation for wxDebugReportPreview class +// 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,32 +28,35 @@ 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. + + @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); + virtual bool Show(wxDebugReport& dbgrpt) const; }; + /** @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} @@ -67,36 +70,47 @@ 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 wxString GetCompressedFileName() const; }; + /** @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} @@ -104,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); @@ -133,113 +154,112 @@ 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 @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. + 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 @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. + 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. + + @return @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); + 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(). + + @return The name of the temporary directory used for the files in this + report. */ - const wxString GetDirectory(); + const wxString GetDirectory() const; /** - 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. + 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); + bool GetFile(size_t n, wxString* name, wxString* desc) const; /** Gets the current number files in this report. */ - size_t GetFilesCount(); + size_t GetFilesCount() const; /** Gets the name used as a base name for various files, by default - wxApp::GetAppName is used. + wxApp::GetAppName() is used. */ - wxString GetReportName(); + 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. */ -#define bool IsOk() /* implementation is private */ + bool IsOk() const; /** Processes this report: the base class simply notifies the user that the @@ -249,27 +269,28 @@ 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(); }; + /** @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} @@ -283,21 +304,22 @@ public: wxDebugReportPreviewStd(); /** - Show the dialog, see - wxDebugReportPreview::Show for more - information. + Shows the dialog. + + @see wxDebugReportPreview::Show() */ - bool Show(wxDebugReport& dbgrpt); + bool Show(wxDebugReport& dbgrpt) const; }; + /** @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,26 +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 @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. + 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); }; +