1 // Copyright 2012 Google LLC 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google LLC nor the names of its 14 // contributors may be used to endorse or promote products derived from 15 // this software without specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 29 #ifndef CLIENT_IOS_HANDLER_IOS_BREAKPAD_CONTROLLER_H_ 30 #define CLIENT_IOS_HANDLER_IOS_BREAKPAD_CONTROLLER_H_ 31 32 #import <Foundation/Foundation.h> 33 34 #import "client/ios/Breakpad.h" 35 36 // This class is used to offer a higher level API around BreakpadRef. It 37 // configures it, ensures thread-safety, and sends crash reports back to the 38 // collecting server. By default, no crash reports are sent, the user must call 39 // |setUploadingEnabled:YES| to start the uploading. 40 @interface BreakpadController : NSObject { 41 @private 42 // The dispatch queue that will own the breakpad reference. 43 dispatch_queue_t queue_; 44 45 // Instance of Breakpad crash reporter. This is owned by the queue, but can 46 // be created on the main thread at startup. 47 BreakpadRef breakpadRef_; 48 49 // The dictionary that contains configuration for breakpad. Modifying it 50 // should only happen when the controller is not started. The initial value 51 // is the infoDictionary of the bundle of the application. 52 NSMutableDictionary* configuration_; 53 54 // Whether or not crash reports should be uploaded. 55 BOOL enableUploads_; 56 57 // Whether the controller has been started on the main thread. This is only 58 // used to assert the initialization order is correct. 59 BOOL started_; 60 61 // The interval to wait between two uploads. Value is 0 if no upload must be 62 // done. 63 int uploadIntervalInSeconds_; 64 65 // The dictionary that contains additional server parameters to send when 66 // uploading crash reports. 67 NSDictionary* uploadTimeParameters_; 68 69 // The callback to call on report upload completion. 70 BreakpadUploadCompletionCallback uploadCompleteCallback_; 71 } 72 73 // Singleton. 74 + (BreakpadController*)sharedInstance; 75 76 // Update the controller configuration. Merges its old configuration with the 77 // new one. Merge is done by replacing the old values by the new values. 78 - (void)updateConfiguration:(NSDictionary*)configuration; 79 80 // Reset the controller configuration to its initial value, which is the 81 // infoDictionary of the bundle of the application. 82 - (void)resetConfiguration; 83 84 // Configure the URL to upload the report to. This must be called at least once 85 // if the URL is not in the bundle information. 86 - (void)setUploadingURL:(NSString*)url; 87 88 // Set the minimal interval between two uploads in seconds. This must be called 89 // at least once if the interval is not in the bundle information. A value of 0 90 // will prevent uploads. 91 - (void)setUploadInterval:(int)intervalInSeconds; 92 93 // Set additional server parameters to send when uploading crash reports. 94 - (void)setParametersToAddAtUploadTime:(NSDictionary*)uploadTimeParameters; 95 96 // Specify an upload parameter that will be added to the crash report when a 97 // crash report is generated. See |BreakpadAddUploadParameter|. 98 - (void)addUploadParameter:(NSString*)value forKey:(NSString*)key; 99 100 // Sets the callback to be called after uploading a crash report to the server. 101 // Only the latest callback registered will be called. 102 - (void)setUploadCallback:(BreakpadUploadCompletionCallback)callback; 103 104 // Remove a previously-added parameter from the upload parameter set. See 105 // |BreakpadRemoveUploadParameter|. 106 - (void)removeUploadParameterForKey:(NSString*)key; 107 108 // Access the underlying BreakpadRef. This method is asynchronous, and will be 109 // executed on the thread owning the BreakpadRef variable. Moreover, if the 110 // controller is not started, the block will be called with a NULL parameter. 111 - (void)withBreakpadRef:(void(^)(BreakpadRef))callback; 112 113 // Starts the BreakpadController by registering crash handlers. If 114 // |onCurrentThread| is YES, all setup is done on the current thread, otherwise 115 // it is done on a private queue. 116 - (void)start:(BOOL)onCurrentThread; 117 118 // Unregisters the crash handlers. 119 - (void)stop; 120 121 // Returns whether or not the controller is started. 122 - (BOOL)isStarted; 123 124 // Enables or disables uploading of crash reports, but does not stop the 125 // BreakpadController. 126 - (void)setUploadingEnabled:(BOOL)enabled; 127 128 // Check if there is currently a crash report to upload. 129 - (void)hasReportToUpload:(void(^)(BOOL))callback; 130 131 // Get the number of crash reports waiting to upload. 132 - (void)getCrashReportCount:(void(^)(int))callback; 133 134 // Get the next report to upload. 135 // - If upload is disabled, callback will be called with (nil, -1). 136 // - If a delay is to be waited before sending, callback will be called with 137 // (nil, n), with n (> 0) being the number of seconds to wait. 138 // - if no delay is needed, callback will be called with (0, configuration), 139 // configuration being next report to upload, or nil if none is pending. 140 - (void)getNextReportConfigurationOrSendDelay: 141 (void(^)(NSDictionary*, int))callback; 142 143 // Get the date of the most recent crash report. 144 - (void)getDateOfMostRecentCrashReport:(void(^)(NSDate *))callback; 145 146 // Sends synchronously the report specified by |configuration|. This method is 147 // NOT thread safe and must be called from the breakpad thread. 148 - (void)threadUnsafeSendReportWithConfiguration:(NSDictionary*)configuration 149 withBreakpadRef:(BreakpadRef)ref; 150 151 @end 152 153 #endif // CLIENT_IOS_HANDLER_IOS_BREAKPAD_CONTROLLER_H_ 154