1 // Copyright (c) 2006, Google Inc.
2 // All rights reserved.
4 // Redistribution and use in source and binary forms, with or without
5 // modification, are permitted provided that the following conditions are
8 // * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 // * Redistributions in binary form must reproduce the above
11 // copyright notice, this list of conditions and the following disclaimer
12 // in the documentation and/or other materials provided with the
14 // * Neither the name of Google Inc. nor the names of its
15 // contributors may be used to endorse or promote products derived from
16 // this software without specific prior written permission.
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 // Framework to provide a simple C API to crash reporting for
31 // applications. By default, if any machine-level exception (e.g.,
32 // EXC_BAD_ACCESS) occurs, it will be handled by the BreakpadRef
35 // 1. Create a minidump file (see Breakpad for details)
36 // 2. Prompt the user (using CFUserNotification)
37 // 3. Invoke a command line reporting tool to send the minidump to a
40 // By specifying parameters to the BreakpadCreate function, you can
41 // modify the default behavior to suit your needs and wants and
44 // A service name associated with the original bootstrap parent port, saved in
45 // OnDemandServer and restored in Inspector.
46 #define BREAKPAD_BOOTSTRAP_PARENT_PORT "com.Breakpad.BootstrapParent"
48 typedef void *BreakpadRef;
54 #include <CoreFoundation/CoreFoundation.h>
55 #include <Foundation/Foundation.h>
57 #include "BreakpadDefines.h"
59 // Optional user-defined function to dec to decide if we should handle
60 // this crash or forward it along.
61 // Return true if you want Breakpad to handle it.
62 // Return false if you want Breakpad to skip it
63 // The exception handler always returns false, as if SEND_AND_EXIT were false
64 // (which means the next exception handler will take the exception)
65 typedef bool (*BreakpadFilterCallback)(int exception_type,
67 mach_port_t crashing_thread,
70 // Create a new BreakpadRef object and install it as an exception
71 // handler. The |parameters| will typically be the contents of your
72 // bundle's Info.plist.
74 // You can also specify these additional keys for customizable behavior:
76 // BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct")
77 // This one is used as the key to identify
78 // the product when uploading. Falls back to
79 // CFBundleName if not specified.
82 // BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty
83 // name for the product when the crash_sender
84 // pops up UI for the user. Falls back first to
85 // CFBundleDisplayName and then to
86 // BREAKPAD_PRODUCT if not specified.
88 // BREAKPAD_VERSION Product version (e.g., 1.2.3), used
89 // as metadata for crash report. Falls back to
90 // CFBundleVersion if not specified.
93 // BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has
94 // been created that you can send to <vendor>")
96 // BREAKPAD_URL URL destination for reporting
99 // BREAKPAD_REPORT_INTERVAL # of seconds between sending
100 // reports. If an additional report is
101 // generated within this time, it will
102 // be ignored. Default: 3600sec.
103 // Specify 0 to send all reports.
105 // BREAKPAD_SKIP_CONFIRM If true, the reporter will send the report
106 // without any user intervention.
109 // BREAKPAD_CONFIRM_TIMEOUT Number of seconds before the upload
110 // confirmation dialog will be automatically
111 // dismissed (cancelling the upload).
112 // Default: 300 seconds (min of 60).
113 // Specify 0 to prevent timeout.
115 // BREAKPAD_SEND_AND_EXIT If true, the handler will exit after sending.
116 // This will prevent any other handler (e.g.,
117 // CrashReporter) from getting the crash.
120 // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps
121 // in. By default, we use
122 // ~/Library/Breakpad/<BREAKPAD_PRODUCT>
123 // The path you specify here is tilde-expanded.
125 // BREAKPAD_INSPECTOR_LOCATION The full path to the Inspector executable.
126 // Defaults to <Framework resources>/Inspector
128 // BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender
131 // <Framework Resources>/crash_report_sender.app
133 // BREAKPAD_LOGFILES Indicates an array of log file paths that
134 // should be uploaded at crash time.
136 // BREAKPAD_REQUEST_COMMENTS If true, the message dialog will have a
137 // text box for the user to enter comments.
140 // BREAKPAD_REQUEST_EMAIL If true and BREAKPAD_REQUEST_COMMENTS is also
141 // true, the message dialog will have a text
142 // box for the user to enter their email address.
145 // BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to
146 // rewrite the upload parameters for a specific
147 // server type. The currently valid values are
148 // 'socorro' or 'google'. If you want to add
149 // other types, see the function in
150 // crash_report_sender.m that maps parameters to
151 // URL parameters. Defaults to 'google'.
153 // BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static
154 // parameters that are uploaded to the
155 // server. The parameters are sent as
156 // is to the crash server. Their
157 // content isn't added to the minidump
158 // but pass as URL parameters when
159 // uploading theminidump to the crash
162 // BREAKPAD_IN_PROCESS A boolean NSNumber value. If YES, Breakpad
163 // will write the dump file in-process and then
164 // launch the reporter executable as a child
166 //=============================================================================
167 // The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are
168 // required to have non-NULL values. By default, the BREAKPAD_PRODUCT
169 // will be the CFBundleName and the BREAKPAD_VERSION will be the
170 // CFBundleVersion when these keys are present in the bundle's
171 // Info.plist, which is usually passed in to BreakpadCreate() as an
172 // NSDictionary (you could also pass in another dictionary that had
173 // the same keys configured). If the BREAKPAD_PRODUCT or
174 // BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will
175 // fail. You have been warned.
177 // If you are running in a debugger, Breakpad will not install, unless the
178 // BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero.
180 // The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default
181 // values are NO and YES. However, they can be controlled by setting their
182 // values in a user or global plist.
184 // It's easiest to use Breakpad via the Framework, but if you're compiling the
185 // code in directly, BREAKPAD_INSPECTOR_LOCATION and
186 // BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths
187 // to the helper executables.
189 //=============================================================================
190 // The following are NOT user-supplied but are documented here for
191 // completeness. They are calculated by Breakpad during initialization &
192 // crash-dump generation, or entered in by the user.
194 // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the
197 // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the
200 // BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process
201 // has been running. This parameter is not
202 // set until the crash-dump-generation phase.
204 // BREAKPAD_LOGFILE_KEY_PREFIX Used to find out which parameters in the
205 // parameter dictionary correspond to log
208 // BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad
209 // internally, because Breakpad uses
210 // the same dictionary internally to
211 // track both its internal
212 // configuration parameters and
213 // parameters meant to be uploaded
214 // to the server. This string is
215 // used internally by Breakpad to
216 // prefix user-supplied parameter
217 // names so those can be sent to the
218 // server without leaking Breakpad's
221 // BREAKPAD_ON_DEMAND Used internally to indicate to the
222 // Reporter that we're sending on-demand,
223 // not as result of a crash.
225 // BREAKPAD_COMMENTS The text the user provided as comments.
226 // Only used in crash_report_sender.
228 // Returns a new BreakpadRef object on success, NULL otherwise.
229 BreakpadRef BreakpadCreate(NSDictionary *parameters);
231 // Uninstall and release the data associated with |ref|.
232 void BreakpadRelease(BreakpadRef ref);
234 // Clients may set an optional callback which gets called when a crash
235 // occurs. The callback function should return |true| if we should
236 // handle the crash, generate a crash report, etc. or |false| if we
237 // should ignore it and forward the crash (normally to CrashReporter).
238 // Context is a pointer to arbitrary data to make the callback with.
239 void BreakpadSetFilterCallback(BreakpadRef ref,
240 BreakpadFilterCallback callback,
243 // User defined key and value string storage. Generally this is used
244 // to configure Breakpad's internal operation, such as whether the
245 // crash_sender should prompt the user, or the filesystem location for
246 // the minidump file. See Breakpad.h for some parameters that can be
247 // set. Anything longer than 255 bytes will be truncated. Note that
248 // the string is converted to UTF8 before truncation, so any multibyte
249 // character that straddles the 255(256 - 1 for terminator) byte limit
252 // A maximum number of 64 key/value pairs are supported. An assert()
253 // will fire if more than this number are set. Unfortunately, right
254 // now, the same dictionary is used for both Breakpad's parameters AND
255 // the Upload parameters.
257 // TODO (nealsid): Investigate how necessary this is if we don't
258 // automatically upload parameters to the server anymore.
259 // TODO (nealsid): separate server parameter dictionary from the
260 // dictionary used to configure Breakpad, and document limits for each
262 void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value);
263 NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key);
264 void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key);
266 // You can use this method to specify parameters that will be uploaded
267 // to the crash server. They will be automatically encoded as
268 // necessary. Note that as mentioned above there are limits on both
269 // the number of keys and their length.
270 void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key,
273 // This method will remove a previously-added parameter from the
274 // upload parameter set.
275 void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key);
277 // Add a log file for Breakpad to read and send upon crash dump
278 void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname);
280 // Generate a minidump and send
281 void BreakpadGenerateAndSendReport(BreakpadRef ref);