///////////////////////////////////////////////////////////////////////////// // Name: debugrpt.h // Purpose: interface of wxDebugReport* // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxDebugReportPreview 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: /** Default constructor. */ wxDebugReportPreview(); /** Destructor is trivial as well but should be virtual for a base class. */ 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. */ virtual bool Show(wxDebugReport& dbgrpt) const = 0; }; /** @class wxDebugReportCompress 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} */ class wxDebugReportCompress : public wxDebugReport { public: /** Default constructor does nothing special. */ wxDebugReportCompress(); /** Set the directory where the debug report should be generated. By default, the debug report is generated under user temporary files directory. This is usually fine if it is meant to be processed in some way (e.g. automatically uploaded to a remote server) but if the user is asked to manually upload or send the report, it may be more convenient to generate it in e.g. the users home directory and this function allows to do this. Notice that it should be called before wxDebugReport::Process() or it has no effect. @param dir The full path to an existing directory where the debug report file should be generated. @since 2.9.1 */ void SetCompressedFileDirectory(const wxString& dir); /** Set the base name of the generated debug report file. This function is similar to SetCompressedFileDirectory() but allows to change the base name of the file. Notice that the file extension will always be @c .zip. By default, a unique name constructed from wxApp::GetAppName(), the current process id and the current date and time is used. @param name The base name (i.e. without extension) of the file. @since 2.9.1 */ void SetCompressedFileBaseName(const wxString& name); /** Returns the full path of the compressed file (empty if creation failed). */ const wxString& GetCompressedFileName() const; }; /** @class wxDebugReport 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. 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. 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} */ 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. */ 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. */ virtual ~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. */ virtual bool AddContext(Context ctx); /** The same as calling AddContext(Context_Current). */ bool AddCurrentContext(); /** 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). */ virtual bool AddDump(Context ctx); /** The same as calling AddContext(Context_Exception). */ bool AddExceptionContext(); /** 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 will be searched in the temporary directory returned by GetDirectory(). The argument @a description only exists to be displayed to the user in the report summary shown by wxDebugReportPreview. @see GetDirectory(), AddText() */ virtual void AddFile(const wxString& filename, const wxString& description); /** 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 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; /** 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 files, then @false is returned. */ bool GetFile(size_t n, wxString* name, wxString* desc) const; /** Gets the current number files in this report. */ size_t GetFilesCount() const; /** Gets the name used as a base name for various files, by default wxApp::GetAppName() is used. */ virtual wxString GetReportName() const; /** Returns @true if the object was successfully initialized. If this method returns @false the report can't be used. */ bool IsOk() const; /** 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(); protected: /** This function may be overridden to add arbitrary custom context to the XML context file created by AddContext(). By default, it does nothing. */ virtual void DoAddCustomContext(wxXmlNode* nodeRoot); /** This function may be overridden to modify the contents of the exception tag in the XML context file. */ virtual bool DoAddExceptionInfo(wxXmlNode* nodeContext); /** This function may be overridden to modify the contents of the modules tag in the XML context file. */ virtual bool DoAddLoadedModules(wxXmlNode* nodeModules); /** This function may be overridden to modify the contents of the system tag in the XML context file. */ virtual bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo); }; /** @class wxDebugReportPreviewStd 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} */ class wxDebugReportPreviewStd : public wxDebugReportPreview { public: /** Trivial default constructor. */ wxDebugReportPreviewStd(); /** Shows the dialog. @see wxDebugReportPreview::Show() */ bool Show(wxDebugReport& dbgrpt) const; }; /** @class wxDebugReportUpload 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 @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& curl = "curl"); protected: /** 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(). */ virtual bool OnServerReply(const wxArrayString& reply); };