diff options
Diffstat (limited to 'OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h')
| -rw-r--r--[-rwxr-xr-x] | OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h | 272 |
1 files changed, 171 insertions, 101 deletions
diff --git a/OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h b/OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h index cd79566..bc1d491 100755..100644 --- a/OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h +++ b/OSX/Sparkle.framework/Versions/A/Headers/SUUpdater.h @@ -9,153 +9,223 @@ #ifndef SUUPDATER_H #define SUUPDATER_H +#if __has_feature(modules) +@import Cocoa; +#else +#import <Cocoa/Cocoa.h> +#endif +#import "SUExport.h" #import "SUVersionComparisonProtocol.h" #import "SUVersionDisplayProtocol.h" -@class SUUpdateDriver, SUAppcastItem, SUHost, SUAppcast; +@class SUAppcastItem, SUAppcast; + +@protocol SUUpdaterDelegate; + +/*! + The main API in Sparkle for controlling the update mechanism. -@interface SUUpdater : NSObject -{ -@private - NSTimer *checkTimer; - SUUpdateDriver *driver; + This class is used to configure the update paramters as well as manually + and automatically schedule and control checks for updates. + */ +SU_EXPORT @interface SUUpdater : NSObject - NSString *customUserAgentString; - SUHost *host; - IBOutlet id delegate; -} +@property (unsafe_unretained) IBOutlet id<SUUpdaterDelegate> delegate; +/*! + The shared updater for the main bundle. + + This is equivalent to passing [NSBundle mainBundle] to SUUpdater::updaterForBundle: + */ + (SUUpdater *)sharedUpdater; -+ (SUUpdater *)updaterForBundle:(NSBundle *)bundle; -- (id)initForBundle:(NSBundle *)bundle; -- (NSBundle *)hostBundle; +/*! + The shared updater for a specified bundle. + + If an updater has already been initialized for the provided bundle, that shared instance will be returned. + */ ++ (SUUpdater *)updaterForBundle:(NSBundle *)bundle; -- (void)setDelegate:(id)delegate; -- (id)delegate; +/*! + Designated initializer for SUUpdater. + + If an updater has already been initialized for the provided bundle, that shared instance will be returned. + */ +- (instancetype)initForBundle:(NSBundle *)bundle; -- (void)setAutomaticallyChecksForUpdates:(BOOL)automaticallyChecks; -- (BOOL)automaticallyChecksForUpdates; +/*! + Explicitly checks for updates and displays a progress dialog while doing so. -- (void)setUpdateCheckInterval:(NSTimeInterval)interval; -- (NSTimeInterval)updateCheckInterval; + This method is meant for a main menu item. + Connect any menu item to this action in Interface Builder, + and Sparkle will check for updates and report back its findings verbosely + when it is invoked. -- (void)setFeedURL:(NSURL *)feedURL; -- (NSURL *)feedURL; // *** MUST BE CALLED ON MAIN THREAD *** + This will find updates that the user has opted into skipping. + */ +- (IBAction)checkForUpdates:(id)sender; -- (void)setUserAgentString:(NSString *)userAgent; -- (NSString *)userAgentString; +/*! + The menu item validation used for the -checkForUpdates: action + */ +- (BOOL)validateMenuItem:(NSMenuItem *)menuItem; -- (void)setSendsSystemProfile:(BOOL)sendsSystemProfile; -- (BOOL)sendsSystemProfile; +/*! + Checks for updates, but does not display any UI unless an update is found. -- (void)setAutomaticallyDownloadsUpdates:(BOOL)automaticallyDownloadsUpdates; -- (BOOL)automaticallyDownloadsUpdates; + This is meant for programmatically initating a check for updates. That is, + it will display no UI unless it actually finds an update, in which case it + proceeds as usual. -// This IBAction is meant for a main menu item. Hook up any menu item to this action, -// and Sparkle will check for updates and report back its findings verbosely. -- (IBAction)checkForUpdates:(id)sender; + If automatic downloading of updates it turned on and allowed, however, + this will invoke that behavior, and if an update is found, it will be downloaded + in the background silently and will be prepped for installation. -// This kicks off an update meant to be programmatically initiated. That is, it will display no UI unless it actually finds an update, -// in which case it proceeds as usual. If the fully automated updating is turned on, however, this will invoke that behavior, and if an -// update is found, it will be downloaded and prepped for installation. + This will not find updates that the user has opted into skipping. + */ - (void)checkForUpdatesInBackground; -// Date of last update check. Returns nil if no check has been performed. -- (NSDate*)lastUpdateCheckDate; +/*! + A property indicating whether or not to check for updates automatically. -// This begins a "probing" check for updates which will not actually offer to update to that version. The delegate methods, though, -// (up to updater:didFindValidUpdate: and updaterDidNotFindUpdate:), are called, so you can use that information in your UI. -- (void)checkForUpdateInformation; + 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 BOOL automaticallyChecksForUpdates; -// Call this to appropriately schedule or cancel 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 NSTimer. -- (void)resetUpdateCycle; +/*! + A property indicating whether or not updates can be automatically downloaded in the background. -- (BOOL)updateInProgress; + Note that automatic downloading of updates can be disallowed by the developer + or by the user's system if silent updates cannot be done (eg: if they require authentication). + In this case, -automaticallyDownloadsUpdates will return NO regardless of how this property is set. -@end + Setting this property will persist in the host bundle's user defaults. + */ +@property BOOL automaticallyDownloadsUpdates; +/*! + A property indicating the current automatic update check interval. -// ----------------------------------------------------------------------------- -// SUUpdater Delegate: -// ----------------------------------------------------------------------------- + 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 NSTimeInterval updateCheckInterval; -@interface NSObject (SUUpdaterDelegateInformalProtocol) +/*! + Begins a "probing" check for updates which will not actually offer to + update to that version. -// Use this to keep Sparkle from popping up e.g. while your setup assistant is showing: -- (BOOL)updaterMayCheckForUpdates:(SUUpdater *)bundle; + However, the delegate methods + SUUpdaterDelegate::updater:didFindValidUpdate: and + SUUpdaterDelegate::updaterDidNotFindUpdate: will be called, + so you can use that information in your UI. -// This method allows you to add extra parameters to the appcast URL, potentially based on whether or not Sparkle will also be sending along the system profile. This method should return an array of dictionaries with keys: "key", "value", "displayKey", "displayValue", the latter two being specifically for display to the user. -- (NSArray *)feedParametersForUpdater:(SUUpdater *)updater sendingSystemProfile:(BOOL)sendingProfile; + Updates that have been skipped by the user will not be found. + */ +- (void)checkForUpdateInformation; -// Override this to dynamically specify the entire URL. -- (NSString*)feedURLStringForUpdater:(SUUpdater*)updater; +/*! + The URL of the appcast used to download update information. -// Use this to override the default behavior for Sparkle prompting the user about automatic update checks. -- (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:(SUUpdater *)bundle; + Setting this property will persist in the host bundle's user defaults. + If you don't want persistence, you may want to consider instead implementing + SUUpdaterDelegate::feedURLStringForUpdater: or SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile: -// Implement this if you want to do some special handling with the appcast once it finishes loading. -- (void)updater:(SUUpdater *)updater didFinishLoadingAppcast:(SUAppcast *)appcast; + This property must be called on the main thread. + */ +@property (copy) NSURL *feedURL; -// If you're using special logic or extensions in your appcast, implement this to use your own logic for finding -// a valid update, if any, in the given appcast. -- (SUAppcastItem *)bestValidUpdateInAppcast:(SUAppcast *)appcast forUpdater:(SUUpdater *)bundle; +/*! + The host bundle that is being updated. + */ +@property (readonly, strong) NSBundle *hostBundle; -// Sent when a valid update is found by the update driver. -- (void)updater:(SUUpdater *)updater didFindValidUpdate:(SUAppcastItem *)update; +/*! + The bundle this class (SUUpdater) is loaded into. + */ +@property (strong, readonly) NSBundle *sparkleBundle; -// Sent when a valid update is not found. -- (void)updaterDidNotFindUpdate:(SUUpdater *)update; +/*! + The user agent used when checking for updates. -// Sent immediately before installing the specified update. -- (void)updater:(SUUpdater *)updater willInstallUpdate:(SUAppcastItem *)update; + The default implementation can be overrided. + */ +@property (nonatomic, copy) NSString *userAgentString; -// Return YES to delay the relaunch until you do some processing; invoke the given NSInvocation to continue. -// This is not called if the user didn't relaunch on the previous update, in that case it will immediately -// restart. -- (BOOL)updater:(SUUpdater *)updater shouldPostponeRelaunchForUpdate:(SUAppcastItem *)update untilInvoking:(NSInvocation *)invocation; +/*! + The HTTP headers used when checking for updates. -// Some apps *can not* be relaunched in certain circumstances. They can use this method -// to prevent a relaunch "hard": -- (BOOL)updaterShouldRelaunchApplication:(SUUpdater *)updater; + The keys of this dictionary are HTTP header fields (NSString) and values are corresponding values (NSString) + */ +@property (copy) NSDictionary<NSString *, NSString *> *httpHeaders; -// Called immediately before relaunching. -- (void)updaterWillRelaunchApplication:(SUUpdater *)updater; +/*! + A property indicating whether or not the user's system profile information is sent when checking for updates. -// This method allows you to provide a custom version comparator. -// If you don't implement this method or return nil, the standard version comparator will be used. -- (id <SUVersionComparison>)versionComparatorForUpdater:(SUUpdater *)updater; + Setting this property will persist in the host bundle's user defaults. + */ +@property BOOL sendsSystemProfile; -// This method allows you to provide a custom version comparator. -// If you don't implement this method or return nil, the standard version displayer will be used. -- (id <SUVersionDisplay>)versionDisplayerForUpdater:(SUUpdater *)updater; +/*! + A property indicating the decryption password used for extracting updates shipped as Apple Disk Images (dmg) + */ +@property (nonatomic, copy) NSString *decryptionPassword; -// Returns the path which is used to relaunch the client after the update is installed. By default, the path of the host bundle. -- (NSString *)pathToRelaunchForUpdater:(SUUpdater *)updater; +/*! + This function ignores normal update schedule, ignores user preferences, + and interrupts users with an unwanted immediate app update. -// Called before and after, respectively, an updater shows a modal alert window, to give the host -// the opportunity to hide attached windows etc. that may get in the way: --(void) updaterWillShowModalAlert:(SUUpdater *)updater; --(void) updaterDidShowModalAlert:(SUUpdater *)updater; + WARNING: this function should not be used in regular apps. This function + is a user-unfriendly hack only for very special cases, like unstable + rapidly-changing beta builds that would not run correctly if they were + even one day out of date. -@end + Instead of this function you should set `SUAutomaticallyUpdate` to `YES`, + which will gracefully install updates when the app quits. + For UI-less/daemon apps that aren't usually quit, instead of this function, + you can use the delegate method + SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationInvocation: + to immediately start installation when an update was found. -// ----------------------------------------------------------------------------- -// Constants: -// ----------------------------------------------------------------------------- + A progress dialog is shown but the user will never be prompted to read the + release notes. -// Define some minimum intervals to avoid DOS-like checking attacks. These are in seconds. -#if defined(DEBUG) && DEBUG && 0 -#define SU_MIN_CHECK_INTERVAL 60 -#else -#define SU_MIN_CHECK_INTERVAL 60*60 -#endif + This function will cause update to be downloaded twice if automatic updates are + enabled. -#if defined(DEBUG) && DEBUG && 0 -#define SU_DEFAULT_CHECK_INTERVAL 60 -#else -#define SU_DEFAULT_CHECK_INTERVAL 60*60*24 -#endif + You may want to respond to the userDidCancelDownload delegate method in case + the user clicks the "Cancel" button while the update is downloading. + */ +- (void)installUpdatesIfAvailable; + +/*! + Returns the date of last update check. + + \returns \c nil if no check has been performed. + */ +@property (readonly, copy) 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 NSTimer. + */ +- (void)resetUpdateCycle; + +/*! + A property indicating whether or not an update is in progress. + + Note this property is not indicative of whether or not user initiated updates can be performed. + Use SUUpdater::validateMenuItem: for that instead. + */ +@property (readonly) BOOL updateInProgress; + +@end #endif |