xpcom/system/nsICrashReporter.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIFile;
   8 interface nsIURL;
   9
  10 /**
  11  * Provides access to crash reporting functionality.
  12  *
  13  * @status UNSTABLE - This interface is not frozen and will probably change in
  14  *                    future releases.
  15  */
  16
  17 [scriptable, uuid(4b74c39a-cf69-4a8a-8e63-169d81ad1ecf)]
  18 interface nsICrashReporter : nsISupports
  19 {
  20   /**
  21    * Get the enabled status of the crash reporter.
  22    */
  23   readonly attribute boolean crashReporterEnabled;
  24
  25   /**
  26    * Enable or disable crash reporting at runtime. Not available to script
  27    * because the JS engine relies on proper exception handler chaining.
  28    */
  29   [noscript]
  30   void setEnabled(in bool enabled);
  31
  32   /**
  33    * Get or set the URL to which crash reports will be submitted.
  34    * Only https and http URLs are allowed, as the submission is handled
  35    * by OS-native networking libraries.
  36    *
  37    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
  38    * @throw NS_ERROR_INVALID_ARG on set if a non-http(s) URL is assigned
  39    * @throw NS_ERROR_FAILURE on get if no URL is set
  40    */
  41   attribute nsIURL serverURL;
  42
  43   /**
  44    * Get or set the path on the local system to which minidumps will be
  45    * written when a crash happens.
  46    *
  47    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
  48    */
  49   attribute nsIFile minidumpPath;
  50
  51   /**
  52    * Get the minidump file corresponding to the specified ID.
  53    *
  54    * @param id
  55    *        ID of the crash. Likely a UUID.
  56    *
  57    * @return The minidump file associated with the ID.
  58    *
  59    * @throw NS_ERROR_FILE_NOT_FOUND if the minidump could not be found
  60    */
  61   nsIFile getMinidumpForID(in AString id);
  62
  63   /**
  64    * Get the extra file corresponding to the specified ID.
  65    *
  66    * @param id
  67    *        ID of the crash. Likely a UUID.
  68    *
  69    * @return The extra file associated with the ID.
  70    *
  71    * @throw NS_ERROR_FILE_NOT_FOUND if the extra file could not be found
  72    */
  73   nsIFile getExtraFileForID(in AString id);
  74
  75   /**
  76    * Add some extra data to be submitted with a crash report.
  77    *
  78    * @param key
  79    *        Name of a known crash annotation constant.
  80    * @param data
  81    *        Data to be added.
  82    *
  83    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
  84    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value or data
  85    *                             contains invalid characters.  Invalid
  86    *                             character for data is '\0'.
  87    */
  88   void annotateCrashReport(in AUTF8String key, in AUTF8String data);
  89
  90   /**
  91    * Remove a crash report annotation.
  92    *
  93    * @param key
  94    *        Name of a known crash annotation constant.
  95    *
  96    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
  97    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
  98    */
  99   void removeCrashReportAnnotation(in AUTF8String key);
 100
 101   /**
 102    * Checks if an annotation is allowlisted for inclusion in the crash ping.
 103    *
 104    * @param key
 105    *        Name of a known crash annotation constant.
 106    *
 107    * @return True if the specified value is a valid annotation and can be
 108              included in the crash ping, false otherwise.
 109    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
 110    */
 111   boolean isAnnotationAllowlistedForPing(in ACString value);
 112
 113   /**
 114    * Append some data to the "Notes" field, to be submitted with a crash report.
 115    * Unlike annotateCrashReport, this method will append to existing data.
 116    *
 117    * @param data
 118    *        Data to be added.
 119    *
 120    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
 121    * @throw NS_ERROR_INVALID_ARG if data contains invalid characters.
 122    *                             The only invalid character is '\0'.
 123    */
 124   void appendAppNotesToCrashReport(in ACString data);
 125
 126   /**
 127    * Register a given memory range to be included in the crash report.
 128    *
 129    * @param ptr
 130    *        The starting address for the bytes.
 131    * @param size
 132    *        The number of bytes to include.
 133    *
 134    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
 135    * @throw NS_ERROR_NOT_IMPLEMENTED if unavailable on the current OS
 136    */
 137   void registerAppMemory(in unsigned long long ptr, in unsigned long long size);
 138
 139   /**
 140    * Write a minidump immediately, with the user-supplied exception
 141    * information. This is implemented on Windows only, because
 142    * SEH (structured exception handling) exists on Windows only.
 143    *
 144    * @param aExceptionInfo  EXCEPTION_INFO* provided by Window's SEH
 145    */
 146   [noscript] void writeMinidumpForException(in voidPtr aExceptionInfo);
 147
 148   /**
 149    * Append note containing an Obj-C exception's info.
 150    *
 151    * @param aException  NSException object to append note for
 152    */
 153   [noscript] void appendObjCExceptionInfoToAppNotes(in voidPtr aException);
 154
 155   /**
 156    * User preference for submitting crash reports.
 157    */
 158   attribute boolean submitReports;
 159
 160   /**
 161    * Cause the crash reporter to re-evaluate where crash events should go.
 162    *
 163    * This should be called during application startup and whenever profiles
 164    * change.
 165    */
 166   void UpdateCrashEventsDir();
 167
 168   /**
 169    * Save an anonymized memory report file for inclusion in a future crash
 170    * report in this session.
 171    *
 172    * @throws NS_ERROR_NOT_INITIALIZED if crash reporting is disabled.
 173    */
 174   void saveMemoryReport();
 175 };