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