summaryrefslogtreecommitdiffstats
path: root/xpcom/system/nsICrashReporter.idl
blob: 6fd0967e752d56c194662f8aa5d573db85678f02 (plain)
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
/* 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 crashReporterEnabled;

  /**
   * 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 allowed 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 isAnnotationAllowedForPing(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();
};