/thirdparty/breakpad/client/mac/Framework/Breakpad.h

  1// Copyright (c) 2006, Google Inc.
  2// All rights reserved.
  3//
  4// Redistribution and use in source and binary forms, with or without
  5// modification, are permitted provided that the following conditions are
  6// met:
  7//
  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
 13// distribution.
 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.
 17//
 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.
 29//
 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
 33// object as follows:
 34//
 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
 38//    server
 39//
 40// By specifying parameters to the BreakpadCreate function, you can
 41// modify the default behavior to suit your needs and wants and
 42// desires.
 43
 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"
 47
 48typedef void *BreakpadRef;
 49
 50#ifdef __cplusplus
 51extern "C" {
 52#endif
 53
 54#include <CoreFoundation/CoreFoundation.h>
 55#include <Foundation/Foundation.h>
 56
 57#include "BreakpadDefines.h"
 58
 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)
 65typedef bool (*BreakpadFilterCallback)(int exception_type,
 66                                       int exception_code,
 67                                       mach_port_t crashing_thread,
 68                                       void *context);
 69
 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.
 73//
 74// You can also specify these additional keys for customizable behavior:
 75// Key:                           Value:
 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.
 80//                                REQUIRED
 81//
 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.
 87//
 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.
 91//                                REQUIRED
 92//
 93// BREAKPAD_VENDOR                Vendor name, used in UI (e.g. "A report has
 94//                                been created that you can send to <vendor>")
 95//
 96// BREAKPAD_URL                   URL destination for reporting
 97//                                REQUIRED
 98//
 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.
104//
105// BREAKPAD_SKIP_CONFIRM          If true, the reporter will send the report
106//                                without any user intervention.
107//                                Defaults to NO
108//
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.
114//
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.
118//                                Defaults TO YES
119//
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.
124//
125// BREAKPAD_INSPECTOR_LOCATION    The full path to the Inspector executable.
126//                                Defaults to <Framework resources>/Inspector
127//
128// BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender
129//                                executable.
130//                                Default:
131//                                <Framework Resources>/crash_report_sender.app
132//
133// BREAKPAD_LOGFILES              Indicates an array of log file paths that
134//                                should be uploaded at crash time.
135//
136// BREAKPAD_REQUEST_COMMENTS      If true, the message dialog will have a
137//                                text box for the user to enter comments.
138//                                Default: NO
139//
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.
143//                                Default: NO
144//
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'.
152//
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
160//                                server.
161//=============================================================================
162// The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are
163// required to have non-NULL values.  By default, the BREAKPAD_PRODUCT
164// will be the CFBundleName and the BREAKPAD_VERSION will be the
165// CFBundleVersion when these keys are present in the bundle's
166// Info.plist, which is usually passed in to BreakpadCreate() as an
167// NSDictionary (you could also pass in another dictionary that had
168// the same keys configured).  If the BREAKPAD_PRODUCT or
169// BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will
170// fail.  You have been warned.
171//
172// If you are running in a debugger, Breakpad will not install, unless the
173// BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero.
174//
175// The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default
176// values are NO and YES.  However, they can be controlled by setting their
177// values in a user or global plist.
178//
179// It's easiest to use Breakpad via the Framework, but if you're compiling the
180// code in directly, BREAKPAD_INSPECTOR_LOCATION and
181// BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths
182// to the helper executables.
183//
184//=============================================================================
185// The following are NOT user-supplied but are documented here for
186// completeness.  They are calculated by Breakpad during initialization &
187// crash-dump generation, or entered in by the user.
188//
189// BREAKPAD_PROCESS_START_TIME       The time, in seconds since the Epoch, the
190//                                   process started
191//
192// BREAKPAD_PROCESS_CRASH_TIME       The time, in seconds since the Epoch, the
193//                                   process crashed.
194//
195// BREAKPAD_PROCESS_UP_TIME          The total time in milliseconds the process
196//                                   has been running.  This parameter is not
197//                                   set until the crash-dump-generation phase.
198//
199// BREAKPAD_LOGFILE_KEY_PREFIX       Used to find out which parameters in the
200//                                   parameter dictionary correspond to log
201//                                   file paths.
202//
203// BREAKPAD_SERVER_PARAMETER_PREFIX  This prefix is used by Breakpad
204//                                   internally, because Breakpad uses
205//                                   the same dictionary internally to
206//                                   track both its internal
207//                                   configuration parameters and
208//                                   parameters meant to be uploaded
209//                                   to the server.  This string is
210//                                   used internally by Breakpad to
211//                                   prefix user-supplied parameter
212//                                   names so those can be sent to the
213//                                   server without leaking Breakpad's
214//                                   internal values.
215//
216// BREAKPAD_ON_DEMAND                Used internally to indicate to the
217//                                   Reporter that we're sending on-demand,
218//                                   not as result of a crash.
219//
220// BREAKPAD_COMMENTS                 The text the user provided as comments.
221//                                   Only used in crash_report_sender.
222
223// Returns a new BreakpadRef object on success, NULL otherwise.
224BreakpadRef BreakpadCreate(NSDictionary *parameters);
225
226// Uninstall and release the data associated with |ref|.
227void BreakpadRelease(BreakpadRef ref);
228
229// Clients may set an optional callback which gets called when a crash
230// occurs.  The callback function should return |true| if we should
231// handle the crash, generate a crash report, etc. or |false| if we
232// should ignore it and forward the crash (normally to CrashReporter).
233// Context is a pointer to arbitrary data to make the callback with.
234void BreakpadSetFilterCallback(BreakpadRef ref,
235                               BreakpadFilterCallback callback,
236                               void *context);
237
238// User defined key and value string storage.  Generally this is used
239// to configure Breakpad's internal operation, such as whether the
240// crash_sender should prompt the user, or the filesystem location for
241// the minidump file.  See Breakpad.h for some parameters that can be
242// set.  Anything longer than 255 bytes will be truncated. Note that
243// the string is converted to UTF8 before truncation, so any multibyte
244// character that straddles the 255(256 - 1 for terminator) byte limit
245// will be mangled.
246//
247// A maximum number of 64 key/value pairs are supported.  An assert()
248// will fire if more than this number are set.  Unfortunately, right
249// now, the same dictionary is used for both Breakpad's parameters AND
250// the Upload parameters.
251//
252// TODO (nealsid): Investigate how necessary this is if we don't
253// automatically upload parameters to the server anymore.
254// TODO (nealsid): separate server parameter dictionary from the
255// dictionary used to configure Breakpad, and document limits for each
256// independently.
257void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value);
258NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key);
259void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key);
260
261// You can use this method to specify parameters that will be uploaded
262// to the crash server.  They will be automatically encoded as
263// necessary.  Note that as mentioned above there are limits on both
264// the number of keys and their length.
265void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key,
266                                NSString *value);
267
268// This method will remove a previously-added parameter from the
269// upload parameter set.
270void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key);
271
272// Add a log file for Breakpad to read and send upon crash dump
273void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname);
274
275// Generate a minidump and send
276void BreakpadGenerateAndSendReport(BreakpadRef ref);
277
278#ifdef __cplusplus
279}
280#endif