--- /dev/null
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: debugrpt.tex
+%% Purpose: wxDebugReport documentation
+%% Author: Vadim Zeitlin
+%% Modified by:
+%% Created: 2005-03-21
+%% RCS-ID: $Id$
+%% Copyright: (c) Vadim Zeitlin 2005
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDebugReport}}\label{wxdebugreport}
+
+wxDebugReport is used to generate a debug report, containing information about
+the program current state. It is usually used from
+\helpref{wxApp::OnFatalException()}{wxapponfatalexception} as shown in the
+\helpref{sample}{sampledebugrpt}.
+
+wxDebugReport 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 report is fully assembled, it can be simply left in the temporary
+directory so that the user can email it to the developers (in which case you
+should still use \helpref{wxDebugReportCompress}{wxdebugreportcompress} to
+compress it in a single file) or uploaded to a Web server using
+\helpref{wxDebugReportUpload}{wxdebugreportupload} (setting up the Web server
+to accept uploads is your responsibility, of course). Other handlers, e.g. for
+automatically emailing the report, can be defined as well but are not currently
+included in wxWidgets.
+
+\wxheading{Example of use}
+
+\begin{verbatim}
+ wxDebugReport report;
+ wxDebugReportPreviewStd preview;
+
+ report.AddCurrentContext(); // could also use AddAll()
+ report.AddCurrentDump(); // to do both at once
+
+ if ( preview.Show(report) )
+ report.Process();
+\end{verbatim}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/debugrpt.h>
+
+\wxheading{Data structures}
+
+This enum used for the functions which may report either the current state
+or the state during the last (fatal) exception:
+\begin{verbatim}
+enum wxDebugReport::Context
+{
+ Context_Curent,
+ Context_Exception
+};
+\end{verbatim}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxDebugReport::wxDebugReport}\label{wxdebugreportwxdebugreport}
+
+\func{}{wxDebugReport}{\void}
+
+Constructor creates a temporary directory where the files which will
+be included in the report are created. Use
+\helpref{IsOk()}{wxdebugreportisok} to check for errors.
+
+
+\membersection{wxDebugReport::\destruct{wxDebugReport}}\label{wxdebugreportdtor}
+
+\func{}{\destruct{wxDebugReport}}{\void}
+
+Destructor normally destroys the temporary directory created in the constructor
+with all the files it contains, call \helpref{Reset()}{wxdebugreportreset} to
+prevent this from happening.
+
+
+\membersection{wxDebugReport::AddAll}\label{wxdebugreportaddall}
+
+\func{void}{AddAll}{\param{Context }{context = Context\_Exception}}
+
+Add all available information to the report. Currently this includes a
+text (XML) file describing the process context and, under Win32, a minidump
+file.
+
+
+\membersection{wxDebugReport::AddContext}\label{wxdebugreportaddcontext}
+
+\func{bool}{AddContext}{\param{Context }{ctx}}
+
+Add an XML file containing the current or exception context and the
+stack trace.
+
+
+\membersection{wxDebugReport::AddCurrentContext}\label{wxdebugreportaddcurrentcontext}
+
+\func{bool}{AddCurrentContext}{\void}
+
+Same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}.
+
+
+\membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump}
+
+\func{bool}{AddCurrentDump}{\void}
+
+Same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}.
+
+
+\membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump}
+
+\func{bool}{AddDump}{\param{Context }{ctx}}
+
+Adds minidump file to the debug report.
+
+Minidumps are only available under recent Win32 versions (\texttt{dbghlp32.dll}
+can be installed under older systems to make minidumps available).
+
+
+\membersection{wxDebugReport::AddExceptionContext}\label{wxdebugreportaddexceptioncontext}
+
+\func{bool}{AddExceptionContext}{\void}
+
+Same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}.
+
+
+\membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump}
+
+\func{bool}{AddExceptionDump}{\void}
+
+Same as \helpref{AddDump(Context\_Exception)}{wxdebugreportadddump}.
+
+
+\membersection{wxDebugReport::AddFile}\label{wxdebugreportaddfile}
+
+\func{void}{AddFile}{\param{const wxString\& }{name}, \param{const wxString\& }{description}}
+
+Add another file to the report: the file must already exist on disk. Its name
+is relative to \helpref{GetDirectory()}{wxdebugreportgetdirectory}.
+
+\arg{description} only exists to be shown to the user in the report summary
+shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}.
+
+
+\membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext}
+
+\func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}}
+
+This function may be overridden to add arbitrary custom context to the XML
+context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By
+default, it does nothing.
+
+
+\membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo}
+
+\func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}}
+
+This function may be overridden to modify the contents of the exception tag in
+the XML context file.
+
+
+\membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules}
+
+\func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}}
+
+This function may be overridden to modify the contents of the modules tag in
+the XML context file.
+
+
+\membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo}
+
+\func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}}
+
+This function may be overridden to modify the contents of the system tag in
+the XML context file.
+
+
+\membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory}
+
+\constfunc{const wxString\&}{GetDirectory}{\void}
+
+Return 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 \helpref{AddFile}{wxdebugreportaddfile}.
+
+
+\membersection{wxDebugReport::GetFile}\label{wxdebugreportgetfile}
+
+\constfunc{bool}{GetFile}{\param{size\_t }{n}, \param{wxString* }{name}, \param{wxString* }{desc}}
+
+Retrieve the name (relative to
+\helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the
+file with the given index. If \arg{n} is greater than or equal to the number of
+filse, \false is returned.
+
+
+\membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount}
+
+\constfunc{size\_t}{GetFilesCount}{\void}
+
+Get the current number files in this report.
+
+
+\membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname}
+
+\constfunc{wxString}{GetReportName}{\void}
+
+Get the name used as base name for various files, by default
+\helpref{wxApp::GetName()}{wxappgetname} is used.
+
+
+\membersection{wxDebugReport::IsOk}\label{wxdebugreportisok}
+
+\constfunc{bool}{IsOk}{\void}
+
+Return \true if the object was successfully initialized, if this method returns
+\false the report can't be used.
+
+
+\membersection{wxDebugReport::Process}\label{wxdebugreportprocess}
+
+\func{bool}{Process}{\void}
+
+Process 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.
+
+
+\membersection{wxDebugReport::RemoveFile}\label{wxdebugreportremovefile}
+
+\func{void}{RemoveFile}{\param{const wxString\& }{name}}
+
+Remove the file from report: this is used by
+\helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to
+remove files potentially containing private information from the report.
+
+
+\membersection{wxDebugReport::Reset}\label{wxdebugreportreset}
+
+\func{void}{Reset}{\void}
+
+Reset the directory name we use, the object can't be used any more after
+this as it becomes invalid/uninitialized.
+
--- /dev/null
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: debugrptpvw.tex
+%% Purpose: wxDebugReportPreview documentation
+%% Author: Vadim Zeitlin
+%% Modified by:
+%% Created: 2005-03-21
+%% RCS-ID: $Id$
+%% Copyright: (c) Vadim Zeitlin 2005
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDebugReportPreview}}\label{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
+\helpref{wxDebugReportPreviewStd}{wxdebugreportpreviewstd}.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/debugrpt.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxDebugReportPreview::wxDebugReportPreview}\label{wxdebugreportpreviewwxdebugreportpreview}
+
+\func{}{wxDebugReportPreview}{\void}
+
+Trivial default constructor.
+
+
+\membersection{wxDebugReportPreview::\destruct{wxDebugReportPreview}}\label{wxdebugreportpreviewdtor}
+
+\func{}{\destruct{wxDebugReportPreview}}{\void}
+
+dtor is trivial as well but should be virtual for a base class
+
+
+\membersection{wxDebugReportPreview::Show}\label{wxdebugreportpreviewshow}
+
+\constfunc{bool}{Show}{\param{wxDebugReport\& }{dbgrpt}}
+
+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.
+
--- /dev/null
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: debugrptup.tex
+%% Purpose: wxDebugReportUpload documentation
+%% Author: Vadim Zeitlin
+%% Modified by:
+%% Created: 2005-03-21
+%% RCS-ID: $Id$
+%% Copyright: (c) Vadim Zeitlin 2005
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDebugReportUpload}}\label{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.
+
+\wxheading{Derived from}
+
+\helpref{wxDebugReportCompress}{wxdebugreportcompress}
+
+\wxheading{Include files}
+
+<wx/debugrpt.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDebugReportUpload::wxDebugReportUpload}\label{wxdebugreportuploadwxdebugreportupload}
+
+\func{}{wxDebugReportUpload}{\param{const wxString\& }{url}, \param{const wxString\& }{input}, \param{const wxString\& }{action}, \param{const wxString\& }{curl = \_T("curl")}}
+
+This class will upload the compressed file created by its base class to an HTML
+multipart/form-data form at the specified address. The \arg{url} is the upload
+page address, \arg{input} is the name of the \texttt{"type=file"} control on
+the form used for the file name and \arg{action} is the value of the form
+action field. The report is uploaded using \texttt{\textit{curl}} program which
+should be available, the \arg{curl} parameter may be used to specify the full
+path to it.
+
+
+\membersection{wxDebugReportUpload::OnServerReply}\label{wxdebugreportuploadonserverreply}
+
+\func{bool}{OnServerReply}{\param{const wxArrayString\& }{WXUNUSED(reply)}}
+
+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
+\helpref{wxDebugReport::Process()}{wxdebugreportprocess}.
+
+
projects / wxWidgets.git / commitdiff
