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