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