Home | History | Annotate | Download | only in ios 
      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