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

   1 //
   2 //  SUUpdaterDelegate.h
   3 //  Sparkle
   4 //
   5 //  Created by Mayur Pawashe on 12/25/16.
   6 //  Copyright © 2016 Sparkle Project. All rights reserved.
   7 //
   8
   9 #if __has_feature(modules)
  10 @import Foundation;
  11 #else
  12 #import <Foundation/Foundation.h>
  13 #endif
  14
  15 #import "SUExport.h"
  16
  17 @protocol SUVersionComparison, SUVersionDisplay;
  18 @class SUUpdater, SUAppcast, SUAppcastItem;
  19
  20 NS_ASSUME_NONNULL_BEGIN
  21
  22 // -----------------------------------------------------------------------------
  23 // SUUpdater Notifications for events that might be interesting to more than just the delegate
  24 // The updater will be the notification object
  25 // -----------------------------------------------------------------------------
  26 SU_EXPORT extern NSString *const SUUpdaterDidFinishLoadingAppCastNotification;
  27 SU_EXPORT extern NSString *const SUUpdaterDidFindValidUpdateNotification;
  28 SU_EXPORT extern NSString *const SUUpdaterDidNotFindUpdateNotification;
  29 SU_EXPORT extern NSString *const SUUpdaterWillRestartNotification;
  30 #define SUUpdaterWillRelaunchApplicationNotification SUUpdaterWillRestartNotification;
  31 #define SUUpdaterWillInstallUpdateNotification SUUpdaterWillRestartNotification;
  32
  33 // Key for the SUAppcastItem object in the SUUpdaterDidFindValidUpdateNotification userInfo
  34 SU_EXPORT extern NSString *const SUUpdaterAppcastItemNotificationKey;
  35 // Key for the SUAppcast object in the SUUpdaterDidFinishLoadingAppCastNotification userInfo
  36 SU_EXPORT extern NSString *const SUUpdaterAppcastNotificationKey;
  37
  38 // -----------------------------------------------------------------------------
  39 // SUUpdater Delegate:
  40 // -----------------------------------------------------------------------------
  41
  42 /*!
  43  Provides methods to control the behavior of an SUUpdater object.
  44  */
  45 @protocol SUUpdaterDelegate <NSObject>
  46 @optional
  47
  48 /*!
  49  Returns whether to allow Sparkle to pop up.
  50
  51  For example, this may be used to prevent Sparkle from interrupting a setup assistant.
  52
  53  \param updater The SUUpdater instance.
  54  */
  55 - (BOOL)updaterMayCheckForUpdates:(SUUpdater *)updater;
  56
  57 /*!
  58  Returns additional parameters to append to the appcast URL's query string.
  59
  60  This is potentially based on whether or not Sparkle will also be sending along the system profile.
  61
  62  \param updater The SUUpdater instance.
  63  \param sendingProfile Whether the system profile will also be sent.
  64
  65  \return An array of dictionaries with keys: "key", "value", "displayKey", "displayValue", the latter two being specifically for display to the user.
  66  */
  67 - (NSArray<NSDictionary<NSString *, NSString *> *> *)feedParametersForUpdater:(SUUpdater *)updater sendingSystemProfile:(BOOL)sendingProfile;
  68
  69 /*!
  70  Returns a custom appcast URL.
  71
  72  Override this to dynamically specify the entire URL.
  73
  74  An alternative may be to use SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
  75  and let the server handle what kind of feed to provide.
  76
  77  \param updater The SUUpdater instance.
  78  */
  79 - (nullable NSString *)feedURLStringForUpdater:(SUUpdater *)updater;
  80
  81 /*!
  82  Returns whether Sparkle should prompt the user about automatic update checks.
  83
  84  Use this to override the default behavior.
  85
  86  \param updater The SUUpdater instance.
  87  */
  88 - (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:(SUUpdater *)updater;
  89
  90 /*!
  91  Called after Sparkle has downloaded the appcast from the remote server.
  92
  93  Implement this if you want to do some special handling with the appcast once it finishes loading.
  94
  95  \param updater The SUUpdater instance.
  96  \param appcast The appcast that was downloaded from the remote server.
  97  */
  98 - (void)updater:(SUUpdater *)updater didFinishLoadingAppcast:(SUAppcast *)appcast;
  99
 100 /*!
 101  Returns the item in the appcast corresponding to the update that should be installed.
 102
 103  If you're using special logic or extensions in your appcast,
 104  implement this to use your own logic for finding a valid update, if any,
 105  in the given appcast.
 106
 107  \param appcast The appcast that was downloaded from the remote server.
 108  \param updater The SUUpdater instance.
 109  */
 110 - (nullable SUAppcastItem *)bestValidUpdateInAppcast:(SUAppcast *)appcast forUpdater:(SUUpdater *)updater;
 111
 112 /*!
 113  Called when a valid update is found by the update driver.
 114
 115  \param updater The SUUpdater instance.
 116  \param item The appcast item corresponding to the update that is proposed to be installed.
 117  */
 118 - (void)updater:(SUUpdater *)updater didFindValidUpdate:(SUAppcastItem *)item;
 119
 120 /*!
 121  Called just before the scheduled update driver prompts the user to install an update.
 122
 123  \param updater The SUUpdater instance.
 124
 125  \return YES to allow the update prompt to be shown (the default behavior), or NO to suppress it.
 126  */
 127 - (BOOL)updaterShouldShowUpdateAlertForScheduledUpdate:(SUUpdater *)updater forItem:(SUAppcastItem *)item;
 128
 129 /*!
 130  Called after the user dismisses the update alert.
 131
 132  \param updater The SUUpdater instance.
 133  \param permanently YES if the alert will not appear again for this update; NO if it may reappear.
 134  */
 135 - (void)updater:(SUUpdater *)updater didDismissUpdateAlertPermanently:(BOOL)permanently forItem:(SUAppcastItem *)item;
 136
 137 /*!
 138  Called when a valid update is not found.
 139
 140  \param updater The SUUpdater instance.
 141  */
 142 - (void)updaterDidNotFindUpdate:(SUUpdater *)updater;
 143
 144 /*!
 145  Called when the user clicks the Skip This Version button.
 146
 147  \param updater The SUUpdater instance.
 148  */
 149 - (void)updater:(SUUpdater *)updater userDidSkipThisVersion:(SUAppcastItem *)item;
 150
 151 /*!
 152  Called immediately before downloading the specified update.
 153
 154  \param updater The SUUpdater instance.
 155  \param item The appcast item corresponding to the update that is proposed to be downloaded.
 156  \param request The mutable URL request that will be used to download the update.
 157  */
 158 - (void)updater:(SUUpdater *)updater willDownloadUpdate:(SUAppcastItem *)item withRequest:(NSMutableURLRequest *)request;
 159
 160 /*!
 161  Called immediately after succesfull download of the specified update.
 162
 163  \param updater The SUUpdater instance.
 164  \param item The appcast item corresponding to the update that has been downloaded.
 165  */
 166 - (void)updater:(SUUpdater *)updater didDownloadUpdate:(SUAppcastItem *)item;
 167
 168 /*!
 169  Called after the specified update failed to download.
 170
 171  \param updater The SUUpdater instance.
 172  \param item The appcast item corresponding to the update that failed to download.
 173  \param error The error generated by the failed download.
 174  */
 175 - (void)updater:(SUUpdater *)updater failedToDownloadUpdate:(SUAppcastItem *)item error:(NSError *)error;
 176
 177 /*!
 178  Called when the user clicks the cancel button while and update is being downloaded.
 179
 180  \param updater The SUUpdater instance.
 181  */
 182 - (void)userDidCancelDownload:(SUUpdater *)updater;
 183
 184 /*!
 185  Called immediately before extracting the specified downloaded update.
 186
 187  \param updater The SUUpdater instance.
 188  \param item The appcast item corresponding to the update that is proposed to be extracted.
 189  */
 190 - (void)updater:(SUUpdater *)updater willExtractUpdate:(SUAppcastItem *)item;
 191
 192 /*!
 193  Called immediately after extracting the specified downloaded update.
 194
 195  \param updater The SUUpdater instance.
 196  \param item The appcast item corresponding to the update that has been extracted.
 197  */
 198 - (void)updater:(SUUpdater *)updater didExtractUpdate:(SUAppcastItem *)item;
 199
 200 /*!
 201  Called immediately before installing the specified update.
 202
 203  \param updater The SUUpdater instance.
 204  \param item The appcast item corresponding to the update that is proposed to be installed.
 205  */
 206 - (void)updater:(SUUpdater *)updater willInstallUpdate:(SUAppcastItem *)item;
 207
 208 /*!
 209  Returns whether the relaunch should be delayed in order to perform other tasks.
 210
 211  This is not called if the user didn't relaunch on the previous update,
 212  in that case it will immediately restart.
 213
 214  \param updater The SUUpdater instance.
 215  \param item The appcast item corresponding to the update that is proposed to be installed.
 216  \param invocation The invocation that must be completed with `[invocation invoke]` before continuing with the relaunch.
 217
 218  \return \c YES to delay the relaunch until \p invocation is invoked.
 219  */
 220 - (BOOL)updater:(SUUpdater *)updater shouldPostponeRelaunchForUpdate:(SUAppcastItem *)item untilInvoking:(NSInvocation *)invocation;
 221
 222 /*!
 223  Returns whether the relaunch should be delayed in order to perform other tasks.
 224
 225  This is not called if the user didn't relaunch on the previous update,
 226  in that case it will immediately restart.
 227
 228  This method acts as a simpler alternative to SUUpdaterDelegate::updater:shouldPostponeRelaunchForUpdate:untilInvoking: avoiding usage of NSInvocation, which is not available in Swift environments.
 229
 230  \param updater The SUUpdater instance.
 231  \param item The appcast item corresponding to the update that is proposed to be installed.
 232
 233  \return \c YES to delay the relaunch.
 234  */
 235 - (BOOL)updater:(SUUpdater *)updater shouldPostponeRelaunchForUpdate:(SUAppcastItem *)item;
 236
 237 /*!
 238  Returns whether the application should be relaunched at all.
 239
 240  Some apps \b cannot be relaunched under certain circumstances.
 241  This method can be used to explicitly prevent a relaunch.
 242
 243  \param updater The SUUpdater instance.
 244  */
 245 - (BOOL)updaterShouldRelaunchApplication:(SUUpdater *)updater;
 246
 247 /*!
 248  Called immediately before relaunching.
 249
 250  \param updater The SUUpdater instance.
 251  */
 252 - (void)updaterWillRelaunchApplication:(SUUpdater *)updater;
 253
 254 /*!
 255  Called immediately after relaunching. SUUpdater delegate must be set before applicationDidFinishLaunching: to catch this event.
 256
 257  \param updater The SUUpdater instance.
 258  */
 259 - (void)updaterDidRelaunchApplication:(SUUpdater *)updater;
 260
 261 /*!
 262  Returns an object that compares version numbers to determine their arithmetic relation to each other.
 263
 264  This method allows you to provide a custom version comparator.
 265  If you don't implement this method or return \c nil,
 266  the standard version comparator will be used.
 267
 268  \sa SUStandardVersionComparator
 269
 270  \param updater The SUUpdater instance.
 271  */
 272 - (nullable id<SUVersionComparison>)versionComparatorForUpdater:(SUUpdater *)updater;
 273
 274 /*!
 275  Returns an object that formats version numbers for display to the user.
 276
 277  If you don't implement this method or return \c nil,
 278  the standard version formatter will be used.
 279
 280  \sa SUUpdateAlert
 281
 282  \param updater The SUUpdater instance.
 283  */
 284 - (nullable id<SUVersionDisplay>)versionDisplayerForUpdater:(SUUpdater *)updater;
 285
 286 /*!
 287  Returns the path which is used to relaunch the client after the update is installed.
 288
 289  The default is the path of the host bundle.
 290
 291  \param updater The SUUpdater instance.
 292  */
 293 - (nullable NSString *)pathToRelaunchForUpdater:(SUUpdater *)updater;
 294
 295 /*!
 296  Called before an updater shows a modal alert window,
 297  to give the host the opportunity to hide attached windows that may get in the way.
 298
 299  \param updater The SUUpdater instance.
 300  */
 301 - (void)updaterWillShowModalAlert:(SUUpdater *)updater;
 302
 303 /*!
 304  Called after an updater shows a modal alert window,
 305  to give the host the opportunity to hide attached windows that may get in the way.
 306
 307  \param updater The SUUpdater instance.
 308  */
 309 - (void)updaterDidShowModalAlert:(SUUpdater *)updater;
 310
 311 /*!
 312  Called when an update is scheduled to be silently installed on quit.
 313  This is after an update has been automatically downloaded in the background.
 314  (i.e. SUUpdater::automaticallyDownloadsUpdates is YES)
 315
 316  \param updater The SUUpdater instance.
 317  \param item The appcast item corresponding to the update that is proposed to be installed.
 318  \param invocation Can be used to trigger an immediate silent install and relaunch.
 319  */
 320 - (void)updater:(SUUpdater *)updater willInstallUpdateOnQuit:(SUAppcastItem *)item immediateInstallationInvocation:(NSInvocation *)invocation;
 321
 322 /*!
 323  Called when an update is scheduled to be silently installed on quit.
 324  This is after an update has been automatically downloaded in the background.
 325  (i.e. SUUpdater::automaticallyDownloadsUpdates is YES)
 326  This method acts as a more modern alternative to SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationInvocation: using a block instead of NSInvocation, which is not available in Swift environments.
 327
 328  \param updater The SUUpdater instance.
 329  \param item The appcast item corresponding to the update that is proposed to be installed.
 330  \param installationBlock Can be used to trigger an immediate silent install and relaunch.
 331  */
 332 - (void)updater:(SUUpdater *)updater willInstallUpdateOnQuit:(SUAppcastItem *)item immediateInstallationBlock:(void (^)(void))installationBlock;
 333
 334 /*!
 335  Calls after an update that was scheduled to be silently installed on quit has been canceled.
 336
 337  \param updater The SUUpdater instance.
 338  \param item The appcast item corresponding to the update that was proposed to be installed.
 339  */
 340 - (void)updater:(SUUpdater *)updater didCancelInstallUpdateOnQuit:(SUAppcastItem *)item;
 341
 342 /*!
 343  Called after an update is aborted due to an error.
 344
 345  \param updater The SUUpdater instance.
 346  \param error The error that caused the abort
 347  */
 348 - (void)updater:(SUUpdater *)updater didAbortWithError:(NSError *)error;
 349
 350 @end
 351
 352 NS_ASSUME_NONNULL_END