The Tor Browser / file revision

 // Copyright (c) 2011, 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. Create a config file.

 //

 // These files can then be uploaded to a server.

 typedef void *BreakpadRef;

 #ifdef __cplusplus

 extern "C" {

 #endif

 #include <Foundation/Foundation.h>

 #include <client/apple/Framework/BreakpadDefines.h>

 // The keys in the dictionary returned by |BreakpadGenerateReport|.

 #define BREAKPAD_OUTPUT_DUMP_FILE   "BreakpadDumpFile"

 #define BREAKPAD_OUTPUT_CONFIG_FILE "BreakpadConfigFile"

 // Optional user-defined function 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_DUMP_DIRECTORY        The directory to store crash-dumps

 //                                in. By default, we use

 //                                ~/Library/Cache/Breakpad/<BREAKPAD_PRODUCT>

 //                                The path you specify here is tilde-expanded.

 //

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

 // 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);

 // 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);

 // Method to handle uploading data to the server

 // Returns if there is some report to send to the server.

 bool BreakpadHasCrashReportToUpload(BreakpadRef ref);

 // Upload next report to the server.

 void BreakpadUploadNextReport(BreakpadRef ref);

 // Upload a file to the server. |data| is the content of the file to sent.

 // |server_parameters| is additional server parameters to send.

 void BreakpadUploadData(BreakpadRef ref, NSData *data, NSString *name,

                         NSDictionary *server_parameters);

 // Generate a breakpad minidump and configuration file in the dump directory.

 // The report will be available for uploading. The paths of the created files

 // are returned in the dictionary. |server_parameters| is additional server

 // parameters to add in the config file.

 NSDictionary *BreakpadGenerateReport(BreakpadRef ref,

                                      NSDictionary *server_parameters);

 #ifdef __cplusplus

 }

 #endif