| // Copyright (c) 2006, Google Inc. |
| // All rights reserved. |
| // |
| // Redistribution and use in source and binary forms, with or without |
| // modification, are permitted provided that the following conditions are |
| // met: |
| // |
| // * Redistributions of source code must retain the above copyright |
| // notice, this list of conditions and the following disclaimer. |
| // * Redistributions in binary form must reproduce the above |
| // copyright notice, this list of conditions and the following disclaimer |
| // in the documentation and/or other materials provided with the |
| // distribution. |
| // * Neither the name of Google Inc. nor the names of its |
| // contributors may be used to endorse or promote products derived from |
| // this software without specific prior written permission. |
| // |
| // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| // |
| // Framework to provide a simple C API to crash reporting for |
| // applications. By default, if any machine-level exception (e.g., |
| // EXC_BAD_ACCESS) occurs, it will be handled by the BreakpadRef |
| // object as follows: |
| // |
| // 1. Create a minidump file (see Breakpad for details) |
| // 2. Prompt the user (using CFUserNotification) |
| // 3. Invoke a command line reporting tool to send the minidump to a |
| // server |
| // |
| // By specifying parameters to the BreakpadCreate function, you can |
| // modify the default behavior to suit your needs and wants and |
| // desires. |
| |
| // A service name associated with the original bootstrap parent port, saved in |
| // OnDemandServer and restored in Inspector. |
| #define BREAKPAD_BOOTSTRAP_PARENT_PORT "com.Breakpad.BootstrapParent" |
| |
| typedef void* BreakpadRef; |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <CoreFoundation/CoreFoundation.h> |
| #include <Foundation/Foundation.h> |
| |
| #include "BreakpadDefines.h" |
| |
| // Optional user-defined function to dec to decide if we should handle |
| // this crash or forward it along. |
| // Return true if you want Breakpad to handle it. |
| // Return false if you want Breakpad to skip it |
| // The exception handler always returns false, as if SEND_AND_EXIT were false |
| // (which means the next exception handler will take the exception) |
| typedef bool (*BreakpadFilterCallback)(int exception_type, |
| int exception_code, |
| mach_port_t crashing_thread, |
| void* context); |
| |
| // Create a new BreakpadRef object and install it as an exception |
| // handler. The |parameters| will typically be the contents of your |
| // bundle's Info.plist. |
| // |
| // You can also specify these additional keys for customizable behavior: |
| // Key: Value: |
| // BREAKPAD_PRODUCT Product name (e.g., "MyAwesomeProduct") |
| // This one is used as the key to identify |
| // the product when uploading. Falls back to |
| // CFBundleName if not specified. |
| // REQUIRED |
| // |
| // BREAKPAD_PRODUCT_DISPLAY This is the display name, e.g. a pretty |
| // name for the product when the crash_sender |
| // pops up UI for the user. Falls back first to |
| // CFBundleDisplayName and then to |
| // BREAKPAD_PRODUCT if not specified. |
| // |
| // BREAKPAD_VERSION Product version (e.g., 1.2.3), used |
| // as metadata for crash report. Falls back to |
| // CFBundleVersion if not specified. |
| // REQUIRED |
| // |
| // BREAKPAD_VENDOR Vendor name, used in UI (e.g. "A report has |
| // been created that you can send to <vendor>") |
| // |
| // BREAKPAD_URL URL destination for reporting |
| // REQUIRED |
| // |
| // BREAKPAD_REPORT_INTERVAL # of seconds between sending |
| // reports. If an additional report is |
| // generated within this time, it will |
| // be ignored. Default: 3600sec. |
| // Specify 0 to send all reports. |
| // |
| // BREAKPAD_SKIP_CONFIRM If true, the reporter will send the report |
| // without any user intervention. |
| // Defaults to NO |
| // |
| // BREAKPAD_CONFIRM_TIMEOUT Number of seconds before the upload |
| // confirmation dialog will be automatically |
| // dismissed (cancelling the upload). |
| // Default: 300 seconds (min of 60). |
| // Specify 0 to prevent timeout. |
| // |
| // BREAKPAD_SEND_AND_EXIT If true, the handler will exit after sending. |
| // This will prevent any other handler (e.g., |
| // CrashReporter) from getting the crash. |
| // Defaults TO YES |
| // |
| // BREAKPAD_DUMP_DIRECTORY The directory to store crash-dumps |
| // in. By default, we use |
| // ~/Library/Breakpad/<BREAKPAD_PRODUCT> |
| // The path you specify here is tilde-expanded. |
| // |
| // BREAKPAD_INSPECTOR_LOCATION The full path to the Inspector executable. |
| // Defaults to <Framework resources>/Inspector |
| // |
| // BREAKPAD_REPORTER_EXE_LOCATION The full path to the Reporter/sender |
| // executable. |
| // Default: |
| // <Framework Resources>/crash_report_sender.app |
| // |
| // BREAKPAD_LOGFILES Indicates an array of log file paths that |
| // should be uploaded at crash time. |
| // |
| // BREAKPAD_REQUEST_COMMENTS If true, the message dialog will have a |
| // text box for the user to enter comments. |
| // Default: NO |
| // |
| // BREAKPAD_REQUEST_EMAIL If true and BREAKPAD_REQUEST_COMMENTS is also |
| // true, the message dialog will have a text |
| // box for the user to enter their email address. |
| // Default: NO |
| // |
| // BREAKPAD_SERVER_TYPE A parameter that tells Breakpad how to |
| // rewrite the upload parameters for a specific |
| // server type. The currently valid values are |
| // 'socorro' or 'google'. If you want to add |
| // other types, see the function in |
| // crash_report_sender.m that maps parameters to |
| // URL parameters. Defaults to 'google'. |
| // |
| // BREAKPAD_SERVER_PARAMETER_DICT A plist dictionary of static |
| // parameters that are uploaded to the |
| // server. The parameters are sent as |
| // is to the crash server. Their |
| // content isn't added to the minidump |
| // but pass as URL parameters when |
| // uploading theminidump to the crash |
| // server. |
| // |
| // BREAKPAD_IN_PROCESS A boolean NSNumber value. If YES, Breakpad |
| // will write the dump file in-process and then |
| // launch the reporter executable as a child |
| // process. |
| //============================================================================= |
| // The BREAKPAD_PRODUCT, BREAKPAD_VERSION and BREAKPAD_URL are |
| // required to have non-NULL values. By default, the BREAKPAD_PRODUCT |
| // will be the CFBundleName and the BREAKPAD_VERSION will be the |
| // CFBundleVersion when these keys are present in the bundle's |
| // Info.plist, which is usually passed in to BreakpadCreate() as an |
| // NSDictionary (you could also pass in another dictionary that had |
| // the same keys configured). If the BREAKPAD_PRODUCT or |
| // BREAKPAD_VERSION are ultimately undefined, BreakpadCreate() will |
| // fail. You have been warned. |
| // |
| // If you are running in a debugger, Breakpad will not install, unless the |
| // BREAKPAD_IGNORE_DEBUGGER envionment variable is set and/or non-zero. |
| // |
| // The BREAKPAD_SKIP_CONFIRM and BREAKPAD_SEND_AND_EXIT default |
| // values are NO and YES. However, they can be controlled by setting their |
| // values in a user or global plist. |
| // |
| // It's easiest to use Breakpad via the Framework, but if you're compiling the |
| // code in directly, BREAKPAD_INSPECTOR_LOCATION and |
| // BREAKPAD_REPORTER_EXE_LOCATION allow you to specify custom paths |
| // to the helper executables. |
| // |
| //============================================================================= |
| // The following are NOT user-supplied but are documented here for |
| // completeness. They are calculated by Breakpad during initialization & |
| // crash-dump generation, or entered in by the user. |
| // |
| // BREAKPAD_PROCESS_START_TIME The time, in seconds since the Epoch, the |
| // process started |
| // |
| // BREAKPAD_PROCESS_CRASH_TIME The time, in seconds since the Epoch, the |
| // process crashed. |
| // |
| // BREAKPAD_PROCESS_UP_TIME The total time in milliseconds the process |
| // has been running. This parameter is not |
| // set until the crash-dump-generation phase. |
| // |
| // BREAKPAD_LOGFILE_KEY_PREFIX Used to find out which parameters in the |
| // parameter dictionary correspond to log |
| // file paths. |
| // |
| // BREAKPAD_SERVER_PARAMETER_PREFIX This prefix is used by Breakpad |
| // internally, because Breakpad uses |
| // the same dictionary internally to |
| // track both its internal |
| // configuration parameters and |
| // parameters meant to be uploaded |
| // to the server. This string is |
| // used internally by Breakpad to |
| // prefix user-supplied parameter |
| // names so those can be sent to the |
| // server without leaking Breakpad's |
| // internal values. |
| // |
| // BREAKPAD_ON_DEMAND Used internally to indicate to the |
| // Reporter that we're sending on-demand, |
| // not as result of a crash. |
| // |
| // BREAKPAD_COMMENTS The text the user provided as comments. |
| // Only used in crash_report_sender. |
| |
| // Returns a new BreakpadRef object on success, NULL otherwise. |
| BreakpadRef BreakpadCreate(NSDictionary* parameters); |
| |
| // Uninstall and release the data associated with |ref|. |
| void BreakpadRelease(BreakpadRef ref); |
| |
| // Clients may set an optional callback which gets called when a crash |
| // occurs. The callback function should return |true| if we should |
| // handle the crash, generate a crash report, etc. or |false| if we |
| // should ignore it and forward the crash (normally to CrashReporter). |
| // Context is a pointer to arbitrary data to make the callback with. |
| void BreakpadSetFilterCallback(BreakpadRef ref, |
| BreakpadFilterCallback callback, |
| void* context); |
| |
| // User defined key and value string storage. Generally this is used |
| // to configure Breakpad's internal operation, such as whether the |
| // crash_sender should prompt the user, or the filesystem location for |
| // the minidump file. See Breakpad.h for some parameters that can be |
| // set. Anything longer than 255 bytes will be truncated. Note that |
| // the string is converted to UTF8 before truncation, so any multibyte |
| // character that straddles the 255(256 - 1 for terminator) byte limit |
| // will be mangled. |
| // |
| // A maximum number of 64 key/value pairs are supported. An assert() |
| // will fire if more than this number are set. Unfortunately, right |
| // now, the same dictionary is used for both Breakpad's parameters AND |
| // the Upload parameters. |
| // |
| // TODO (nealsid): Investigate how necessary this is if we don't |
| // automatically upload parameters to the server anymore. |
| // TODO (nealsid): separate server parameter dictionary from the |
| // dictionary used to configure Breakpad, and document limits for each |
| // independently. |
| void BreakpadSetKeyValue(BreakpadRef ref, NSString* key, NSString* value); |
| NSString* BreakpadKeyValue(BreakpadRef ref, NSString* key); |
| void BreakpadRemoveKeyValue(BreakpadRef ref, NSString* key); |
| |
| // You can use this method to specify parameters that will be uploaded |
| // to the crash server. They will be automatically encoded as |
| // necessary. Note that as mentioned above there are limits on both |
| // the number of keys and their length. |
| void BreakpadAddUploadParameter(BreakpadRef ref, NSString* key, |
| NSString* value); |
| |
| // This method will remove a previously-added parameter from the |
| // upload parameter set. |
| void BreakpadRemoveUploadParameter(BreakpadRef ref, NSString* key); |
| |
| // Add a log file for Breakpad to read and send upon crash dump |
| void BreakpadAddLogFile(BreakpadRef ref, NSString* logPathname); |
| |
| // Generate a minidump and send |
| void BreakpadGenerateAndSendReport(BreakpadRef ref); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
