5 // Created by Mayur Pawashe on 12/25/16.
6 // Copyright © 2016 Sparkle Project. All rights reserved.
9 #if __has_feature(modules)
12 #import <Foundation/Foundation.h>
17 @protocol SUVersionComparison
, SUVersionDisplay
;
18 @
class SUUpdater
, SUAppcast
, SUAppcastItem
;
20 NS_ASSUME_NONNULL_BEGIN
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;
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
;
38 // -----------------------------------------------------------------------------
39 // SUUpdater Delegate:
40 // -----------------------------------------------------------------------------
43 Provides methods to control the behavior of an SUUpdater object.
45 @protocol SUUpdaterDelegate
<NSObject
>
49 Returns whether to allow Sparkle to pop up.
51 For example, this may be used to prevent Sparkle from interrupting a setup assistant.
53 \param updater The SUUpdater instance.
55 - (BOOL
)updaterMayCheckForUpdates
:(SUUpdater
*)updater
;
58 Returns additional parameters to append to the appcast URL's query string.
60 This is potentially based on whether or not Sparkle will also be sending along the system profile.
62 \param updater The SUUpdater instance.
63 \param sendingProfile Whether the system profile will also be sent.
65 \return An array of dictionaries with keys: "key", "value", "displayKey", "displayValue", the latter two being specifically for display to the user.
67 - (NSArray
<NSDictionary
<NSString
*, NSString
*> *> *)feedParametersForUpdater
:(SUUpdater
*)updater sendingSystemProfile
:(BOOL
)sendingProfile
;
70 Returns a custom appcast URL.
72 Override this to dynamically specify the entire URL.
74 An alternative may be to use SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
75 and let the server handle what kind of feed to provide.
77 \param updater The SUUpdater instance.
79 - (nullable NSString
*)feedURLStringForUpdater
:(SUUpdater
*)updater
;
82 Returns whether Sparkle should prompt the user about automatic update checks.
84 Use this to override the default behavior.
86 \param updater The SUUpdater instance.
88 - (BOOL
)updaterShouldPromptForPermissionToCheckForUpdates
:(SUUpdater
*)updater
;
91 Called after Sparkle has downloaded the appcast from the remote server.
93 Implement this if you want to do some special handling with the appcast once it finishes loading.
95 \param updater The SUUpdater instance.
96 \param appcast The appcast that was downloaded from the remote server.
98 - (void)updater
:(SUUpdater
*)updater didFinishLoadingAppcast
:(SUAppcast
*)appcast
;
101 Returns the item in the appcast corresponding to the update that should be installed.
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.
107 \param appcast The appcast that was downloaded from the remote server.
108 \param updater The SUUpdater instance.
110 - (nullable SUAppcastItem
*)bestValidUpdateInAppcast
:(SUAppcast
*)appcast forUpdater
:(SUUpdater
*)updater
;
113 Called when a valid update is found by the update driver.
115 \param updater The SUUpdater instance.
116 \param item The appcast item corresponding to the update that is proposed to be installed.
118 - (void)updater
:(SUUpdater
*)updater didFindValidUpdate
:(SUAppcastItem
*)item
;
121 Called when a valid update is not found.
123 \param updater The SUUpdater instance.
125 - (void)updaterDidNotFindUpdate
:(SUUpdater
*)updater
;
128 Called immediately before downloading the specified update.
130 \param updater The SUUpdater instance.
131 \param item The appcast item corresponding to the update that is proposed to be downloaded.
132 \param request The mutable URL request that will be used to download the update.
134 - (void)updater
:(SUUpdater
*)updater willDownloadUpdate
:(SUAppcastItem
*)item withRequest
:(NSMutableURLRequest
*)request
;
137 Called immediately after succesfull download of the specified update.
139 \param updater The SUUpdater instance.
140 \param item The appcast item corresponding to the update that has been downloaded.
142 - (void)updater
:(SUUpdater
*)updater didDownloadUpdate
:(SUAppcastItem
*)item
;
145 Called after the specified update failed to download.
147 \param updater The SUUpdater instance.
148 \param item The appcast item corresponding to the update that failed to download.
149 \param error The error generated by the failed download.
151 - (void)updater
:(SUUpdater
*)updater failedToDownloadUpdate
:(SUAppcastItem
*)item error
:(NSError
*)error
;
154 Called when the user clicks the cancel button while and update is being downloaded.
156 \param updater The SUUpdater instance.
158 - (void)userDidCancelDownload
:(SUUpdater
*)updater
;
161 Called immediately before extracting the specified downloaded update.
163 \param updater The SUUpdater instance.
164 \param item The appcast item corresponding to the update that is proposed to be extracted.
166 - (void)updater
:(SUUpdater
*)updater willExtractUpdate
:(SUAppcastItem
*)item
;
169 Called immediately after extracting the specified downloaded update.
171 \param updater The SUUpdater instance.
172 \param item The appcast item corresponding to the update that has been extracted.
174 - (void)updater
:(SUUpdater
*)updater didExtractUpdate
:(SUAppcastItem
*)item
;
177 Called immediately before installing the specified update.
179 \param updater The SUUpdater instance.
180 \param item The appcast item corresponding to the update that is proposed to be installed.
182 - (void)updater
:(SUUpdater
*)updater willInstallUpdate
:(SUAppcastItem
*)item
;
185 Returns whether the relaunch should be delayed in order to perform other tasks.
187 This is not called if the user didn't relaunch on the previous update,
188 in that case it will immediately restart.
190 \param updater The SUUpdater instance.
191 \param item The appcast item corresponding to the update that is proposed to be installed.
192 \param invocation The invocation that must be completed with `[invocation invoke]` before continuing with the relaunch.
194 \return \c YES to delay the relaunch until \p invocation is invoked.
196 - (BOOL
)updater
:(SUUpdater
*)updater shouldPostponeRelaunchForUpdate
:(SUAppcastItem
*)item untilInvoking
:(NSInvocation
*)invocation
;
199 Returns whether the application should be relaunched at all.
201 Some apps \b cannot be relaunched under certain circumstances.
202 This method can be used to explicitly prevent a relaunch.
204 \param updater The SUUpdater instance.
206 - (BOOL
)updaterShouldRelaunchApplication
:(SUUpdater
*)updater
;
209 Called immediately before relaunching.
211 \param updater The SUUpdater instance.
213 - (void)updaterWillRelaunchApplication
:(SUUpdater
*)updater
;
216 Called immediately after relaunching. SUUpdater delegate must be set before applicationDidFinishLaunching: to catch this event.
218 \param updater The SUUpdater instance.
220 - (void)updaterDidRelaunchApplication
:(SUUpdater
*)updater
;
223 Returns an object that compares version numbers to determine their arithmetic relation to each other.
225 This method allows you to provide a custom version comparator.
226 If you don't implement this method or return \c nil,
227 the standard version comparator will be used.
229 \sa SUStandardVersionComparator
231 \param updater The SUUpdater instance.
233 - (nullable id
<SUVersionComparison
>)versionComparatorForUpdater
:(SUUpdater
*)updater
;
236 Returns an object that formats version numbers for display to the user.
238 If you don't implement this method or return \c nil,
239 the standard version formatter will be used.
243 \param updater The SUUpdater instance.
245 - (nullable id
<SUVersionDisplay
>)versionDisplayerForUpdater
:(SUUpdater
*)updater
;
248 Returns the path which is used to relaunch the client after the update is installed.
250 The default is the path of the host bundle.
252 \param updater The SUUpdater instance.
254 - (nullable NSString
*)pathToRelaunchForUpdater
:(SUUpdater
*)updater
;
257 Called before an updater shows a modal alert window,
258 to give the host the opportunity to hide attached windows that may get in the way.
260 \param updater The SUUpdater instance.
262 - (void)updaterWillShowModalAlert
:(SUUpdater
*)updater
;
265 Called after an updater shows a modal alert window,
266 to give the host the opportunity to hide attached windows that may get in the way.
268 \param updater The SUUpdater instance.
270 - (void)updaterDidShowModalAlert
:(SUUpdater
*)updater
;
273 Called when an update is scheduled to be silently installed on quit.
274 This is after an update has been automatically downloaded in the background.
275 (i.e. SUUpdater::automaticallyDownloadsUpdates is YES)
277 \param updater The SUUpdater instance.
278 \param item The appcast item corresponding to the update that is proposed to be installed.
279 \param invocation Can be used to trigger an immediate silent install and relaunch.
281 - (void)updater
:(SUUpdater
*)updater willInstallUpdateOnQuit
:(SUAppcastItem
*)item immediateInstallationInvocation
:(NSInvocation
*)invocation
;
284 Calls after an update that was scheduled to be silently installed on quit has been canceled.
286 \param updater The SUUpdater instance.
287 \param item The appcast item corresponding to the update that was proposed to be installed.
289 - (void)updater
:(SUUpdater
*)updater didCancelInstallUpdateOnQuit
:(SUAppcastItem
*)item
;
292 Called after an update is aborted due to an error.
294 \param updater The SUUpdater instance.
295 \param error The error that caused the abort
297 - (void)updater
:(SUUpdater
*)updater didAbortWithError
:(NSError
*)error
;
301 NS_ASSUME_NONNULL_END