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 boolean 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. This can be a string, a 32-bit integer or a
  82    *        boolean. The type must match the type of the annotation as
  83    *        specified in CrashAnnotations.yaml.
  84    *
  85    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
  86    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value, data is a
  87    *                             string and contains invalid characters, or
  88    *                             data does not match the annotation type
  89    * @throw NS_ERROR_OUT_OF_MEMORY if there was insufficient memory to
  90    *                               convert a JavaScript string to UTF-8
  91    */
  92   [implicit_jscontext]
  93   void annotateCrashReport(in AUTF8String key, in jsval data);
  94
  95   /**
  96    * Remove a crash report annotation.
  97    *
  98    * @param key
  99    *        Name of a known crash annotation constant.
 100    *
 101    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
 102    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
 103    */
 104   void removeCrashReportAnnotation(in AUTF8String key);
 105
 106   /**
 107    * Checks if an annotation is allowed for inclusion in the crash ping.
 108    *
 109    * @param key
 110    *        Name of a known crash annotation constant.
 111    *
 112    * @return True if the specified value is a valid annotation and can be
 113              included in the crash ping, false otherwise.
 114    * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
 115    */
 116   boolean isAnnotationAllowedForPing(in ACString value);
 117
 118   /**
 119    * Append some data to the "Notes" field, to be submitted with a crash report.
 120    * Unlike annotateCrashReport, this method will append to existing data.
 121    *
 122    * @param data
 123    *        Data to be added.
 124    *
 125    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
 126    * @throw NS_ERROR_INVALID_ARG if data contains invalid characters.
 127    *                             The only invalid character is '\0'.
 128    */
 129   void appendAppNotesToCrashReport(in ACString data);
 130
 131   /**
 132    * Register a given memory range to be included in the crash report.
 133    *
 134    * @param ptr
 135    *        The starting address for the bytes.
 136    * @param size
 137    *        The number of bytes to include.
 138    *
 139    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
 140    * @throw NS_ERROR_NOT_IMPLEMENTED if unavailable on the current OS
 141    */
 142   void registerAppMemory(in unsigned long long ptr, in unsigned long long size);
 143
 144   /**
 145    * Write a minidump immediately, with the user-supplied exception
 146    * information. This is implemented on Windows only, because
 147    * SEH (structured exception handling) exists on Windows only.
 148    *
 149    * @param aExceptionInfo  EXCEPTION_INFO* provided by Window's SEH
 150    */
 151   [noscript] void writeMinidumpForException(in voidPtr aExceptionInfo);
 152
 153   /**
 154    * Append note containing an Obj-C exception's info.
 155    *
 156    * @param aException  NSException object to append note for
 157    */
 158   [noscript] void appendObjCExceptionInfoToAppNotes(in voidPtr aException);
 159
 160   /**
 161    * User preference for submitting crash reports.
 162    */
 163   attribute boolean submitReports;
 164
 165   /**
 166    * Cause the crash reporter to re-evaluate where crash events should go.
 167    *
 168    * This should be called during application startup and whenever profiles
 169    * change.
 170    */
 171   void UpdateCrashEventsDir();
 172
 173   /**
 174    * Save an anonymized memory report file for inclusion in a future crash
 175    * report in this session.
 176    *
 177    * @throws NS_ERROR_NOT_INITIALIZED if crash reporting is disabled.
 178    */
 179   void saveMemoryReport();
 180 };