text: /////////////////////////////////////////////////////////////////////////////
  // Name:        debugrpt.h
  // Purpose:     interface of wxDebugReport*
  // Author:      wxWidgets team
  // 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);
  };
  
  