DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (47d7c18620c8)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIFile;
interface nsIURL;

/**
 * Provides access to crash reporting functionality.
 *
 * @status UNSTABLE - This interface is not frozen and will probably change in
 *                    future releases.
 */

[scriptable, uuid(4b74c39a-cf69-4a8a-8e63-169d81ad1ecf)]
interface nsICrashReporter : nsISupports
{
  /**
   * Get the enabled status of the crash reporter.
   */
  readonly attribute boolean enabled;

  /**
   * Enable or disable crash reporting at runtime. Not available to script
   * because the JS engine relies on proper exception handler chaining.
   */
  [noscript]
  void setEnabled(in bool enabled);

  /**
   * Get or set the URL to which crash reports will be submitted.
   * Only https and http URLs are allowed, as the submission is handled
   * by OS-native networking libraries.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
   * @throw NS_ERROR_INVALID_ARG on set if a non-http(s) URL is assigned
   * @throw NS_ERROR_FAILURE on get if no URL is set
   */
  attribute nsIURL serverURL;

  /**
   * Get or set the path on the local system to which minidumps will be
   * written when a crash happens.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
   */
  attribute nsIFile minidumpPath;

  /**
   * Get the minidump file corresponding to the specified ID.
   *
   * @param id
   *        ID of the crash. Likely a UUID.
   *
   * @return The minidump file associated with the ID.
   *
   * @throw NS_ERROR_FILE_NOT_FOUND if the minidump could not be found
   */
  nsIFile getMinidumpForID(in AString id);

  /**
   * Get the extra file corresponding to the specified ID.
   *
   * @param id
   *        ID of the crash. Likely a UUID.
   *
   * @return The extra file associated with the ID.
   *
   * @throw NS_ERROR_FILE_NOT_FOUND if the extra file could not be found
   */
  nsIFile getExtraFileForID(in AString id);

  /**
   * Add some extra data to be submitted with a crash report.
   *
   * @param key
   *        Name of a known crash annotation constant.
   * @param data
   *        Data to be added.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
   * @throw NS_ERROR_INVALID_ARG if key contains an invalid value or data
   *                             contains invalid characters.  Invalid
   *                             character for data is '\0'.
   */
  void annotateCrashReport(in AUTF8String key, in AUTF8String data);

  /**
   * Remove a crash report annotation.
   *
   * @param key
   *        Name of a known crash annotation constant.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
   * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
   */
  void removeCrashReportAnnotation(in AUTF8String key);

  /**
   * Checks if an annotation is whitelisted for inclusion in the crash ping.
   *
   * @param key
   *        Name of a known crash annotation constant.
   *
   * @return True if the specified value is a valid annotation and can be
             included in the crash ping, false otherwise.
   * @throw NS_ERROR_INVALID_ARG if key contains an invalid value.
   */
  boolean isAnnotationWhitelistedForPing(in ACString value);

  /**
   * Append some data to the "Notes" field, to be submitted with a crash report.
   * Unlike annotateCrashReport, this method will append to existing data.
   *
   * @param data
   *        Data to be added.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
   * @throw NS_ERROR_INVALID_ARG if data contains invalid characters.
   *                             The only invalid character is '\0'.
   */
  void appendAppNotesToCrashReport(in ACString data);

  /**
   * Register a given memory range to be included in the crash report.
   *
   * @param ptr
   *        The starting address for the bytes.
   * @param size
   *        The number of bytes to include.
   *
   * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
   * @throw NS_ERROR_NOT_IMPLEMENTED if unavailable on the current OS
   */
  void registerAppMemory(in unsigned long long ptr, in unsigned long long size);

  /**
   * Write a minidump immediately, with the user-supplied exception
   * information. This is implemented on Windows only, because
   * SEH (structured exception handling) exists on Windows only.
   *
   * @param aExceptionInfo  EXCEPTION_INFO* provided by Window's SEH
   */
  [noscript] void writeMinidumpForException(in voidPtr aExceptionInfo);

  /**
   * Append note containing an Obj-C exception's info.
   *
   * @param aException  NSException object to append note for
   */
  [noscript] void appendObjCExceptionInfoToAppNotes(in voidPtr aException);

  /**
   * User preference for submitting crash reports.
   */
  attribute boolean submitReports;

  /**
   * Cause the crash reporter to re-evaluate where crash events should go.
   *
   * This should be called during application startup and whenever profiles
   * change.
   */
  void UpdateCrashEventsDir();

  /**
   * Save an anonymized memory report file for inclusion in a future crash
   * report in this session.
   *
   * @throws NS_ERROR_NOT_INITIALIZED if crash reporting is disabled.
   */
  void saveMemoryReport();

  /**
   * Set the telemetry session ID which is recorded in crash metadata. This is
   * saved in the crash manager and telemetry but is not submitted as a
   * crash-stats annotation.
   */
  void setTelemetrySessionId(in AUTF8String id);
};