1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,280 @@
1.4 +// Copyright (c) 2006, Google Inc.
1.5 +// All rights reserved.
1.6 +//
1.7 +// Redistribution and use in source and binary forms, with or without
1.8 +// modification, are permitted provided that the following conditions are
1.9 +// met:
1.10 +//
1.11 +// * Redistributions of source code must retain the above copyright
1.12 +// notice, this list of conditions and the following disclaimer.
1.13 +// * Redistributions in binary form must reproduce the above
1.14 +// copyright notice, this list of conditions and the following disclaimer
1.15 +// in the documentation and/or other materials provided with the
1.16 +// distribution.
1.17 +// * Neither the name of Google Inc. nor the names of its
1.18 +// contributors may be used to endorse or promote products derived from
1.19 +// this software without specific prior written permission.
1.20 +//
1.21 +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.22 +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.23 +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.24 +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
1.25 +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.26 +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.27 +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
1.28 +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1.29 +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1.30 +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1.31 +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.32 +//
1.33 +// Framework to provide a simple C API to crash reporting for
1.34 +// applications. By default, if any machine-level exception (e.g.,
1.35 +// EXC_BAD_ACCESS) occurs, it will be handled by the BreakpadRef
1.36 +// object as follows:
1.37 +//
1.38 +// 1. Create a minidump file (see Breakpad for details)
1.39 +// 2. Prompt the user (using CFUserNotification)
1.40 +// 3. Invoke a command line reporting tool to send the minidump to a
1.41 +// server
1.42 +//
1.43 +// By specifying parameters to the BreakpadCreate function, you can
1.44 +// modify the default behavior to suit your needs and wants and
1.45 +// desires.
1.46 +
1.47 +// A service name associated with the original bootstrap parent port, saved in
1.48 +// OnDemandServer and restored in Inspector.
1.49 +#define BREAKPAD_BOOTSTRAP_PARENT_PORT "com.Breakpad.BootstrapParent"
1.50 +
1.51 +typedef void *BreakpadRef;
1.52 +
1.53 +#ifdef __cplusplus
1.54 +extern "C" {
1.55 +#endif
1.56 +
1.57 +#include <CoreFoundation/CoreFoundation.h>
1.58 +#include <Foundation/Foundation.h>
1.59 +
1.60 +#include "BreakpadDefines.h"
1.61 +
1.62 +// Optional user-defined function to dec to decide if we should handle
1.63 +// this crash or forward it along.
1.64 +// Return true if you want Breakpad to handle it.
1.65 +// Return false if you want Breakpad to skip it
1.66 +// The exception handler always returns false, as if SEND_AND_EXIT were false
1.67 +// (which means the next exception handler will take the exception)
1.68 +typedef bool (*BreakpadFilterCallback)(int exception_type,
1.69 + int exception_code,
1.70 + mach_port_t crashing_thread,
1.71 + void *context);
1.72 +
1.73 +// Create a new BreakpadRef object and install it as an exception
1.74 +// handler. The |parameters| will typically be the contents of your
1.75 +// bundle's Info.plist.
1.76 +//
1.77 +// You can also specify these additional keys for customizable behavior:
1.78 +// Key: Value:
1.79 +// BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct")
1.80 +// This one is used as the key to identify
1.81 +// the product when uploading. Falls back to
1.82 +// CFBundleName if not specified.
1.83 +// REQUIRED
1.84 +//
1.85 +// BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty
1.86 +// name for the product when the crash_sender
1.87 +// pops up UI for the user. Falls back first to
1.88 +// CFBundleDisplayName and then to
1.89 +// BREAKPAD_PRODUCT if not specified.
1.90 +//
1.91 +// BREAKPAD_VERSION Product version (e.g., 1.2.3), used
1.92 +// as metadata for crash report. Falls back to
1.93 +// CFBundleVersion if not specified.
1.94 +// REQUIRED
1.95 +//
1.96 +// BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has
1.97 +// been created that you can send to <vendor>")
1.98 +//
1.99 +// BREAKPAD_URL URL destination for reporting
1.100 +// REQUIRED
1.101 +//
1.102 +// BREAKPAD_REPORT_INTERVAL # of seconds between sending
1.103 +// reports. If an additional report is
1.104 +// generated within this time, it will
1.105 +// be ignored. Default: 3600sec.
1.106 +// Specify 0 to send all reports.
1.107 +//
1.108 +// BREAKPAD_SKIP_CONFIRM If true, the reporter will send the report
1.109 +// without any user intervention.
1.110 +// Defaults to NO
1.111 +//
1.112 +// BREAKPAD_CONFIRM_TIMEOUT Number of seconds before the upload
1.113 +// confirmation dialog will be automatically
1.114 +// dismissed (cancelling the upload).
1.115 +// Default: 300 seconds (min of 60).
1.116 +// Specify 0 to prevent timeout.
1.117 +//
1.118 +// BREAKPAD_SEND_AND_EXIT If true, the handler will exit after sending.
1.119 +// This will prevent any other handler (e.g.,
1.120 +// CrashReporter) from getting the crash.
1.121 +// Defaults TO YES
1.122 +//
1.123 +// BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps
1.124 +// in. By default, we use
1.125 +// ~/Library/Breakpad/<BREAKPAD_PRODUCT>
1.126 +// The path you specify here is tilde-expanded.
1.127 +//
1.128 +// BREAKPAD_INSPECTOR_LOCATION The full path to the Inspector executable.
1.129 +// Defaults to <Framework resources>/Inspector
1.130 +//
1.131 +// BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender
1.132 +// executable.
1.133 +// Default:
1.134 +// <Framework Resources>/crash_report_sender.app
1.135 +//
1.136 +// BREAKPAD_LOGFILES Indicates an array of log file paths that
1.137 +// should be uploaded at crash time.
1.138 +//
1.139 +// BREAKPAD_REQUEST_COMMENTS If true, the message dialog will have a
1.140 +// text box for the user to enter comments.
1.141 +// Default: NO
1.142 +//
1.143 +// BREAKPAD_REQUEST_EMAIL If true and BREAKPAD_REQUEST_COMMENTS is also
1.144 +// true, the message dialog will have a text
1.145 +// box for the user to enter their email address.
1.146 +// Default: NO
1.147 +//
1.148 +// BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to
1.149 +// rewrite the upload parameters for a specific
1.150 +// server type. The currently valid values are
1.151 +// 'socorro' or 'google'. If you want to add
1.152 +// other types, see the function in
1.153 +// crash_report_sender.m that maps parameters to
1.154 +// URL parameters. Defaults to 'google'.
1.155 +//
1.156 +// BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static
1.157 +// parameters that are uploaded to the
1.158 +// server. The parameters are sent as
1.159 +// is to the crash server. Their
1.160 +// content isn't added to the minidump
1.161 +// but pass as URL parameters when
1.162 +// uploading theminidump to the crash
1.163 +// server.
1.164 +//=============================================================================
1.165 +// The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are
1.166 +// required to have non-NULL values. By default, the BREAKPAD_PRODUCT
1.167 +// will be the CFBundleName and the BREAKPAD_VERSION will be the
1.168 +// CFBundleVersion when these keys are present in the bundle's
1.169 +// Info.plist, which is usually passed in to BreakpadCreate() as an
1.170 +// NSDictionary (you could also pass in another dictionary that had
1.171 +// the same keys configured). If the BREAKPAD_PRODUCT or
1.172 +// BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will
1.173 +// fail. You have been warned.
1.174 +//
1.175 +// If you are running in a debugger, Breakpad will not install, unless the
1.176 +// BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero.
1.177 +//
1.178 +// The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default
1.179 +// values are NO and YES. However, they can be controlled by setting their
1.180 +// values in a user or global plist.
1.181 +//
1.182 +// It's easiest to use Breakpad via the Framework, but if you're compiling the
1.183 +// code in directly, BREAKPAD_INSPECTOR_LOCATION and
1.184 +// BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths
1.185 +// to the helper executables.
1.186 +//
1.187 +//=============================================================================
1.188 +// The following are NOT user-supplied but are documented here for
1.189 +// completeness. They are calculated by Breakpad during initialization &
1.190 +// crash-dump generation, or entered in by the user.
1.191 +//
1.192 +// BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the
1.193 +// process started
1.194 +//
1.195 +// BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the
1.196 +// process crashed.
1.197 +//
1.198 +// BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process
1.199 +// has been running. This parameter is not
1.200 +// set until the crash-dump-generation phase.
1.201 +//
1.202 +// BREAKPAD_LOGFILE_KEY_PREFIX Used to find out which parameters in the
1.203 +// parameter dictionary correspond to log
1.204 +// file paths.
1.205 +//
1.206 +// BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad
1.207 +// internally, because Breakpad uses
1.208 +// the same dictionary internally to
1.209 +// track both its internal
1.210 +// configuration parameters and
1.211 +// parameters meant to be uploaded
1.212 +// to the server. This string is
1.213 +// used internally by Breakpad to
1.214 +// prefix user-supplied parameter
1.215 +// names so those can be sent to the
1.216 +// server without leaking Breakpad's
1.217 +// internal values.
1.218 +//
1.219 +// BREAKPAD_ON_DEMAND Used internally to indicate to the
1.220 +// Reporter that we're sending on-demand,
1.221 +// not as result of a crash.
1.222 +//
1.223 +// BREAKPAD_COMMENTS The text the user provided as comments.
1.224 +// Only used in crash_report_sender.
1.225 +
1.226 +// Returns a new BreakpadRef object on success, NULL otherwise.
1.227 +BreakpadRef BreakpadCreate(NSDictionary *parameters);
1.228 +
1.229 +// Uninstall and release the data associated with |ref|.
1.230 +void BreakpadRelease(BreakpadRef ref);
1.231 +
1.232 +// Clients may set an optional callback which gets called when a crash
1.233 +// occurs. The callback function should return |true| if we should
1.234 +// handle the crash, generate a crash report, etc. or |false| if we
1.235 +// should ignore it and forward the crash (normally to CrashReporter).
1.236 +// Context is a pointer to arbitrary data to make the callback with.
1.237 +void BreakpadSetFilterCallback(BreakpadRef ref,
1.238 + BreakpadFilterCallback callback,
1.239 + void *context);
1.240 +
1.241 +// User defined key and value string storage. Generally this is used
1.242 +// to configure Breakpad's internal operation, such as whether the
1.243 +// crash_sender should prompt the user, or the filesystem location for
1.244 +// the minidump file. See Breakpad.h for some parameters that can be
1.245 +// set. Anything longer than 255 bytes will be truncated. Note that
1.246 +// the string is converted to UTF8 before truncation, so any multibyte
1.247 +// character that straddles the 255(256 - 1 for terminator) byte limit
1.248 +// will be mangled.
1.249 +//
1.250 +// A maximum number of 64 key/value pairs are supported. An assert()
1.251 +// will fire if more than this number are set. Unfortunately, right
1.252 +// now, the same dictionary is used for both Breakpad's parameters AND
1.253 +// the Upload parameters.
1.254 +//
1.255 +// TODO (nealsid): Investigate how necessary this is if we don't
1.256 +// automatically upload parameters to the server anymore.
1.257 +// TODO (nealsid): separate server parameter dictionary from the
1.258 +// dictionary used to configure Breakpad, and document limits for each
1.259 +// independently.
1.260 +void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value);
1.261 +NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key);
1.262 +void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key);
1.263 +
1.264 +// You can use this method to specify parameters that will be uploaded
1.265 +// to the crash server. They will be automatically encoded as
1.266 +// necessary. Note that as mentioned above there are limits on both
1.267 +// the number of keys and their length.
1.268 +void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key,
1.269 + NSString *value);
1.270 +
1.271 +// This method will remove a previously-added parameter from the
1.272 +// upload parameter set.
1.273 +void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key);
1.274 +
1.275 +// Add a log file for Breakpad to read and send upon crash dump
1.276 +void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname);
1.277 +
1.278 +// Generate a minidump and send
1.279 +void BreakpadGenerateAndSendReport(BreakpadRef ref);
1.280 +
1.281 +#ifdef __cplusplus
1.282 +}
1.283 +#endif
