michael@0: // Copyright (c) 2006, 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. Prompt the user (using CFUserNotification) michael@0: // 3. Invoke a command line reporting tool to send the minidump to a michael@0: // server michael@0: // michael@0: // By specifying parameters to the BreakpadCreate function, you can michael@0: // modify the default behavior to suit your needs and wants and michael@0: // desires. michael@0: michael@0: // A service name associated with the original bootstrap parent port, saved in michael@0: // OnDemandServer and restored in Inspector. michael@0: #define BREAKPAD_BOOTSTRAP_PARENT_PORT "com.Breakpad.BootstrapParent" 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: #include michael@0: michael@0: #include "BreakpadDefines.h" michael@0: michael@0: // Optional user-defined function to dec to decide if we should handle michael@0: // this crash or 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_REPORT_INTERVAL # of seconds between sending michael@0: // reports. If an additional report is michael@0: // generated within this time, it will michael@0: // be ignored. Default: 3600sec. michael@0: // Specify 0 to send all reports. michael@0: // michael@0: // BREAKPAD_SKIP_CONFIRM If true, the reporter will send the report michael@0: // without any user intervention. michael@0: // Defaults to NO michael@0: // michael@0: // BREAKPAD_CONFIRM_TIMEOUT Number of seconds before the upload michael@0: // confirmation dialog will be automatically michael@0: // dismissed (cancelling the upload). michael@0: // Default: 300 seconds (min of 60). michael@0: // Specify 0 to prevent timeout. michael@0: // michael@0: // BREAKPAD_SEND_AND_EXIT If true, the handler will exit after sending. michael@0: // This will prevent any other handler (e.g., michael@0: // CrashReporter) from getting the crash. michael@0: // Defaults TO YES michael@0: // michael@0: // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps michael@0: // in. By default, we use michael@0: // ~/Library/Breakpad/ michael@0: // The path you specify here is tilde-expanded. michael@0: // michael@0: // BREAKPAD_INSPECTOR_LOCATION The full path to the Inspector executable. michael@0: // Defaults to /Inspector michael@0: // michael@0: // BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender michael@0: // executable. michael@0: // Default: michael@0: // /crash_report_sender.app michael@0: // michael@0: // BREAKPAD_LOGFILES Indicates an array of log file paths that michael@0: // should be uploaded at crash time. michael@0: // michael@0: // BREAKPAD_REQUEST_COMMENTS If true, the message dialog will have a michael@0: // text box for the user to enter comments. michael@0: // Default: NO michael@0: // michael@0: // BREAKPAD_REQUEST_EMAIL If true and BREAKPAD_REQUEST_COMMENTS is also michael@0: // true, the message dialog will have a text michael@0: // box for the user to enter their email address. michael@0: // Default: NO 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: // The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default michael@0: // values are NO and YES. However, they can be controlled by setting their michael@0: // values in a user or global plist. michael@0: // michael@0: // It's easiest to use Breakpad via the Framework, but if you're compiling the michael@0: // code in directly, BREAKPAD_INSPECTOR_LOCATION and michael@0: // BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths michael@0: // to the helper executables. 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_LOGFILE_KEY_PREFIX Used to find out which parameters in the michael@0: // parameter dictionary correspond to log michael@0: // file paths. 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: // BREAKPAD_ON_DEMAND Used internally to indicate to the michael@0: // Reporter that we're sending on-demand, michael@0: // not as result of a crash. michael@0: // michael@0: // BREAKPAD_COMMENTS The text the user provided as comments. michael@0: // Only used in crash_report_sender. 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: // Clients may set an optional callback which gets called when a crash michael@0: // occurs. The callback function should return |true| if we should michael@0: // handle the crash, generate a crash report, etc. or |false| if we michael@0: // should ignore it and forward the crash (normally to CrashReporter). michael@0: // Context is a pointer to arbitrary data to make the callback with. michael@0: void BreakpadSetFilterCallback(BreakpadRef ref, michael@0: BreakpadFilterCallback callback, michael@0: void *context); 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: // Add a log file for Breakpad to read and send upon crash dump michael@0: void BreakpadAddLogFile(BreakpadRef ref, NSString *logPathname); michael@0: michael@0: // Generate a minidump and send michael@0: void BreakpadGenerateAndSendReport(BreakpadRef ref); michael@0: michael@0: #ifdef __cplusplus michael@0: } michael@0: #endif