[wxWidgets.git] / interface / debugrpt.h

/////////////////////////////////////////////////////////////////////////////
// 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();
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: debugrpt.h
	3	// Purpose: documentation for wxDebugReportPreview class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxDebugReportPreview
	11	@wxheader{debugrpt.h}
7c913512	12
23324ae1 FM	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.
7c913512	19
23324ae1	20	wxDebugReportPreview is an abstract base class, currently the only concrete
7c913512	21	class deriving from it is
23324ae1	22	wxDebugReportPreviewStd.
7c913512	23
23324ae1 FM	24	@library{wxqa}
	25	@category{debugging}
	26	*/
7c913512	27	class wxDebugReportPreview
23324ae1 FM	28	{
	29	public:
	30	/**
	31	Trivial default constructor.
	32	*/
	33	wxDebugReportPreview();
	34
	35	/**
	36	dtor is trivial as well but should be virtual for a base class
	37	*/
	38	~wxDebugReportPreview();
	39
	40	/**
	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.
	45	*/
	46	bool Show(wxDebugReport& dbgrpt);
	47	};
	48
	49
	50	/**
	51	@class wxDebugReportCompress
	52	@wxheader{debugrpt.h}
7c913512	53
23324ae1 FM	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.
7c913512	57
23324ae1 FM	58	@library{wxqa}
	59	@category{debugging}
	60	*/
	61	class wxDebugReportCompress : public wxDebugReport
	62	{
	63	public:
	64	/**
	65	Default constructor does nothing special.
	66	*/
	67	wxDebugReportCompress();
	68
	69	/**
	70	Returns the full path of the compressed file (empty if creation failed).
	71	*/
	72	const wxString GetCompressedFileName();
	73	};
	74
	75
	76	/**
	77	@class wxDebugReport
	78	@wxheader{debugrpt.h}
7c913512	79
23324ae1	80	wxDebugReport is used to generate a debug report, containing information about
7c913512 FM	81	the program current state. It is usually used from
7c913512 FM	82	wxApp::OnFatalException as shown in the
23324ae1	83	sample.
7c913512	84
23324ae1 FM	85	A wxDebugReport object contains one or more files. A few of them can be created
	86	by the
	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.
7c913512	90
23324ae1 FM	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
7c913512	94	compress it in a single file) or uploaded to a Web server using
23324ae1 FM	95	wxDebugReportUpload (setting up the Web server
	96	to accept uploads is your responsibility, of course). Other handlers, for
	97	example for
	98	automatically emailing the report, can be defined as well but are not currently
	99	included in wxWidgets.
7c913512	100
23324ae1 FM	101	@library{wxqa}
	102	@category{debugging}
	103	*/
7c913512	104	class wxDebugReport
23324ae1 FM	105	{
	106	public:
	107	/**
	108	The constructor creates a temporary directory where the files that will
7c913512	109	be included in the report are created. Use
23324ae1 FM	110	IsOk() to check for errors.
	111	*/
	112	wxDebugReport();
	113
	114	/**
	115	The destructor normally destroys the temporary directory created in the
	116	constructor
	117	with all the files it contains. Call Reset() to
	118	prevent this from happening.
	119	*/
	120	~wxDebugReport();
	121
	122	/**
	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
	125	file.
	126	*/
	127	void AddAll(Context context = Context_Exception);
	128
	129	/**
	130	Add an XML file containing the current or exception context and the
	131	stack trace.
	132	*/
	133	bool AddContext(Context ctx);
	134
	135	/**
	136	The same as @ref addcontext() AddContext(Context_Current).
	137	*/
	138	bool AddCurrentContext();
	139
	140	/**
	141	The same as @ref adddump() AddDump(Context_Current).
	142	*/
	143	bool AddCurrentDump();
	144
	145	/**
	146	Adds the minidump file to the debug report.
	147
7c913512	148	Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
23324ae1 FM	149	can be installed under older systems to make minidumps available).
	150	*/
	151	bool AddDump(Context ctx);
	152
	153	/**
	154	The same as @ref addcontext() AddContext(Context_Exception).
	155	*/
	156	bool AddExceptionContext();
	157
	158	/**
	159	The same as @ref adddump() AddDump(Context_Exception).
	160	*/
	161	bool AddExceptionDump();
	162
	163	/**
	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
	167
	168	@e description only exists to be displayed to the user in the report summary
	169	shown by wxDebugReportPreview.
	170	*/
	171	void AddFile(const wxString& filename,
	172	const wxString& description);
	173
	174	/**
	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.
	178
	179	Returns @true if file could be added successfully, @false if an IO error
	180	occurred.
	181	*/
	182	bool AddText(const wxString& filename, const wxString& text,
	183	const wxString& description);
	184
	185	/**
	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.
	189	*/
	190	void DoAddCustomContext(wxXmlNode * nodeRoot);
	191
	192	/**
	193	This function may be overridden to modify the contents of the exception tag in
	194	the XML context file.
	195	*/
	196	bool DoAddExceptionInfo(wxXmlNode* nodeContext);
	197
	198	/**
	199	This function may be overridden to modify the contents of the modules tag in
	200	the XML context file.
	201	*/
	202	bool DoAddLoadedModules(wxXmlNode* nodeModules);
	203
	204	/**
	205	This function may be overridden to modify the contents of the system tag in
	206	the XML context file.
	207	*/
	208	bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
	209
	210	/**
	211	Returns the name of the temporary directory used for the files in this report.
	212
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().
215	*/
216	const wxString GetDirectory();
217
218	/**
7c913512	219	Retrieves the name (relative to
23324ae1 FM	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.
	223	*/
	224	bool GetFile(size_t n, wxString* name, wxString* desc);
	225
	226	/**
	227	Gets the current number files in this report.
	228	*/
	229	size_t GetFilesCount();
	230
	231	/**
7c913512	232	Gets the name used as a base name for various files, by default
23324ae1 FM	233	wxApp::GetAppName is used.
	234	*/
	235	wxString GetReportName();
	236
	237	/**
	238	Returns @true if the object was successfully initialized. If this method
7c913512	239	returns
23324ae1 FM	240	@false the report can't be used.
	241	*/
	242	#define bool IsOk() /* implementation is private */
	243
	244	/**
	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.
	248	*/
	249	bool Process();
	250
	251	/**
7c913512	252	Removes the file from report: this is used by
23324ae1 FM	253	wxDebugReportPreview to allow the user to
	254	remove files potentially containing private information from the report.
	255	*/
	256	void RemoveFile(const wxString& name);
	257
	258	/**
	259	Resets the directory name we use. The object can't be used any more after
	260	this as it becomes uninitialized and invalid.
	261	*/
	262	void Reset();
	263	};
	264
	265
	266	/**
	267	@class wxDebugReportPreviewStd
	268	@wxheader{debugrpt.h}
7c913512	269
23324ae1 FM	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.
7c913512	273
23324ae1 FM	274	@library{wxqa}
	275	@category{debugging}
	276	*/
	277	class wxDebugReportPreviewStd : public wxDebugReportPreview
	278	{
	279	public:
	280	/**
	281	Trivial default constructor.
	282	*/
	283	wxDebugReportPreviewStd();
	284
	285	/**
7c913512	286	Show the dialog, see
23324ae1 FM	287	wxDebugReportPreview::Show for more
	288	information.
	289	*/
	290	bool Show(wxDebugReport& dbgrpt);
	291	};
	292
	293
	294	/**
	295	@class wxDebugReportUpload
	296	@wxheader{debugrpt.h}
7c913512	297
23324ae1 FM	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.
7c913512	301
23324ae1 FM	302	@library{wxqa}
	303	@category{debugging}
	304	*/
	305	class wxDebugReportUpload : public wxDebugReportCompress
	306	{
	307	public:
	308	/**
	309	)
	310
	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
	317	path to it.
	318	*/
	319	wxDebugReportUpload(const wxString& url, const wxString& input,
	320	const wxString& action);
	321
	322	/**
	323	)
	324
	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.
7c913512	327	Value returned by this function becomes the return value of
23324ae1 FM	328	wxDebugReport::Process.
	329	*/
	330	bool OnServerReply();
	331	};