1 // Copyright (c) 2011, 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. Create a config file. 37 // 38 // These files can then be uploaded to a server. 39 40 typedef void *BreakpadRef; 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 #include <Foundation/Foundation.h> 47 48 #include <client/apple/Framework/BreakpadDefines.h> 49 50 // The keys in the dictionary returned by |BreakpadGenerateReport|. 51 #define BREAKPAD_OUTPUT_DUMP_FILE "BreakpadDumpFile" 52 #define BREAKPAD_OUTPUT_CONFIG_FILE "BreakpadConfigFile" 53 54 // Optional user-defined function to decide if we should handle this crash or 55 // forward it along. 56 // Return true if you want Breakpad to handle it. 57 // Return false if you want Breakpad to skip it 58 // The exception handler always returns false, as if SEND_AND_EXIT were false 59 // (which means the next exception handler will take the exception) 60 typedef bool (*BreakpadFilterCallback)(int exception_type, 61 int exception_code, 62 mach_port_t crashing_thread, 63 void *context); 64 65 // Optional user-defined function that will be called after a network upload 66 // of a crash report. 67 // |report_id| will be the id returned by the server, or "ERR" if an error 68 // occurred. 69 // |error| will contain the error, or nil if no error occured. 70 typedef void (*BreakpadUploadCompletionCallback)(NSString *report_id, 71 NSError *error); 72 73 // Create a new BreakpadRef object and install it as an exception 74 // handler. The |parameters| will typically be the contents of your 75 // bundle's Info.plist. 76 // 77 // You can also specify these additional keys for customizable behavior: 78 // Key: Value: 79 // BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct") 80 // This one is used as the key to identify 81 // the product when uploading. Falls back to 82 // CFBundleName if not specified. 83 // REQUIRED 84 // 85 // BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty 86 // name for the product when the crash_sender 87 // pops up UI for the user. Falls back first to 88 // CFBundleDisplayName and then to 89 // BREAKPAD_PRODUCT if not specified. 90 // 91 // BREAKPAD_VERSION Product version (e.g., 1.2.3), used 92 // as metadata for crash report. Falls back to 93 // CFBundleVersion if not specified. 94 // REQUIRED 95 // 96 // BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has 97 // been created that you can send to <vendor>") 98 // 99 // BREAKPAD_URL URL destination for reporting 100 // REQUIRED 101 // 102 // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps 103 // in. By default, we use 104 // ~/Library/Cache/Breakpad/<BREAKPAD_PRODUCT> 105 // The path you specify here is tilde-expanded. 106 // 107 // BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to 108 // rewrite the upload parameters for a specific 109 // server type. The currently valid values are 110 // 'socorro' or 'google'. If you want to add 111 // other types, see the function in 112 // crash_report_sender.m that maps parameters to 113 // URL parameters. Defaults to 'google'. 114 // 115 // BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static 116 // parameters that are uploaded to the 117 // server. The parameters are sent as 118 // is to the crash server. Their 119 // content isn't added to the minidump 120 // but pass as URL parameters when 121 // uploading theminidump to the crash 122 // server. 123 //============================================================================= 124 // The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are 125 // required to have non-NULL values. By default, the BREAKPAD_PRODUCT 126 // will be the CFBundleName and the BREAKPAD_VERSION will be the 127 // CFBundleVersion when these keys are present in the bundle's 128 // Info.plist, which is usually passed in to BreakpadCreate() as an 129 // NSDictionary (you could also pass in another dictionary that had 130 // the same keys configured). If the BREAKPAD_PRODUCT or 131 // BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will 132 // fail. You have been warned. 133 // 134 // If you are running in a debugger, Breakpad will not install, unless the 135 // BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero. 136 // 137 //============================================================================= 138 // The following are NOT user-supplied but are documented here for 139 // completeness. They are calculated by Breakpad during initialization & 140 // crash-dump generation, or entered in by the user. 141 // 142 // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the 143 // process started 144 // 145 // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the 146 // process crashed. 147 // 148 // BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process 149 // has been running. This parameter is not 150 // set until the crash-dump-generation phase. 151 // 152 // BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad 153 // internally, because Breakpad uses 154 // the same dictionary internally to 155 // track both its internal 156 // configuration parameters and 157 // parameters meant to be uploaded 158 // to the server. This string is 159 // used internally by Breakpad to 160 // prefix user-supplied parameter 161 // names so those can be sent to the 162 // server without leaking Breakpad's 163 // internal values. 164 165 // Returns a new BreakpadRef object on success, NULL otherwise. 166 BreakpadRef BreakpadCreate(NSDictionary *parameters); 167 168 // Uninstall and release the data associated with |ref|. 169 void BreakpadRelease(BreakpadRef ref); 170 171 // User defined key and value string storage. Generally this is used 172 // to configure Breakpad's internal operation, such as whether the 173 // crash_sender should prompt the user, or the filesystem location for 174 // the minidump file. See Breakpad.h for some parameters that can be 175 // set. Anything longer than 255 bytes will be truncated. Note that 176 // the string is converted to UTF8 before truncation, so any multibyte 177 // character that straddles the 255(256 - 1 for terminator) byte limit 178 // will be mangled. 179 // 180 // A maximum number of 64 key/value pairs are supported. An assert() 181 // will fire if more than this number are set. Unfortunately, right 182 // now, the same dictionary is used for both Breakpad's parameters AND 183 // the Upload parameters. 184 // 185 // TODO (nealsid): Investigate how necessary this is if we don't 186 // automatically upload parameters to the server anymore. 187 // TODO (nealsid): separate server parameter dictionary from the 188 // dictionary used to configure Breakpad, and document limits for each 189 // independently. 190 void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value); 191 NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key); 192 void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key); 193 194 // You can use this method to specify parameters that will be uploaded 195 // to the crash server. They will be automatically encoded as 196 // necessary. Note that as mentioned above there are limits on both 197 // the number of keys and their length. 198 void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key, 199 NSString *value); 200 201 // This method will remove a previously-added parameter from the 202 // upload parameter set. 203 void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key); 204 205 // Method to handle uploading data to the server 206 207 // Returns the number of crash reports waiting to send to the server. 208 int BreakpadGetCrashReportCount(BreakpadRef ref); 209 210 // Returns the next upload configuration. The report file is deleted. 211 NSDictionary *BreakpadGetNextReportConfiguration(BreakpadRef ref); 212 213 // Returns the date of the most recent crash report. 214 NSDate *BreakpadGetDateOfMostRecentCrashReport(BreakpadRef ref); 215 216 // Upload next report to the server. 217 void BreakpadUploadNextReport(BreakpadRef ref); 218 219 // Upload next report to the server. 220 // |server_parameters| is additional server parameters to send. 221 void BreakpadUploadNextReportWithParameters( 222 BreakpadRef ref, 223 NSDictionary *server_parameters, 224 BreakpadUploadCompletionCallback callback); 225 226 // Upload a report to the server. 227 // |server_parameters| is additional server parameters to send. 228 // |configuration| is the configuration of the breakpad report to send. 229 void BreakpadUploadReportWithParametersAndConfiguration( 230 BreakpadRef ref, 231 NSDictionary *server_parameters, 232 NSDictionary *configuration, 233 BreakpadUploadCompletionCallback callback); 234 235 // Handles the network response of a breakpad upload. This function is needed if 236 // the actual upload is done by the Breakpad client. 237 // |configuration| is the configuration of the upload. It must contain the same 238 // fields as the configuration passed to 239 // BreakpadUploadReportWithParametersAndConfiguration. 240 // |data| and |error| contain the network response. 241 void BreakpadHandleNetworkResponse(BreakpadRef ref, 242 NSDictionary *configuration, 243 NSData *data, 244 NSError *error); 245 246 // Upload a file to the server. |data| is the content of the file to sent. 247 // |server_parameters| is additional server parameters to send. 248 void BreakpadUploadData(BreakpadRef ref, NSData *data, NSString *name, 249 NSDictionary *server_parameters); 250 251 // Generate a breakpad minidump and configuration file in the dump directory. 252 // The report will be available for uploading. The paths of the created files 253 // are returned in the dictionary. |server_parameters| is additional server 254 // parameters to add in the config file. 255 NSDictionary *BreakpadGenerateReport(BreakpadRef ref, 256 NSDictionary *server_parameters); 257 258 #ifdef __cplusplus 259 } 260 #endif 261