The Tor Browser: toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h@6474c204b198 (annotated)

toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h@6474c204b198 (annotated)

toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 // 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.
 //=============================================================================
 // 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

The Tor Browser / annotate

toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h@6474c204b198 (annotated)

toolkit/crashreporter/google-breakpad/src/client/mac/Framework/Breakpad.h