Sparkle.framework/Versions/A/Headers/SUUpdater.h

   1 //
   2 //  SUUpdater.h
   3 //  Sparkle
   4 //
   5 //  Created by Andy Matuschak on 1/4/06.
   6 //  Copyright 2006 Andy Matuschak. All rights reserved.
   7 //
   8
   9 #ifndef SUUPDATER_H
  10 #define SUUPDATER_H
  11
  12 #if __has_feature(modules)
  13 @import Cocoa;
  14 #else
  15 #import <Cocoa/Cocoa.h>
  16 #endif
  17 #import "SUExport.h"
  18 #import "SUVersionComparisonProtocol.h"
  19 #import "SUVersionDisplayProtocol.h"
  20
  21 @class SUAppcastItem, SUAppcast;
  22
  23 @protocol SUUpdaterDelegate;
  24
  25 /*!
  26     The main API in Sparkle for controlling the update mechanism.
  27
  28     This class is used to configure the update paramters as well as manually
  29     and automatically schedule and control checks for updates.
  30  */
  31 SU_EXPORT @interface SUUpdater : NSObject
  32
  33 @property (unsafe_unretained) IBOutlet id<SUUpdaterDelegate> delegate;
  34
  35 /*!
  36  The shared updater for the main bundle.
  37
  38  This is equivalent to passing [NSBundle mainBundle] to SUUpdater::updaterForBundle:
  39  */
  40 + (SUUpdater *)sharedUpdater;
  41
  42 /*!
  43  The shared updater for a specified bundle.
  44
  45  If an updater has already been initialized for the provided bundle, that shared instance will be returned.
  46  */
  47 + (SUUpdater *)updaterForBundle:(NSBundle *)bundle;
  48
  49 /*!
  50  Designated initializer for SUUpdater.
  51
  52  If an updater has already been initialized for the provided bundle, that shared instance will be returned.
  53  */
  54 - (instancetype)initForBundle:(NSBundle *)bundle;
  55
  56 /*!
  57  Explicitly checks for updates and displays a progress dialog while doing so.
  58
  59  This method is meant for a main menu item.
  60  Connect any menu item to this action in Interface Builder,
  61  and Sparkle will check for updates and report back its findings verbosely
  62  when it is invoked.
  63
  64  This will find updates that the user has opted into skipping.
  65  */
  66 - (IBAction)checkForUpdates:(id)sender;
  67
  68 /*!
  69  The menu item validation used for the -checkForUpdates: action
  70  */
  71 - (BOOL)validateMenuItem:(NSMenuItem *)menuItem;
  72
  73 /*!
  74  Checks for updates, but does not display any UI unless an update is found.
  75
  76  This is meant for programmatically initating a check for updates. That is,
  77  it will display no UI unless it actually finds an update, in which case it
  78  proceeds as usual.
  79
  80  If automatic downloading of updates it turned on and allowed, however,
  81  this will invoke that behavior, and if an update is found, it will be downloaded
  82  in the background silently and will be prepped for installation.
  83
  84  This will not find updates that the user has opted into skipping.
  85  */
  86 - (void)checkForUpdatesInBackground;
  87
  88 /*!
  89  A property indicating whether or not to check for updates automatically.
  90
  91  Setting this property will persist in the host bundle's user defaults.
  92  The update schedule cycle will be reset in a short delay after the property's new value is set.
  93  This is to allow reverting this property without kicking off a schedule change immediately
  94  */
  95 @property BOOL automaticallyChecksForUpdates;
  96
  97 /*!
  98  A property indicating whether or not updates can be automatically downloaded in the background.
  99
 100  Note that automatic downloading of updates can be disallowed by the developer
 101  or by the user's system if silent updates cannot be done (eg: if they require authentication).
 102  In this case, -automaticallyDownloadsUpdates will return NO regardless of how this property is set.
 103
 104  Setting this property will persist in the host bundle's user defaults.
 105  */
 106 @property BOOL automaticallyDownloadsUpdates;
 107
 108 /*!
 109  A property indicating the current automatic update check interval.
 110
 111  Setting this property will persist in the host bundle's user defaults.
 112  The update schedule cycle will be reset in a short delay after the property's new value is set.
 113  This is to allow reverting this property without kicking off a schedule change immediately
 114  */
 115 @property NSTimeInterval updateCheckInterval;
 116
 117 /*!
 118  Begins a "probing" check for updates which will not actually offer to
 119  update to that version.
 120
 121  However, the delegate methods
 122  SUUpdaterDelegate::updater:didFindValidUpdate: and
 123  SUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
 124  so you can use that information in your UI.
 125
 126  Updates that have been skipped by the user will not be found.
 127  */
 128 - (void)checkForUpdateInformation;
 129
 130 /*!
 131  The URL of the appcast used to download update information.
 132
 133  Setting this property will persist in the host bundle's user defaults.
 134  If you don't want persistence, you may want to consider instead implementing
 135  SUUpdaterDelegate::feedURLStringForUpdater: or SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
 136
 137  This property must be called on the main thread.
 138  */
 139 @property (copy) NSURL *feedURL;
 140
 141 /*!
 142  The host bundle that is being updated.
 143  */
 144 @property (readonly, strong) NSBundle *hostBundle;
 145
 146 /*!
 147  The bundle this class (SUUpdater) is loaded into.
 148  */
 149 @property (strong, readonly) NSBundle *sparkleBundle;
 150
 151 /*!
 152  The user agent used when checking for and downloading updates.
 153
 154  The default implementation can be overrided.
 155  */
 156 @property (nonatomic, copy) NSString *userAgentString;
 157
 158 /*!
 159  The HTTP headers used when checking for and downloading updates.
 160
 161  The keys of this dictionary are HTTP header fields (NSString) and values are corresponding values (NSString)
 162  */
 163 @property (copy) NSDictionary<NSString *, NSString *> *httpHeaders;
 164
 165 /*!
 166  A property indicating whether or not the user's system profile information is sent when checking for updates.
 167
 168  Setting this property will persist in the host bundle's user defaults.
 169  */
 170 @property BOOL sendsSystemProfile;
 171
 172 /*!
 173  A property indicating the decryption password used for extracting updates shipped as Apple Disk Images (dmg)
 174  */
 175 @property (nonatomic, copy) NSString *decryptionPassword;
 176
 177 /*!
 178     This function ignores normal update schedule, ignores user preferences,
 179     and interrupts users with an unwanted immediate app update.
 180
 181     WARNING: this function should not be used in regular apps. This function
 182     is a user-unfriendly hack only for very special cases, like unstable
 183     rapidly-changing beta builds that would not run correctly if they were
 184     even one day out of date.
 185
 186     Instead of this function you should set `SUAutomaticallyUpdate` to `YES`,
 187     which will gracefully install updates when the app quits.
 188
 189     For UI-less/daemon apps that aren't usually quit, instead of this function,
 190     you can use the delegate method
 191     SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationInvocation:
 192     or
 193     SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationBlock:
 194     to immediately start installation when an update was found.
 195
 196     A progress dialog is shown but the user will never be prompted to read the
 197     release notes.
 198
 199     This function will cause update to be downloaded twice if automatic updates are
 200     enabled.
 201
 202     You may want to respond to the userDidCancelDownload delegate method in case
 203     the user clicks the "Cancel" button while the update is downloading.
 204  */
 205 - (void)installUpdatesIfAvailable __attribute__((deprecated("This method is deprecated. Please set SUAutomaticallyUpdate in your Info.plist or use automaticallyDownloadsUpdates property instead.")));
 206
 207 /*!
 208     Returns the date of last update check.
 209
 210     \returns \c nil if no check has been performed.
 211  */
 212 @property (readonly, copy) NSDate *lastUpdateCheckDate;
 213
 214 /*!
 215     Appropriately schedules or cancels the update checking timer according to
 216     the preferences for time interval and automatic checks.
 217
 218     This call does not change the date of the next check,
 219     but only the internal NSTimer.
 220  */
 221 - (void)resetUpdateCycle;
 222
 223 /*!
 224    A property indicating whether or not an update is in progress.
 225
 226    Note this property is not indicative of whether or not user initiated updates can be performed.
 227    Use SUUpdater::validateMenuItem: for that instead.
 228  */
 229 @property (readonly) BOOL updateInProgress;
 230
 231 @end
 232
 233 #endif