230 lines
8.8 KiB
C
230 lines
8.8 KiB
C
|
//
|
||
|
|
// SPUUpdater.h
|
||
|
|
// Sparkle
|
||
|
|
//
|
||
|
|
// Created by Andy Matuschak on 1/4/06.
|
||
|
|
// Copyright 2006 Andy Matuschak. All rights reserved.
|
||
|
|
//
|
||
|
|
|
||
|
|
#if __has_feature(modules)
|
||
|
|
#if __has_warning("-Watimport-in-framework-header")
|
||
|
|
#pragma clang diagnostic ignored "-Watimport-in-framework-header"
|
||
|
|
#endif
|
||
|
|
@import Foundation;
|
||
|
|
#else
|
||
|
|
#import <Foundation/Foundation.h>
|
||
|
|
#endif
|
||
|
|
#import "SUExport.h"
|
||
|
|
#import "SPUUserDriver.h"
|
||
|
|
|
||
|
|
NS_ASSUME_NONNULL_BEGIN
|
||
|
|
|
||
|
|
@class SUAppcastItem, SUAppcast;
|
||
|
|
|
||
|
|
@protocol SPUUpdaterDelegate;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The main API in Sparkle for controlling the update mechanism.
|
||
|
|
|
||
|
|
This class is used to configure the update parameters as well as manually
|
||
|
|
and automatically schedule and control checks for updates.
|
||
|
|
*/
|
||
|
|
SU_EXPORT @interface SPUUpdater : NSObject
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Initializes a new SPUUpdater instance
|
||
|
|
|
||
|
|
This does not start the updater. To start it, see -[SPUUpdater startUpdater:]
|
||
|
|
|
||
|
|
Note that this is a normal initializer and doesn't implement the singleton pattern (i.e, instances aren't cached, so no surprises)
|
||
|
|
This also means that updater instances can be deallocated, and that they will be torn down properly.
|
||
|
|
|
||
|
|
Related: See SPUStandardUpdaterController which wraps a SPUUpdater instance and is suitable for instantiating in nib files
|
||
|
|
|
||
|
|
@param hostBundle The bundle that should be targetted for updating. This must not be nil.
|
||
|
|
@param applicationBundle The application bundle that should be relaunched and waited for termination. Usually this can be the same as hostBundle. This may differ when updating a plug-in or other non-application bundle.
|
||
|
|
@param userDriver The user driver that Sparkle uses for user update interaction
|
||
|
|
@param delegate The delegate for SPUUpdater. This may be nil.
|
||
|
|
*/
|
||
|
|
- (instancetype)initWithHostBundle:(NSBundle *)hostBundle applicationBundle:(NSBundle *)applicationBundle userDriver:(id <SPUUserDriver>)userDriver delegate:(id<SPUUpdaterDelegate> _Nullable)delegate;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Starts the updater.
|
||
|
|
|
||
|
|
This method checks if Sparkle is configured properly. A valid feed URL should be set before this method is invoked.
|
||
|
|
Other properties of this SPUUpdater instance can be set before this method is invoked as well, such as automatic update checks.
|
||
|
|
|
||
|
|
If the configuration is valid, this method may bring up a permission prompt (if needed) for checking if the user wants automatic update checking.
|
||
|
|
This method then starts the regular update cycle if automatic update checks are enabled.
|
||
|
|
|
||
|
|
One of -checkForUpdates, -checkForUpdatesInBackground, or -checkForUpdateInformation can be invoked before starting the updater.
|
||
|
|
This preschedules an update action before starting the updater. When the updater is started, the prescheduled action is immediately invoked.
|
||
|
|
This may be useful for example if you want to check for updates right away without a permission prompt potentially showing.
|
||
|
|
|
||
|
|
This must be called on the main thread.
|
||
|
|
|
||
|
|
@param error The error that is populated if this method fails. Pass NULL if not interested in the error information.
|
||
|
|
@return YES if the updater started otherwise NO with a populated error
|
||
|
|
*/
|
||
|
|
- (BOOL)startUpdater:(NSError * __autoreleasing *)error;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Checks for updates, and displays progress while doing so.
|
||
|
|
|
||
|
|
This is meant for users initiating an update check.
|
||
|
|
This may find a resumable update that has already been downloaded or has begun installing, or
|
||
|
|
this may find a new update that can start to be downloaded if the user requests it.
|
||
|
|
This will find updates that the user has opted into skipping.
|
||
|
|
*/
|
||
|
|
- (void)checkForUpdates;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Checks for updates, but does not display any UI unless an update is found.
|
||
|
|
|
||
|
|
This is meant for programmatically initating a check for updates.
|
||
|
|
That is, it will display no UI unless it finds an update, in which case it proceeds as usual.
|
||
|
|
This will not find updates that the user has opted into skipping.
|
||
|
|
|
||
|
|
Note if there is no resumable update found, and automated updating is turned on,
|
||
|
|
the update will be downloaded in the background without disrupting the user.
|
||
|
|
*/
|
||
|
|
- (void)checkForUpdatesInBackground;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Begins a "probing" check for updates which will not actually offer to
|
||
|
|
update to that version.
|
||
|
|
|
||
|
|
However, the delegate methods
|
||
|
|
SPUUpdaterDelegate::updater:didFindValidUpdate: and
|
||
|
|
SPUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
|
||
|
|
so you can use that information in your UI.
|
||
|
|
|
||
|
|
Updates that have been skipped by the user will not be found.
|
||
|
|
*/
|
||
|
|
- (void)checkForUpdateInformation;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
A property indicating whether or not updates can be checked.
|
||
|
|
|
||
|
|
This property is useful for determining whether update checks can be made programatically or by the user.
|
||
|
|
An update check cannot be made when an on-going update check is in progress.
|
||
|
|
|
||
|
|
Note this property does not reflect whether or not an update itself is in progress. For example,
|
||
|
|
an update check can be done to check if there's an already started update that can be resumed.
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly) BOOL canCheckForUpdates;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
A property indicating whether or not to check for updates automatically.
|
||
|
|
|
||
|
|
Setting this property will persist in the host bundle's user defaults.
|
||
|
|
The update schedule cycle will be reset in a short delay after the property's new value is set.
|
||
|
|
This is to allow reverting this property without kicking off a schedule change immediately
|
||
|
|
*/
|
||
|
|
@property (nonatomic) BOOL automaticallyChecksForUpdates;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
A property indicating the current automatic update check interval.
|
||
|
|
|
||
|
|
Setting this property will persist in the host bundle's user defaults.
|
||
|
|
The update schedule cycle will be reset in a short delay after the property's new value is set.
|
||
|
|
This is to allow reverting this property without kicking off a schedule change immediately
|
||
|
|
*/
|
||
|
|
@property (nonatomic) NSTimeInterval updateCheckInterval;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
A property indicating whether or not updates can be automatically downloaded in the background.
|
||
|
|
|
||
|
|
Note that the developer can disallow automatic downloading of updates from being enabled.
|
||
|
|
In this case, -automaticallyDownloadsUpdates will return NO regardless of how this property is set.
|
||
|
|
|
||
|
|
Setting this property will persist in the host bundle's user defaults.
|
||
|
|
*/
|
||
|
|
@property (nonatomic) BOOL automaticallyDownloadsUpdates;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The URL of the appcast used to download update information.
|
||
|
|
|
||
|
|
If the updater's delegate implements -[SPUUpdaterDelegate feedURLStringForUpdater:], this will return that feed URL.
|
||
|
|
Otherwise if the feed URL has been set before, the feed URL returned will be retrieved from the host bundle's user defaults.
|
||
|
|
Otherwise the feed URL in the host bundle's Info.plist will be returned.
|
||
|
|
If no feed URL can be retrieved, returns nil.
|
||
|
|
|
||
|
|
This property must be called on the main thread; calls from background threads will return nil.
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly) NSURL *feedURL;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Set the URL of the appcast used to download update information. Using this method is discouraged.
|
||
|
|
|
||
|
|
Setting this property will persist in the host bundle's user defaults.
|
||
|
|
To avoid this, you should consider instead implementing
|
||
|
|
-[SPUUpdaterDelegate feedURLStringForUpdater:] or -[SPUUpdaterDelegate feedParametersForUpdater:sendingSystemProfile:]
|
||
|
|
|
||
|
|
Passing nil will remove any feed URL that has been set in the host bundle's user defaults.
|
||
|
|
|
||
|
|
This method must be called on the main thread; calls from background threads will have no effect.
|
||
|
|
*/
|
||
|
|
- (void)setFeedURL:(NSURL * _Nullable)feedURL;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The host bundle that is being updated.
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly) NSBundle *hostBundle;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The bundle this class (SPUUpdater) is loaded into
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly) NSBundle *sparkleBundle;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
* The user agent used when checking for updates.
|
||
|
|
*
|
||
|
|
* The default implementation can be overrided.
|
||
|
|
*/
|
||
|
|
@property (nonatomic, copy) NSString *userAgentString;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The HTTP headers used when checking for updates.
|
||
|
|
|
||
|
|
The keys of this dictionary are HTTP header fields (NSString) and values are corresponding values (NSString)
|
||
|
|
*/
|
||
|
|
#if __has_feature(objc_generics)
|
||
|
|
@property (nonatomic, copy, nullable) NSDictionary<NSString *, NSString *> *httpHeaders;
|
||
|
|
#else
|
||
|
|
@property (nonatomic, copy, nullable) NSDictionary *httpHeaders;
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*!
|
||
|
|
A property indicating whether or not the user's system profile information is sent when checking for updates.
|
||
|
|
|
||
|
|
Setting this property will persist in the host bundle's user defaults.
|
||
|
|
*/
|
||
|
|
@property (nonatomic) BOOL sendsSystemProfile;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Returns the date of last update check.
|
||
|
|
|
||
|
|
\returns \c nil if no check has been performed.
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly, copy, nullable) NSDate *lastUpdateCheckDate;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
Appropriately schedules or cancels the update checking timer according to
|
||
|
|
the preferences for time interval and automatic checks.
|
||
|
|
|
||
|
|
This call does not change the date of the next check,
|
||
|
|
but only the internal timer.
|
||
|
|
*/
|
||
|
|
- (void)resetUpdateCycle;
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
The system profile information that is sent when checking for updates
|
||
|
|
*/
|
||
|
|
@property (nonatomic, readonly, copy) NSArray<NSDictionary<NSString *, NSString *> *> *systemProfileArray;
|
||
|
|
|
||
|
|
@end
|
||
|
|
|
||
|
|
NS_ASSUME_NONNULL_END
|