michael@0: // Copyright (c) 2011, Google Inc. michael@0: // All rights reserved. michael@0: // michael@0: // Redistribution and use in source and binary forms, with or without michael@0: // modification, are permitted provided that the following conditions are michael@0: // met: michael@0: // michael@0: // * Redistributions of source code must retain the above copyright michael@0: // notice, this list of conditions and the following disclaimer. michael@0: // * Redistributions in binary form must reproduce the above michael@0: // copyright notice, this list of conditions and the following disclaimer michael@0: // in the documentation and/or other materials provided with the michael@0: // distribution. michael@0: // * Neither the name of Google Inc. nor the names of its michael@0: // contributors may be used to endorse or promote products derived from michael@0: // this software without specific prior written permission. michael@0: // michael@0: // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS michael@0: // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT michael@0: // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR michael@0: // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT michael@0: // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT michael@0: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, michael@0: // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY michael@0: // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT michael@0: // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE michael@0: // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: michael@0: // Framework to provide a simple C API to crash reporting for michael@0: // applications. By default, if any machine-level exception (e.g., michael@0: // EXC_BAD_ACCESS) occurs, it will be handled by the BreakpadRef michael@0: // object as follows: michael@0: // michael@0: // 1. Create a minidump file (see Breakpad for details) michael@0: // 2. Create a config file. michael@0: // michael@0: // These files can then be uploaded to a server. michael@0: michael@0: typedef void *BreakpadRef; michael@0: michael@0: #ifdef __cplusplus michael@0: extern "C" { michael@0: #endif michael@0: michael@0: #include michael@0: michael@0: #include michael@0: michael@0: // The keys in the dictionary returned by |BreakpadGenerateReport|. michael@0: #define BREAKPAD_OUTPUT_DUMP_FILE "BreakpadDumpFile" michael@0: #define BREAKPAD_OUTPUT_CONFIG_FILE "BreakpadConfigFile" michael@0: michael@0: // Optional user-defined function to decide if we should handle this crash or michael@0: // forward it along. michael@0: // Return true if you want Breakpad to handle it. michael@0: // Return false if you want Breakpad to skip it michael@0: // The exception handler always returns false, as if SEND_AND_EXIT were false michael@0: // (which means the next exception handler will take the exception) michael@0: typedef bool (*BreakpadFilterCallback)(int exception_type, michael@0: int exception_code, michael@0: mach_port_t crashing_thread, michael@0: void *context); michael@0: michael@0: // Create a new BreakpadRef object and install it as an exception michael@0: // handler. The |parameters| will typically be the contents of your michael@0: // bundle's Info.plist. michael@0: // michael@0: // You can also specify these additional keys for customizable behavior: michael@0: // Key: Value: michael@0: // BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct") michael@0: // This one is used as the key to identify michael@0: // the product when uploading. Falls back to michael@0: // CFBundleName if not specified. michael@0: // REQUIRED michael@0: // michael@0: // BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty michael@0: // name for the product when the crash_sender michael@0: // pops up UI for the user. Falls back first to michael@0: // CFBundleDisplayName and then to michael@0: // BREAKPAD_PRODUCT if not specified. michael@0: // michael@0: // BREAKPAD_VERSION Product version (e.g., 1.2.3), used michael@0: // as metadata for crash report. Falls back to michael@0: // CFBundleVersion if not specified. michael@0: // REQUIRED michael@0: // michael@0: // BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has michael@0: // been created that you can send to ") michael@0: // michael@0: // BREAKPAD_URL URL destination for reporting michael@0: // REQUIRED michael@0: // michael@0: // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps michael@0: // in. By default, we use michael@0: // ~/Library/Cache/Breakpad/ michael@0: // The path you specify here is tilde-expanded. michael@0: // michael@0: // BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to michael@0: // rewrite the upload parameters for a specific michael@0: // server type. The currently valid values are michael@0: // 'socorro' or 'google'. If you want to add michael@0: // other types, see the function in michael@0: // crash_report_sender.m that maps parameters to michael@0: // URL parameters. Defaults to 'google'. michael@0: // michael@0: // BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static michael@0: // parameters that are uploaded to the michael@0: // server. The parameters are sent as michael@0: // is to the crash server. Their michael@0: // content isn't added to the minidump michael@0: // but pass as URL parameters when michael@0: // uploading theminidump to the crash michael@0: // server. michael@0: //============================================================================= michael@0: // The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are michael@0: // required to have non-NULL values. By default, the BREAKPAD_PRODUCT michael@0: // will be the CFBundleName and the BREAKPAD_VERSION will be the michael@0: // CFBundleVersion when these keys are present in the bundle's michael@0: // Info.plist, which is usually passed in to BreakpadCreate() as an michael@0: // NSDictionary (you could also pass in another dictionary that had michael@0: // the same keys configured). If the BREAKPAD_PRODUCT or michael@0: // BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will michael@0: // fail. You have been warned. michael@0: // michael@0: // If you are running in a debugger, Breakpad will not install, unless the michael@0: // BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero. michael@0: // michael@0: //============================================================================= michael@0: // The following are NOT user-supplied but are documented here for michael@0: // completeness. They are calculated by Breakpad during initialization & michael@0: // crash-dump generation, or entered in by the user. michael@0: // michael@0: // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the michael@0: // process started michael@0: // michael@0: // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the michael@0: // process crashed. michael@0: // michael@0: // BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process michael@0: // has been running. This parameter is not michael@0: // set until the crash-dump-generation phase. michael@0: // michael@0: // BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad michael@0: // internally, because Breakpad uses michael@0: // the same dictionary internally to michael@0: // track both its internal michael@0: // configuration parameters and michael@0: // parameters meant to be uploaded michael@0: // to the server. This string is michael@0: // used internally by Breakpad to michael@0: // prefix user-supplied parameter michael@0: // names so those can be sent to the michael@0: // server without leaking Breakpad's michael@0: // internal values. michael@0: michael@0: // Returns a new BreakpadRef object on success, NULL otherwise. michael@0: BreakpadRef BreakpadCreate(NSDictionary *parameters); michael@0: michael@0: // Uninstall and release the data associated with |ref|. michael@0: void BreakpadRelease(BreakpadRef ref); michael@0: michael@0: // User defined key and value string storage. Generally this is used michael@0: // to configure Breakpad's internal operation, such as whether the michael@0: // crash_sender should prompt the user, or the filesystem location for michael@0: // the minidump file. See Breakpad.h for some parameters that can be michael@0: // set. Anything longer than 255 bytes will be truncated. Note that michael@0: // the string is converted to UTF8 before truncation, so any multibyte michael@0: // character that straddles the 255(256 - 1 for terminator) byte limit michael@0: // will be mangled. michael@0: // michael@0: // A maximum number of 64 key/value pairs are supported. An assert() michael@0: // will fire if more than this number are set. Unfortunately, right michael@0: // now, the same dictionary is used for both Breakpad's parameters AND michael@0: // the Upload parameters. michael@0: // michael@0: // TODO (nealsid): Investigate how necessary this is if we don't michael@0: // automatically upload parameters to the server anymore. michael@0: // TODO (nealsid): separate server parameter dictionary from the michael@0: // dictionary used to configure Breakpad, and document limits for each michael@0: // independently. michael@0: void BreakpadSetKeyValue(BreakpadRef ref, NSString *key, NSString *value); michael@0: NSString *BreakpadKeyValue(BreakpadRef ref, NSString *key); michael@0: void BreakpadRemoveKeyValue(BreakpadRef ref, NSString *key); michael@0: michael@0: // You can use this method to specify parameters that will be uploaded michael@0: // to the crash server. They will be automatically encoded as michael@0: // necessary. Note that as mentioned above there are limits on both michael@0: // the number of keys and their length. michael@0: void BreakpadAddUploadParameter(BreakpadRef ref, NSString *key, michael@0: NSString *value); michael@0: michael@0: // This method will remove a previously-added parameter from the michael@0: // upload parameter set. michael@0: void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString *key); michael@0: michael@0: // Method to handle uploading data to the server michael@0: michael@0: // Returns if there is some report to send to the server. michael@0: bool BreakpadHasCrashReportToUpload(BreakpadRef ref); michael@0: michael@0: // Upload next report to the server. michael@0: void BreakpadUploadNextReport(BreakpadRef ref); michael@0: michael@0: // Upload a file to the server. |data| is the content of the file to sent. michael@0: // |server_parameters| is additional server parameters to send. michael@0: void BreakpadUploadData(BreakpadRef ref, NSData *data, NSString *name, michael@0: NSDictionary *server_parameters); michael@0: michael@0: // Generate a breakpad minidump and configuration file in the dump directory. michael@0: // The report will be available for uploading. The paths of the created files michael@0: // are returned in the dictionary. |server_parameters| is additional server michael@0: // parameters to add in the config file. michael@0: NSDictionary *BreakpadGenerateReport(BreakpadRef ref, michael@0: NSDictionary *server_parameters); michael@0: michael@0: #ifdef __cplusplus michael@0: } michael@0: #endif