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 48 typedef void *BreakpadRef; 49 50 #ifdef __cplusplus 51 extern "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) 65 typedef 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 // 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 165 // process. 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. 176 // 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. 179 // 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. 183 // 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. 188 // 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. 193 // 194 // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the 195 // process started 196 // 197 // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the 198 // process crashed. 199 // 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. 203 // 204 // BREAKPAD_LOGFILE_KEY_PREFIX Used to find out which parameters in the 205 // parameter dictionary correspond to log 206 // file paths. 207 // 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 219 // internal values. 220 // 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. 224 // 225 // BREAKPAD_COMMENTS The text the user provided as comments. 226 // Only used in crash_report_sender. 227 228 // Returns a new BreakpadRef object on success, NULL otherwise. 229 BreakpadRef BreakpadCreate(NSDictionary *parameters); 230 231 // Uninstall and release the data associated with |ref|. 232 void BreakpadRelease(BreakpadRef ref); 233 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, 241 void *context); 242 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 250 // will be mangled. 251 // 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. 256 // 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 261 // independently. 262 void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value); 263 NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key); 264 void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key); 265 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, 271 NSString *value); 272 273 // This method will remove a previously-added parameter from the 274 // upload parameter set. 275 void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key); 276 277 // Add a log file for Breakpad to read and send upon crash dump 278 void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname); 279 280 // Generate a minidump and send 281 void BreakpadGenerateAndSendReport(BreakpadRef ref); 282 283 #ifdef __cplusplus 284 } 285 #endif 286