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