The controller’s updater targets the application’s main bundle and uses Sparkle’s standard user interface.
+Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
+
The controller creates an SPUUpdater instance using a SPUStandardUserDriver and allows hooking up the check for updates action and handling menu item validation.
+It also allows hooking up the updater’s and user driver’s delegates.
+
+
If you need more control over what bundle you want to update, or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
Accessible property for the updater. Some properties on the updater can be binded via KVO
+
+
When instantiated from a nib, don’t perform update checks before the application has finished launching in a MainMenu nib (i.e applicationDidFinishLaunching:) or before the corresponding window/view controller has been loaded (i.e, windowDidLoad or viewDidLoad). The updater is not guaranteed to be started yet before these points.
Create a new SPUStandardUpdaterController programmatically allowing you to specify whether or not to start the updater immediately.
+
+
You can specify whether or not you want to start the updater immediately.
+If you do not start the updater, you must invoke -startUpdater at a later time to start it.
Starts the updater if it has not already been started.
+
+
You should only call this method yourself if you opted out of starting the updater on initialization.
+Hence, do not call this yourself if you are instantiating this controller from a nib.
+
+
This invokes -[SPUUpdater startUpdater:]. If the application is misconfigured with Sparkle, an error is logged and an alert is shown to the user (after a few seconds) to contact the developer.
+If you want more control over this behavior, you can create your own SPUUpdater instead of using SPUStandardUpdaterController.
Explicitly checks for updates and displays a progress dialog while doing so.
+
+
This method is meant for a main menu item.
+Connect any NSMenuItem to this action in Interface Builder or programmatically,
+and Sparkle will check for updates and report back its findings verbosely when it is invoked.
+
+
When the target/action of the menu item is set to this controller and this method,
+this controller also handles enabling/disabling the menu item by checking
+-[SPUUpdater canCheckForUpdates]
The application bundle that should be waited for termination and relaunched (unless overridden). Usually this can be the same as hostBundle. This may differ when updating a plug-in or other non-application bundle.
+
+
+
+
+
+
+ userDriver
+
+
+
+
+
The user driver that Sparkle uses for user update interaction.
This method first checks if Sparkle is configured properly. A valid feed URL should be set before this method is invoked.
+
+
If the configuration is valid, an update cycle is started in the next main runloop cycle.
+During this cycle, a permission prompt may be brought up (if needed) for checking if the user wants automatic update checking.
+Otherwise if automatic update checks are enabled, a scheduled update alert may be brought up if enough time has elapsed since the last check.
+See automaticallyChecksForUpdates for more information.
If the updater cannot be started (i.e, due to a configuration issue in the application), you may want to fall back appropriately.
+For example, the standard updater controller (SPUStandardUpdaterController) alerts the user that the app is misconfigured and to contact the developer.
Checks for updates, and displays progress while doing so if needed.
+
+
This is meant for users initiating a new update check or checking the current update progress.
+
+
If an update hasn’t started, the user may be shown that a new check for updates is occurring.
+If an update has already been downloaded or begun installing from a previous session, the user may be presented to install that update.
+If the user is already being presented with an update, that update will be shown to the user in active focus.
+
+
This will find updates that the user has previously opted into skipping.
+
+
See canCheckForUpdates property which can determine when this method may be invoked.
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.
A property indicating whether or not an update session is in progress.
+
+
An update session is in progress when the appcast is being downloaded, an update is being downloaded,
+an update is being shown, update permission is being requested, or the installer is being started.
+
+
An active session is when Sparkle’s fired scheduler is running.
+
+
Note an update session may not be running even though Sparkle’s installer (ran as a separate process) may be running,
+or even though the update has been downloaded but the installation has been deferred. In both of these cases, a new update session
+may be activated with the update resumed at a later point (automatically or manually).
+
+
See also:
+
+
+
canCheckForUpdates property which is more suited for menu item validation.
A property indicating whether or not to check for updates automatically.
+
+
By default, Sparkle asks users on second launch for permission if they want automatic update checks enabled
+and sets this property based on their response. If SUEnableAutomaticChecks is set in the Info.plist,
+this permission request is not performed however.
+
+
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
A property indicating the current automatic update check interval in seconds.
+
+
Setting this property will persist in the host bundle’s user defaults.
+For this reason, only set this property if you need dynamic behavior (eg user preferences).
+Otherwise prefer to set SUScheduledCheckInterval directly in your Info.plist.
+
+
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
A property indicating whether or not updates can be automatically downloaded in the background.
+
+
By default, updates are not automatically downloaded.
+
+
Note that the developer can disallow automatic downloading of updates from being enabled.
+In this case, this property will return NO regardless of how this property is set.
+
+
Setting this property will persist in the host bundle’s user defaults.
+For this reason, only set this property if you need dynamic behavior (eg user preferences).
+Otherwise prefer to set SUAutomaticallyUpdate directly in your Info.plist.
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.
This class can be used for reading certain updater settings.
+
+
It retrieves the settings by first looking into the host’s user defaults.
+If the setting is not found in there, then the host’s Info.plist file is looked at.
The appcast item describing an update in the application’s appcast feed.
+
+
An appcast item represents a single update item in the SUAppcast contained within the <item> element.
+
+
Every appcast item must have a versionString, and either a fileURL or an infoURL.
+All the remaining properties describing an update to the application are optional.
This download contains the actual update Sparkle will attempt to install.
+In cases where a download cannot be provided, an infoURL must be provided instead.
+
+
A file URL should have an accompanying contentLength provided.
+
+
This is extracted from the url attribute in the <enclosure> element.
This property is used as a fallback when the server doesn’t report the content length of the download.
+In that case, it is used to report progress of the downloading update to the user.
+
+
A warning is outputted if this property is not equal the server’s expected content length (if provided).
+
+
This is extracted from the length attribute in the <enclosure> element.
+It should be specified if a fileURL is provided.
This informational link is used to direct the user to learn more about an update they cannot download/install directly from within the application.
+The link should point to the product’s web page.
A description may be provided for inline/embedded release notes for new updates using <![CDATA[...]]>
+This is an alternative to providing a releaseNotesURL.
An update item may specify a custom channel name (such as beta) that can only be found by updaters that filter for that channel.
+If no channel is provided, the update item is assumed to be on the default channel.
+
+
This is extracted from the <sparkle:channel> element.
+Old applications must be using Sparkle 2 or later to interpret the channel element and to ignore unmatched channels.
application - indicates this is a regular application update.
+
package - indicates this is a guided package installer update.
+
interactive-package - indicates this is an interactive package installer update (deprecated; use “package” instead)
+
+
+
This is extracted from the sparkle:installationType attribute in the <enclosure> element.
+
+
If no installation type is provided in the enclosure, the installation type is inferred from the fileURL file extension instead.
+
+
If the file extension is pkg or mpkg, the installation type is package otherwise it is application
+
+
Hence, the installation type in the enclosure element only needs to be specified for package based updates distributed inside of a zip or other archive format.
+
+
Old applications must be using Sparkle 1.26 or later to support downloading bare package updates (pkg or mpkg) that are not additionally archived inside of a zip or other archive format.
The minimum bundle version string this update requires for automatically downloading and installing updates if provided.
+
+
If an application’s bundle version meets this version requirement, it can install the new update item in the background automatically.
+
+
Otherwise if the requirement is not met, the user is always prompted to install the update. In this case, the update is assumed to be a majorUpgrade.
+
+
If the update is a majorUpgrade and the update is skipped by the user, other future update alerts with the same minimumAutoupdateVersion will also be skipped.
+
+
This version string corresponds to the application’s CFBundleVersion
Indicates whether or not the update item is critical.
+
+
Critical updates are shown to the user more promptly. Sparkle’s standard user interface also does not allow them to be skipped.
+
+
This is determined and extracted from a top-level <sparkle:criticalUpdate> element or a sparkle:criticalUpdate element inside of a sparkle:tags element.
+
+
Old applications must be using Sparkle 2 or later to support the top-level <sparkle:criticalUpdate> element.
Specifies the operating system the download update is available for if provided.
+
+
If this property is not provided, then the supported operating system is assumed to be macOS.
+
+
Known potential values for this string are macos and windows
+
+
Sparkle on Mac ignores update items that are for other operating systems.
+This is only useful for sharing appcasts between Sparkle on Mac and Sparkle on other operating systems.
+
+
Use macOsUpdate property to test if this update item is for macOS.
+
+
This is extracted from the sparkle:os attribute in the <enclosure> element.
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dict__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dictfailureReason:(NSString*_Nullable__autoreleasing*_Nullable)error__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dictrelativeToURL:(NSURL*_Nullable)appcastURLfailureReason:(NSString*_Nullable__autoreleasing*_Nullable)error__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
This comparator is adapted from MacPAD, by Kevin Ballard.
+It’s “dumb” in that it does essentially string comparison,
+in components split by character type.
Compares two version strings through textual analysis.
+
+
These version strings should be in the format of x, x.y, or x.y.z where each component is a number.
+For example, valid version strings include “1.5.3”, “500”, or “4000.1”
+These versions that are compared correspond to the CFBundleVersion values of the updates.
The API in Sparkle for controlling the user interaction.
+
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle’s internal drivers tell
+an object that implements this protocol what actions to take and show to the user.
+
+
Every method in this protocol can be assumed to be called from the main thread.
Returns an object that formats version numbers for display to the user.
+If you don’t implement this method or return nil, the standard version formatter will be used.
Returns whether to allow Sparkle to check for updates.
+
+
For example, this may be used to prevent Sparkle from interrupting a setup assistant.
+Alternatively, you may want to consider starting the updater after eg: the setup assistant finishes
Returns the set of Sparkle channels the updater is allowed to find new updates from.
+
+
An appcast item can specify a channel the update is posted to. Without specifying a channel, the appcast item is posted to the default channel.
+For instance:
This example posts an update to the beta channel, so only updaters that are allowed to use the beta channel can find this update.
+
+
If the <sparkle:channel> element is not present, the update item is posted to the default channel and can be found by any updater.
+
+
You can pick any name you’d like for the channel. The valid characters for channel names are letters, numbers, dashes, underscores, and periods.
+
+
Note to use this feature, all app versions that your users may update from in your feed must use a version of Sparkle that supports this feature.
+This feature was added in Sparkle 2.
The set of channel names the updater is allowed to find new updates in. An empty set is the default behavior,
+ which means the updater will only look for updates in the default channel.
An array of system profile keys to include in the appcast URL’s query string. Elements must be one of the SUSystemProfiler*Key constants. Return nil for the default behavior and if you don’t want to be delegated this task.
SPUNoUpdateFoundReasonKey: This will provide the SPUNoUpdateFoundReason.
+For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
+
SPUNoUpdateFoundUserInitiatedKey: A boolean that indicates if a new update was not found when the user intitiated an update check manually.
If you want to treat certain updates as informational-only, consider supplying <sparkle:informationalUpdate> with a set of affected versions users are updating from.
+
+
+
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.
+
+
Do not base your logic by filtering out items with a minimum or maximum OS version or minimum autoupdate version
+because Sparkle already has logic for determining whether or not those items should be filtered out.
+
+
Also do not return a non-top level item from the appcast such as a delta item. Delta items will be ignored.
+Sparkle picks the delta item from your selection if the appropriate one is available.
+
+
This method will not be invoked with an appcast that has zero items. Pick the best item from the appcast.
+If an item is available that has the same version as the application or bundle to update, do not pick an item that is worse than that version.
+
+
This method may be called multiple times for different selections and filters. This method should be efficient.
Returns an object that compares version numbers to determine their arithmetic relation to each other.
+
+
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.
+
+
Note that the standard version comparator may be used during installation for preventing a downgrade,
+even if you provide a custom comparator here.
Called when an update is scheduled to be silently installed on quit after downloading the update automatically.
+
+
If the updater is given responsibility, it can later remind the user an update is available if they have not terminated the application for a long time.
+
+
Also if the updater is given responsibility and the update item is marked critical, the new update will be presented to the user immediately after.
+
+
Even if the immediateInstallHandler is not invoked, the installer will attempt to install the update on termination.
The update driver runs when checking for updates. This delegate method is called when that check is finished.
+
+
An update may be scheduled to be installed during the update cycle, or no updates may be found, or an available update may be dismissed or skipped (which is the same as no error).
+
+
If the error is nil, no error has occurred.
+
+
Some special possible values of error.code are:
+
+
+
SUNoUpdateError: No new update was found.
+
SUInstallationCanceledError: The user canceled installing the update when requested for authorization.
Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(BOOL)updaterMayCheckForUpdates:(SPUUpdater*)updater__deprecated_msg("Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.");
The API in Sparkle for controlling the user interaction.
+
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle’s internal drivers tell
+an object that implements this protocol what actions to take and show to the user.
+
+
Every method in this protocol can be assumed to be called from the main thread.
state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background.
+
+
Additionally, these properties on the appcastItem are of importance:
+
+
appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you’ll want to support this case.
+
+
appcastItem.majorUpgrade indicates if the update is a major or paid upgrade.
+
+
appcastItem.criticalUpdate indicates if the update is a critical update.
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update for the time being. The user may be reminded of the update at a later point.
+ If the state.stage is SPUUserUpdateStateDownloaded, the downloaded update is kept after dismissing until the next time an update is shown to the user.
+ If the state.stage is SPUUserUpdateStateInstalling, the installing update is also preserved after dismissing. In this state however, the update will also still be installed after the application is terminated.
+
+
A reply of SPUUserUpdateChoiceSkip skips this particular version and won’t notify the user again, unless they initiate an update check themselves.
+ If appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped.
+ If the state.stage is SPUUpdateStateInstalling, the installation is also canceled when the update is skipped.
The Appcast Item containing information that reflects the new update.
+
+
+
+
+
+
+ state
+
+
+
+
+
The current state of the user update.
+The state.stage values are:
+SPUUpdateStateNotDownloaded - Update has not been downloaded yet.
+SPUUpdateStateDownloaded - Update has already been downloaded but not started installing yet.
+SPUUpdateStateInstalling - Update has been downloaded and already started installing.
+
+
+
+
+
+
+ reply
+
+
+
+
+
A reply of SPUUserUpdateChoiceInstall begins or resumes downloading or installing the update.
+If the state.stage is SPUUserUpdateStateInstalling, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast “install and Relaunch”). Do not use this reply if appcastItem.informationOnlyUpdate is YES.
Show the user the release notes for the new update
+
+
Display the release notes to the user. This will be called after showing the new update.
+ This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file.
+ That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
Show the user that the new update’s release notes could not be downloaded
+
+
This will be called after showing the new update.
+ This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file.
+ That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
SPUNoUpdateFoundReasonKey: if available, this will provide the SUNoUpdateFoundReason. For example the reason could be because
+ the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
The error associated with why a new update was not found.
+There are various reasons a new update is unavailable and can’t be installed.
+This error object is populated with recovery and suggestion strings suitable to be shown in an alert.
+
+
+
+
+
+
+ acknowledgement
+
+
+
+
+
Acknowledge to the updater that no update found error was shown.
The expected content length of the new update being downloaded.
+An implementor should be able to handle if this value is invalid (more or less than actual content length downloaded).
+Additionally, this method may be called more than once for the same download in rare scenarios.
Show the user that the update finished downloading and started extracting
+
+
Sparkle uses this to show an indeterminate progress bar.
+
+
Note that an update can resume at this point after having been downloaded before,
+ so this may be called without any of the download callbacks being invoked prior.
Show the user that the update is ready to install & relaunch
+
+
Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed.
+ Note if the target application has already terminated, this method may not be invoked.
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.
+
+
A reply of SPUUserUpdateChoiceSkip cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.
A reply of SPUUserUpdateChoiceInstall installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.
Show or dismiss progress while a termination signal is being sent to the application from Sparkle’s installer
+
+
Terminating and relaunching the application (if requested to be relaunched) may happen quickly,
+ or it may take some time to perform the final installation, or the termination signal can be canceled or delayed by the application or user.
+
+
It is up to the implementor whether or not to decide to continue showing installation progress
+ or dismissing UI that won’t remain obscuring other parts of the user interface.
+
+
This will not be invoked if the application that is being updated is already terminated.
Show the user that the update installation finished
+
+
Let the user know that the update finished installing.
+
+
This will only be invoked if the updater process is still alive, which is typically not the case if
+ the updater’s lifetime is tied to the application it is updating. This implementation must not try to reference
+ the old bundle prior to the installation, which will no longer be around.
Show the user the current presented update or its progress in utmost focus
+
+
The user wishes to check for updates while the user is being shown update progress.
+ Bring whatever is on screen to frontmost focus (permission request, update information, downloading or extraction status, choice to install update, etc).
Stop and tear down everything.
+ Dismiss all update windows, alerts, progress, etc from the user.
+ Basically, stop everything that could have been started. Sparkle may invoke this when aborting or finishing an update.
Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(void)dismissUserInitiatedUpdateCheck__deprecated_msg("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.");
15// Returns a path to a suitable cache directory to create specifically for Sparkle
+
16// Intermediate directories to this path may not exist yet
+
17// This path may depend on the type of running process,
+
18// such that sandboxed vs non-sandboxed processes could yield different paths
+
19// The caller should create a subdirectory from the path that is returned here so they don't have files that
+
20// conflict with other callers. Once that subdirectory name is decided, the caller can remove old items inside it (using +removeOldItemsInDirectory:)
+
21// and then create a unique temporary directory inside it (using +createUniqueDirectoryInDirectory:)
15// This protocol describes an update driver that drives updates
+
16// An update driver may have multiple levels of other controller components (eg: basic update driver, core based update driver, ui based update driver, appcast driver, etc)
+
17// The update driver and the components the driver has communicates via parameter passing and delegation..
+
18// The old Sparkle architecture communicated via subclassing and method overriding, but this lead to bugs due to high coupling, and complexity of not being aware of methods being executed.
+
19// The newer architecture is still complex but should be more reliable to maintain and extend.
277 - (void)dismissUserInitiatedUpdateCheck __deprecated_msg("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.");;
74 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
+
75 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
+
76 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict relativeToURL:(NSURL * _Nullable)appcastURL failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Initializes with data from a dictionary provided by the RSS class and state resolver.
+
This initializer method is intended to be marked "private" and discouraged from public usage. This method is available however. Talk to us to describe your use case and if you need to construct appcast items yourself.
The controller’s updater targets the application’s main bundle and uses Sparkle’s standard user interface.
+Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
+
The controller creates an SPUUpdater instance using a SPUStandardUserDriver and allows hooking up the check for updates action and handling menu item validation.
+It also allows hooking up the updater’s and user driver’s delegates.
+
+
If you need more control over what bundle you want to update, or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
This class can be used for reading certain updater settings.
+
+
It retrieves the settings by first looking into the host’s user defaults.
+If the setting is not found in there, then the host’s Info.plist file is looked at.
The appcast item describing an update in the application’s appcast feed.
+
+
An appcast item represents a single update item in the SUAppcast contained within the <item> element.
+
+
Every appcast item must have a versionString, and either a fileURL or an infoURL.
+All the remaining properties describing an update to the application are optional.
This comparator is adapted from MacPAD, by Kevin Ballard.
+It’s “dumb” in that it does essentially string comparison,
+in components split by character type.
The controller’s updater targets the application’s main bundle and uses Sparkle’s standard user interface.
+Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
+
The controller creates an SPUUpdater instance using a SPUStandardUserDriver and allows hooking up the check for updates action and handling menu item validation.
+It also allows hooking up the updater’s and user driver’s delegates.
+
+
If you need more control over what bundle you want to update, or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
Accessible property for the updater. Some properties on the updater can be binded via KVO
+
+
When instantiated from a nib, don’t perform update checks before the application has finished launching in a MainMenu nib (i.e applicationDidFinishLaunching:) or before the corresponding window/view controller has been loaded (i.e, windowDidLoad or viewDidLoad). The updater is not guaranteed to be started yet before these points.
Create a new SPUStandardUpdaterController programmatically allowing you to specify whether or not to start the updater immediately.
+
+
You can specify whether or not you want to start the updater immediately.
+If you do not start the updater, you must invoke -startUpdater at a later time to start it.
Starts the updater if it has not already been started.
+
+
You should only call this method yourself if you opted out of starting the updater on initialization.
+Hence, do not call this yourself if you are instantiating this controller from a nib.
+
+
This invokes -[SPUUpdater startUpdater:]. If the application is misconfigured with Sparkle, an error is logged and an alert is shown to the user (after a few seconds) to contact the developer.
+If you want more control over this behavior, you can create your own SPUUpdater instead of using SPUStandardUpdaterController.
Explicitly checks for updates and displays a progress dialog while doing so.
+
+
This method is meant for a main menu item.
+Connect any NSMenuItem to this action in Interface Builder or programmatically,
+and Sparkle will check for updates and report back its findings verbosely when it is invoked.
+
+
When the target/action of the menu item is set to this controller and this method,
+this controller also handles enabling/disabling the menu item by checking
+-[SPUUpdater canCheckForUpdates]
The application bundle that should be waited for termination and relaunched (unless overridden). Usually this can be the same as hostBundle. This may differ when updating a plug-in or other non-application bundle.
+
+
+
+
+
+
+ userDriver
+
+
+
+
+
The user driver that Sparkle uses for user update interaction.
This method first checks if Sparkle is configured properly. A valid feed URL should be set before this method is invoked.
+
+
If the configuration is valid, an update cycle is started in the next main runloop cycle.
+During this cycle, a permission prompt may be brought up (if needed) for checking if the user wants automatic update checking.
+Otherwise if automatic update checks are enabled, a scheduled update alert may be brought up if enough time has elapsed since the last check.
+See automaticallyChecksForUpdates for more information.
If the updater cannot be started (i.e, due to a configuration issue in the application), you may want to fall back appropriately.
+For example, the standard updater controller (SPUStandardUpdaterController) alerts the user that the app is misconfigured and to contact the developer.
Checks for updates, and displays progress while doing so if needed.
+
+
This is meant for users initiating a new update check or checking the current update progress.
+
+
If an update hasn’t started, the user may be shown that a new check for updates is occurring.
+If an update has already been downloaded or begun installing from a previous session, the user may be presented to install that update.
+If the user is already being presented with an update, that update will be shown to the user in active focus.
+
+
This will find updates that the user has previously opted into skipping.
+
+
See canCheckForUpdates property which can determine when this method may be invoked.
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.
A property indicating whether or not an update session is in progress.
+
+
An update session is in progress when the appcast is being downloaded, an update is being downloaded,
+an update is being shown, update permission is being requested, or the installer is being started.
+
+
An active session is when Sparkle’s fired scheduler is running.
+
+
Note an update session may not be running even though Sparkle’s installer (ran as a separate process) may be running,
+or even though the update has been downloaded but the installation has been deferred. In both of these cases, a new update session
+may be activated with the update resumed at a later point (automatically or manually).
+
+
See also:
+
+
+
canCheckForUpdates property which is more suited for menu item validation.
A property indicating whether or not to check for updates automatically.
+
+
By default, Sparkle asks users on second launch for permission if they want automatic update checks enabled
+and sets this property based on their response. If SUEnableAutomaticChecks is set in the Info.plist,
+this permission request is not performed however.
+
+
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
A property indicating the current automatic update check interval in seconds.
+
+
Setting this property will persist in the host bundle’s user defaults.
+For this reason, only set this property if you need dynamic behavior (eg user preferences).
+Otherwise prefer to set SUScheduledCheckInterval directly in your Info.plist.
+
+
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
A property indicating whether or not updates can be automatically downloaded in the background.
+
+
By default, updates are not automatically downloaded.
+
+
Note that the developer can disallow automatic downloading of updates from being enabled.
+In this case, this property will return NO regardless of how this property is set.
+
+
Setting this property will persist in the host bundle’s user defaults.
+For this reason, only set this property if you need dynamic behavior (eg user preferences).
+Otherwise prefer to set SUAutomaticallyUpdate directly in your Info.plist.
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.
This class can be used for reading certain updater settings.
+
+
It retrieves the settings by first looking into the host’s user defaults.
+If the setting is not found in there, then the host’s Info.plist file is looked at.
The appcast item describing an update in the application’s appcast feed.
+
+
An appcast item represents a single update item in the SUAppcast contained within the <item> element.
+
+
Every appcast item must have a versionString, and either a fileURL or an infoURL.
+All the remaining properties describing an update to the application are optional.
This download contains the actual update Sparkle will attempt to install.
+In cases where a download cannot be provided, an infoURL must be provided instead.
+
+
A file URL should have an accompanying contentLength provided.
+
+
This is extracted from the url attribute in the <enclosure> element.
This property is used as a fallback when the server doesn’t report the content length of the download.
+In that case, it is used to report progress of the downloading update to the user.
+
+
A warning is outputted if this property is not equal the server’s expected content length (if provided).
+
+
This is extracted from the length attribute in the <enclosure> element.
+It should be specified if a fileURL is provided.
This informational link is used to direct the user to learn more about an update they cannot download/install directly from within the application.
+The link should point to the product’s web page.
A description may be provided for inline/embedded release notes for new updates using <![CDATA[...]]>
+This is an alternative to providing a releaseNotesURL.
An update item may specify a custom channel name (such as beta) that can only be found by updaters that filter for that channel.
+If no channel is provided, the update item is assumed to be on the default channel.
+
+
This is extracted from the <sparkle:channel> element.
+Old applications must be using Sparkle 2 or later to interpret the channel element and to ignore unmatched channels.
application - indicates this is a regular application update.
+
package - indicates this is a guided package installer update.
+
interactive-package - indicates this is an interactive package installer update (deprecated; use “package” instead)
+
+
+
This is extracted from the sparkle:installationType attribute in the <enclosure> element.
+
+
If no installation type is provided in the enclosure, the installation type is inferred from the fileURL file extension instead.
+
+
If the file extension is pkg or mpkg, the installation type is package otherwise it is application
+
+
Hence, the installation type in the enclosure element only needs to be specified for package based updates distributed inside of a zip or other archive format.
+
+
Old applications must be using Sparkle 1.26 or later to support downloading bare package updates (pkg or mpkg) that are not additionally archived inside of a zip or other archive format.
The minimum bundle version string this update requires for automatically downloading and installing updates if provided.
+
+
If an application’s bundle version meets this version requirement, it can install the new update item in the background automatically.
+
+
Otherwise if the requirement is not met, the user is always prompted to install the update. In this case, the update is assumed to be a majorUpgrade.
+
+
If the update is a majorUpgrade and the update is skipped by the user, other future update alerts with the same minimumAutoupdateVersion will also be skipped.
+
+
This version string corresponds to the application’s CFBundleVersion
Indicates whether or not the update item is critical.
+
+
Critical updates are shown to the user more promptly. Sparkle’s standard user interface also does not allow them to be skipped.
+
+
This is determined and extracted from a top-level <sparkle:criticalUpdate> element or a sparkle:criticalUpdate element inside of a sparkle:tags element.
+
+
Old applications must be using Sparkle 2 or later to support the top-level <sparkle:criticalUpdate> element.
Specifies the operating system the download update is available for if provided.
+
+
If this property is not provided, then the supported operating system is assumed to be macOS.
+
+
Known potential values for this string are macos and windows
+
+
Sparkle on Mac ignores update items that are for other operating systems.
+This is only useful for sharing appcasts between Sparkle on Mac and Sparkle on other operating systems.
+
+
Use macOsUpdate property to test if this update item is for macOS.
+
+
This is extracted from the sparkle:os attribute in the <enclosure> element.
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dict__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dictfailureReason:(NSString*_Nullable__autoreleasing*_Nullable)error__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(nullableinstancetype)initWithDictionary:(NSDictionary*)dictrelativeToURL:(NSURL*_Nullable)appcastURLfailureReason:(NSString*_Nullable__autoreleasing*_Nullable)error__deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
This comparator is adapted from MacPAD, by Kevin Ballard.
+It’s “dumb” in that it does essentially string comparison,
+in components split by character type.
Compares two version strings through textual analysis.
+
+
These version strings should be in the format of x, x.y, or x.y.z where each component is a number.
+For example, valid version strings include “1.5.3”, “500”, or “4000.1”
+These versions that are compared correspond to the CFBundleVersion values of the updates.
The API in Sparkle for controlling the user interaction.
+
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle’s internal drivers tell
+an object that implements this protocol what actions to take and show to the user.
+
+
Every method in this protocol can be assumed to be called from the main thread.
Returns an object that formats version numbers for display to the user.
+If you don’t implement this method or return nil, the standard version formatter will be used.
Returns whether to allow Sparkle to check for updates.
+
+
For example, this may be used to prevent Sparkle from interrupting a setup assistant.
+Alternatively, you may want to consider starting the updater after eg: the setup assistant finishes
Returns the set of Sparkle channels the updater is allowed to find new updates from.
+
+
An appcast item can specify a channel the update is posted to. Without specifying a channel, the appcast item is posted to the default channel.
+For instance:
This example posts an update to the beta channel, so only updaters that are allowed to use the beta channel can find this update.
+
+
If the <sparkle:channel> element is not present, the update item is posted to the default channel and can be found by any updater.
+
+
You can pick any name you’d like for the channel. The valid characters for channel names are letters, numbers, dashes, underscores, and periods.
+
+
Note to use this feature, all app versions that your users may update from in your feed must use a version of Sparkle that supports this feature.
+This feature was added in Sparkle 2.
The set of channel names the updater is allowed to find new updates in. An empty set is the default behavior,
+ which means the updater will only look for updates in the default channel.
An array of system profile keys to include in the appcast URL’s query string. Elements must be one of the SUSystemProfiler*Key constants. Return nil for the default behavior and if you don’t want to be delegated this task.
SPUNoUpdateFoundReasonKey: This will provide the SPUNoUpdateFoundReason.
+For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
+
SPUNoUpdateFoundUserInitiatedKey: A boolean that indicates if a new update was not found when the user intitiated an update check manually.
If you want to treat certain updates as informational-only, consider supplying <sparkle:informationalUpdate> with a set of affected versions users are updating from.
+
+
+
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.
+
+
Do not base your logic by filtering out items with a minimum or maximum OS version or minimum autoupdate version
+because Sparkle already has logic for determining whether or not those items should be filtered out.
+
+
Also do not return a non-top level item from the appcast such as a delta item. Delta items will be ignored.
+Sparkle picks the delta item from your selection if the appropriate one is available.
+
+
This method will not be invoked with an appcast that has zero items. Pick the best item from the appcast.
+If an item is available that has the same version as the application or bundle to update, do not pick an item that is worse than that version.
+
+
This method may be called multiple times for different selections and filters. This method should be efficient.
Returns an object that compares version numbers to determine their arithmetic relation to each other.
+
+
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.
+
+
Note that the standard version comparator may be used during installation for preventing a downgrade,
+even if you provide a custom comparator here.
Called when an update is scheduled to be silently installed on quit after downloading the update automatically.
+
+
If the updater is given responsibility, it can later remind the user an update is available if they have not terminated the application for a long time.
+
+
Also if the updater is given responsibility and the update item is marked critical, the new update will be presented to the user immediately after.
+
+
Even if the immediateInstallHandler is not invoked, the installer will attempt to install the update on termination.
The update driver runs when checking for updates. This delegate method is called when that check is finished.
+
+
An update may be scheduled to be installed during the update cycle, or no updates may be found, or an available update may be dismissed or skipped (which is the same as no error).
+
+
If the error is nil, no error has occurred.
+
+
Some special possible values of error.code are:
+
+
+
SUNoUpdateError: No new update was found.
+
SUInstallationCanceledError: The user canceled installing the update when requested for authorization.
Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(BOOL)updaterMayCheckForUpdates:(SPUUpdater*)updater__deprecated_msg("Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.");
The API in Sparkle for controlling the user interaction.
+
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle’s internal drivers tell
+an object that implements this protocol what actions to take and show to the user.
+
+
Every method in this protocol can be assumed to be called from the main thread.
state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background.
+
+
Additionally, these properties on the appcastItem are of importance:
+
+
appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you’ll want to support this case.
+
+
appcastItem.majorUpgrade indicates if the update is a major or paid upgrade.
+
+
appcastItem.criticalUpdate indicates if the update is a critical update.
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update for the time being. The user may be reminded of the update at a later point.
+ If the state.stage is SPUUserUpdateStateDownloaded, the downloaded update is kept after dismissing until the next time an update is shown to the user.
+ If the state.stage is SPUUserUpdateStateInstalling, the installing update is also preserved after dismissing. In this state however, the update will also still be installed after the application is terminated.
+
+
A reply of SPUUserUpdateChoiceSkip skips this particular version and won’t notify the user again, unless they initiate an update check themselves.
+ If appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped.
+ If the state.stage is SPUUpdateStateInstalling, the installation is also canceled when the update is skipped.
The Appcast Item containing information that reflects the new update.
+
+
+
+
+
+
+ state
+
+
+
+
+
The current state of the user update.
+The state.stage values are:
+SPUUpdateStateNotDownloaded - Update has not been downloaded yet.
+SPUUpdateStateDownloaded - Update has already been downloaded but not started installing yet.
+SPUUpdateStateInstalling - Update has been downloaded and already started installing.
+
+
+
+
+
+
+ reply
+
+
+
+
+
A reply of SPUUserUpdateChoiceInstall begins or resumes downloading or installing the update.
+If the state.stage is SPUUserUpdateStateInstalling, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast “install and Relaunch”). Do not use this reply if appcastItem.informationOnlyUpdate is YES.
Show the user the release notes for the new update
+
+
Display the release notes to the user. This will be called after showing the new update.
+ This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file.
+ That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
Show the user that the new update’s release notes could not be downloaded
+
+
This will be called after showing the new update.
+ This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file.
+ That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
SPUNoUpdateFoundReasonKey: if available, this will provide the SUNoUpdateFoundReason. For example the reason could be because
+ the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
The error associated with why a new update was not found.
+There are various reasons a new update is unavailable and can’t be installed.
+This error object is populated with recovery and suggestion strings suitable to be shown in an alert.
+
+
+
+
+
+
+ acknowledgement
+
+
+
+
+
Acknowledge to the updater that no update found error was shown.
The expected content length of the new update being downloaded.
+An implementor should be able to handle if this value is invalid (more or less than actual content length downloaded).
+Additionally, this method may be called more than once for the same download in rare scenarios.
Show the user that the update finished downloading and started extracting
+
+
Sparkle uses this to show an indeterminate progress bar.
+
+
Note that an update can resume at this point after having been downloaded before,
+ so this may be called without any of the download callbacks being invoked prior.
Show the user that the update is ready to install & relaunch
+
+
Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed.
+ Note if the target application has already terminated, this method may not be invoked.
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.
+
+
A reply of SPUUserUpdateChoiceSkip cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.
A reply of SPUUserUpdateChoiceInstall installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.
Show or dismiss progress while a termination signal is being sent to the application from Sparkle’s installer
+
+
Terminating and relaunching the application (if requested to be relaunched) may happen quickly,
+ or it may take some time to perform the final installation, or the termination signal can be canceled or delayed by the application or user.
+
+
It is up to the implementor whether or not to decide to continue showing installation progress
+ or dismissing UI that won’t remain obscuring other parts of the user interface.
+
+
This will not be invoked if the application that is being updated is already terminated.
Show the user that the update installation finished
+
+
Let the user know that the update finished installing.
+
+
This will only be invoked if the updater process is still alive, which is typically not the case if
+ the updater’s lifetime is tied to the application it is updating. This implementation must not try to reference
+ the old bundle prior to the installation, which will no longer be around.
Show the user the current presented update or its progress in utmost focus
+
+
The user wishes to check for updates while the user is being shown update progress.
+ Bring whatever is on screen to frontmost focus (permission request, update information, downloading or extraction status, choice to install update, etc).
Stop and tear down everything.
+ Dismiss all update windows, alerts, progress, etc from the user.
+ Basically, stop everything that could have been started. Sparkle may invoke this when aborting or finishing an update.
Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.
+
+
+
+
Undocumented
+
+
+
+
Declaration
+
+
Objective-C
+
-(void)dismissUserInitiatedUpdateCheck__deprecated_msg("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.");
15// Returns a path to a suitable cache directory to create specifically for Sparkle
+
16// Intermediate directories to this path may not exist yet
+
17// This path may depend on the type of running process,
+
18// such that sandboxed vs non-sandboxed processes could yield different paths
+
19// The caller should create a subdirectory from the path that is returned here so they don't have files that
+
20// conflict with other callers. Once that subdirectory name is decided, the caller can remove old items inside it (using +removeOldItemsInDirectory:)
+
21// and then create a unique temporary directory inside it (using +createUniqueDirectoryInDirectory:)
15// This protocol describes an update driver that drives updates
+
16// An update driver may have multiple levels of other controller components (eg: basic update driver, core based update driver, ui based update driver, appcast driver, etc)
+
17// The update driver and the components the driver has communicates via parameter passing and delegation..
+
18// The old Sparkle architecture communicated via subclassing and method overriding, but this lead to bugs due to high coupling, and complexity of not being aware of methods being executed.
+
19// The newer architecture is still complex but should be more reliable to maintain and extend.
277 - (void)dismissUserInitiatedUpdateCheck __deprecated_msg("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.");;
74 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
+
75 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
+
76 - (nullable instancetype)initWithDictionary:(NSDictionary *)dict relativeToURL:(NSURL * _Nullable)appcastURL failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");
Initializes with data from a dictionary provided by the RSS class and state resolver.
+
This initializer method is intended to be marked "private" and discouraged from public usage. This method is available however. Talk to us to describe your use case and if you need to construct appcast items yourself.
The controller’s updater targets the application’s main bundle and uses Sparkle’s standard user interface.
+Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
+
The controller creates an SPUUpdater instance using a SPUStandardUserDriver and allows hooking up the check for updates action and handling menu item validation.
+It also allows hooking up the updater’s and user driver’s delegates.
+
+
If you need more control over what bundle you want to update, or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
This class can be used for reading certain updater settings.
+
+
It retrieves the settings by first looking into the host’s user defaults.
+If the setting is not found in there, then the host’s Info.plist file is looked at.
The appcast item describing an update in the application’s appcast feed.
+
+
An appcast item represents a single update item in the SUAppcast contained within the <item> element.
+
+
Every appcast item must have a versionString, and either a fileURL or an infoURL.
+All the remaining properties describing an update to the application are optional.
This comparator is adapted from MacPAD, by Kevin Ballard.
+It’s “dumb” in that it does essentially string comparison,
+in components split by character type.
initWithMajorUpgrade:criticalUpdate:informationalUpdate:minimumOperatingSystemVersionIsOK:maximumOperatingSystemVersionIsOK: (defined in SPUAppcastItemState)
resolveStateWithInformationalUpdateVersions:minimumOperatingSystemVersion:maximumOperatingSystemVersion:minimumAutoupdateVersion:criticalUpdateDictionary: (defined in SPUAppcastItemStateResolver)
Accessible property for the updater's user driver.
+
+
+
Detailed Description
+
A controller class that instantiates a SPUUpdater and allows binding UI to it.
+
This class can be instantiated in a nib or created programatically using initWithUpdaterDelegate:userDriverDelegate: or initWithStartingUpdater:updaterDelegate:userDriverDelegate:.
+
The controller's updater targets the application's main bundle and uses Sparkle's standard user interface. Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
The controller creates an SPUUpdater instance and allows hooking up the check for updates action and handling menu item validation. It also allows hooking up the updater's and user driver's delegates.
+
If you need more control over what bundle you want to update or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
Explicitly checks for updates and displays a progress dialog while doing so.
+
This method is meant for a main menu item. Connect any NSMenuItem to this action in Interface Builder or programmatically, and Sparkle will check for updates and report back its findings verbosely when it is invoked.
+
When the target/action of the menu item is set to this controller and this method, this controller also handles enabling/disabling the menu item by checking -[SPUUpdater canCheckForUpdates]
+
This action checks updates by invoking -[SPUUpdater checkForUpdates]
Create a new SPUStandardUpdaterController programmatically allowing you to specify whether or not to start the updater immediately.
+
You can specify whether or not you want to start the updater immediately. If you do not start the updater, you must invoke -[SPUStandardUpdaterController startUpdater] at a later time to start it.
You cannot call this initializer directly. You must instantiate a SPUStandardUpdaterController inside of a nib (typically the MainMenu nib) to use it.
+
To create a SPUStandardUpdaterController programatically, use initWithUpdaterDelegate:userDriverDelegate: or initWithStartingUpdater:updaterDelegate:userDriverDelegate: instead.
Starts the updater if it has not already been started.
+
You should only call this method yourself if you opted out of starting the updater on initialization. Hence, do not call this yourself if you are instantiating this controller from a nib.
+
This invokes -[SPUUpdater startUpdater:]. If the application is misconfigured with Sparkle, an error is logged and an alert is shown to the user (after a few seconds) to contact the developer. If you want more control over this behavior, you can create your own SPUUpdater instead.
Some properties on the updater can be binded via KVO
+
When instantiated from a nib, don't perform update checks before the application has finished launching in a MainMenu nib (i.e applicationDidFinishLaunching:) or before the corresponding window/view controller has been loaded (i.e, windowDidLoad or viewDidLoad). The updater is not guaranteed to be started yet before these points.
Checks for updates, and displays progress while doing so if needed.
+
This is meant for users initiating a new update check or checking the current update progress.
+
If an update hasn't started, the user may be shown that a new check for updates is occurring. If an update has already been downloaded or begun installing, the user may be presented to install that update. If the user is already being presented with an update, that update will be shown to the user in active focus.
+
This will find updates that the user has previously opted into skipping.
+
See canCheckForUpdates property which can determine if this method may be invoked.
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.
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.
The bundle that should be targetted for updating. This must not be nil.
+
applicationBundle
The application bundle that should be waited for termination and relaunched (unless overridden). Usually this can be the same as hostBundle. This may differ when updating a plug-in or other non-application bundle.
+
userDriver
The user driver that Sparkle uses for user update interaction
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:]
+
Passing nil will remove any feed URL that has been set in the host bundle's user defaults.
+
For beta updates, you may consider migrating to -[SPUUpdaterDelegate allowedChannelsForUpdater:] in the future.
+
This method must be called on the main thread; calls from background threads will have no effect.
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, an update cycle is started in the next main runloop cycle. During this cycle, a permission prompt may be brought up (if needed) for checking if the user wants automatic update checking. Otherwise if automatic update checks are enabled, a scheduled update alert may be brought up if enough time has elapsed since the last check.
+
After starting the updater and before the next runloop cycle, one of -checkForUpdates, -checkForUpdatesInBackground, or -checkForUpdateInformation can be invoked. This may be useful if you want to check for updates immediately or without showing a permission prompt.
+
If the updater cannot be started (i.e, due to a configuration issue in the application), you may want to fall back appropriately. For example, the standard updater controller (SPUStandardUpdaterController) alerts the user that the app is misconfigured and to contact the developer.
+
This must be called on the main thread.
+
Parameters
+
+
error
The error that is populated if this method fails. Pass NULL if not interested in the error information.
+
+
+
+
Returns
YES if the updater started otherwise NO with a populated error
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
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.
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.
A property indicating whether or not an update session is in progress.
+
An update session is in progress when the appcast is being downloaded, an update is being downloaded, an update is being shown, update permission is being requested, or the installer is being started. An active session is when Sparkle's fired scheduler is running.
+
Note an update session may be inactive even though Sparkle's installer (ran as a separate process) may be running, or even though the update has been downloaded but the installation has been deferred. In both of these cases, a new update session may be activated with the update resumed at a later point (automatically or manually).
+
See also canCheckForUpdates property which is more suited for menu item validation.
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
Indicates whether or not anonymous system profile information is sent when checking for updates.
+
+
+
Detailed Description
+
This class can be used for reading certain updater settings.
+
It retrieves the settings by first looking into the host's user defaults. If the setting is not found in there, then the host's Info.plist file is looked at.
Initializes with data from a dictionary provided by the RSS class and state resolver.
+
This initializer method is intended to be marked "private" and discouraged from public usage. This method is available however. Talk to us to describe your use case and if you need to construct appcast items yourself.
A class used for performing file operations more suitable than NSFileManager for performing installation work. All operations on this class may be used on thread other than the main thread. This class provides just basic file operations and stays away from including much application-level logic.
Changes the owner and group IDs of an item at a specified target URL to match another URL
Parameters
+
+
targetURL
A URL pointing to the target item whose owner and group IDs to alter. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
matchURL
A URL pointing to the item whose owner and group IDs will be used for changing on the targetURL. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's owner and group IDs have changed to match the origin's ones, otherwise NO along with a populated error object
+
If the owner and group IDs match on the root items of targetURL and matchURL, this method stops and assumes that nothing needs to be done. Otherwise this method recursively changes the IDs if the target is a directory. If an item in the directory is encountered that is unable to be changed, then this method stops and returns NO. While this method will try to change the group ID, being unable to change the group ID does not result in a failure if the owner ID can be changed or matched.
A URL pointing to the item to move. The item at this URL must exist.
+
destinationURL
A URL pointing to the destination the item will be moved at. An item must not already exist at this URL.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was copied successfully, otherwise NO along with a populated error object
A URL pointing to the directory to create. The item at this URL must not exist, and the parent directory of this URL must already exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was created successfully, otherwise NO along with a populated error object
Creates a temporary directory on the same volume as a provided URL
Parameters
+
+
preferredName
A name that may be used when creating the temporary directory. Note that in the uncothirdStageErrormmon case this name is used, the temporary directory will be created inside the directory pointed by appropriateURL
+
appropriateURL
A URL to a directory that resides on the volume that the temporary directory will be created on. In the uncommon case, the temporary directory may be created inside this directory.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
A URL pointing to the newly created temporary directory, or nil with a populated error object if an error occurs.
+
When moving an item from a source to a destination, it is desirable to create a temporary intermediate destination on the same volume as the destination to ensure that the item will be moved, and not copied, from the intermediate point to the final destination. This ensures file atomicity.
A URL pointing to the item to move. The item at this URL must exist.
+
destinationURL
A URL pointing to the destination the item will be moved at. An item must not already exist at this URL.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was moved successfully, otherwise NO along with a populated error object
+
If sourceURL and destinationURL reside on the same volume, this operation will be an atomic move operation. Otherwise this will be equivalent to a copy & remove which will be a nonatomic operation.
Releases Apple's quarantine extended attribute from the item at the specified root URL
Parameters
+
+
rootURL
A URL pointing to the item to release from Apple's quarantine. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if all the items at the target could be released from quarantine, otherwise NO if any items couldn't along with a populated error object
+
This method removes quarantine attributes from an item, ideally an application, so that when the user launches a new application themselves, they don't have to witness the system dialog alerting them that they downloaded an application from the internet and asking if they want to continue. Note that this may not exactly mimic the system behavior when a user opens an application for the first time (i.e, the xattr isn't deleted), but this should be sufficient enough for our purposes.
+
This method may return NO even if some items do get released from quarantine if the target URL is pointing to a directory. Thus if an item cannot be released from quarantine, this method still continues on to the next enumerated item.
A URL pointing to the item to remove. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was removed successfully, otherwise NO along with a populated error object
Replaces an original item with a new item atomically.
Parameters
+
+
originalItemURL
A URL pointing to the original item to replace. The item at this URL must exist.
+
newItemURL
A URL pointing to the new item that will replace the original item.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the original item was replaced with the new item successfully, otherwise NO along with a populated error object
+
originalItemURL and newItemURL must reside on the same volume. If the operation succeeds, this will be be an atomic operation. Otherwise on failure you may need to re-try using move operations. This operation will fail on non-apfs volumes or volumes that don't support rename swapping. Both originalItemURL and newItemURL must exist.
Updates the access time of an item at a specified root URL to the current time
Parameters
+
+
targetURL
A URL pointing to the target item whose access time to update to the current time. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's access times have been updated, otherwise NO along with a populated error object
+
This method updates the access time of an item to the current time, ideal for letting the system know not to remove a file or directory when placing it at a temporary directory.
Updates the modification and access time of an item at a specified target URL to the current time
Parameters
+
+
targetURL
A URL pointing to the target item whose modification and access time to update. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's modification and access times have been updated, otherwise NO along with a populated error object
+
This method updates the modification and access time of an item to the current time, ideal for letting the system know we installed a new file or application.
+
This is not an atomic operation.
+
+
+
+The documentation for this class was generated from the following files:
Returns a singleton instance of the comparator. More...
+
+
+
Detailed Description
+
Sparkle's default version comparator.
+
This comparator is adapted from MacPAD, by Kevin Ballard. It's "dumb" in that it does essentially string comparison, in components split by character type.
');
+ }
+ }
+ $('#main-menu').smartmenus();
+}
+/* @license-end */
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/menudata.js b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/menudata.js
new file mode 100644
index 0000000..7eff031
--- /dev/null
+++ b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/menudata.js
@@ -0,0 +1,63 @@
+/*
+ @licstart The following is the entire license notice for the JavaScript code in this file.
+
+ The MIT License (MIT)
+
+ Copyright (C) 1997-2020 by Dimitri van Heesch
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ and associated documentation files (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all copies or
+ substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ @licend The above is the entire license notice for the JavaScript code in this file
+*/
+var menudata={children:[
+{text:"Main Page",url:"index.html"},
+{text:"Classes",url:"annotated.html",children:[
+{text:"Class List",url:"annotated.html"},
+{text:"Class Index",url:"classes.html"},
+{text:"Class Hierarchy",url:"hierarchy.html"},
+{text:"Class Members",url:"functions.html",children:[
+{text:"All",url:"functions.html",children:[
+{text:"a",url:"functions.html#index_a"},
+{text:"b",url:"functions.html#index_b"},
+{text:"c",url:"functions.html#index_c"},
+{text:"d",url:"functions.html#index_d"},
+{text:"f",url:"functions.html#index_f"},
+{text:"h",url:"functions.html#index_h"},
+{text:"i",url:"functions.html#index_i"},
+{text:"l",url:"functions.html#index_l"},
+{text:"m",url:"functions.html#index_m"},
+{text:"n",url:"functions.html#index_n"},
+{text:"r",url:"functions.html#index_r"},
+{text:"s",url:"functions.html#index_s"},
+{text:"t",url:"functions.html#index_t"},
+{text:"u",url:"functions.html#index_u"},
+{text:"v",url:"functions.html#index_v"}]},
+{text:"Functions",url:"functions_func.html",children:[
+{text:"a",url:"functions_func.html#index_a"},
+{text:"b",url:"functions_func.html#index_b"},
+{text:"c",url:"functions_func.html#index_c"},
+{text:"d",url:"functions_func.html#index_d"},
+{text:"f",url:"functions_func.html#index_f"},
+{text:"i",url:"functions_func.html#index_i"},
+{text:"m",url:"functions_func.html#index_m"},
+{text:"n",url:"functions_func.html#index_n"},
+{text:"r",url:"functions_func.html#index_r"},
+{text:"s",url:"functions_func.html#index_s"},
+{text:"u",url:"functions_func.html#index_u"},
+{text:"v",url:"functions_func.html#index_v"}]},
+{text:"Properties",url:"functions_prop.html"}]}]},
+{text:"Files",url:"files.html",children:[
+{text:"File List",url:"files.html"}]}]}
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_f.png b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_f.png
new file mode 100644
index 0000000..72a58a5
Binary files /dev/null and b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_f.png differ
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_g.png b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_g.png
new file mode 100644
index 0000000..2093a23
Binary files /dev/null and b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_g.png differ
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_h.png b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_h.png
new file mode 100644
index 0000000..33389b1
Binary files /dev/null and b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/nav_h.png differ
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/open.png b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/open.png
new file mode 100644
index 0000000..30f75c7
Binary files /dev/null and b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/open.png differ
diff --git a/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/protocol_installer_progress_delegate-p-members.html b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/protocol_installer_progress_delegate-p-members.html
new file mode 100644
index 0000000..24e7e34
--- /dev/null
+++ b/documentation/api-reference/docsets/Sparkle.docset/Contents/Resources/Documents/protocol_installer_progress_delegate-p-members.html
@@ -0,0 +1,82 @@
+
+
+
+
+
+
+
+Sparkle: Member List
+
+
+
+
+
+
+
+
+
+
Returns the set of Sparkle channels the updater is allowed to find new updates from.
+
An appcast item can specify a channel the update is posted to. Without specifying a channel, the appcast item is posted to the default channel. For instance: <sparkle:version>2.0 Beta 1</sparkle:version> <sparkle:channel>beta</sparkle:channel>
+
This example posts an update to the 'beta' channel, so only updaters that are allowed to use the 'beta' channel can find this update.
+
If the <sparkle:channel> is not present, the update item is posted to the default channel and can be found by any updater.
+
You can pick any name you'd like for the channel. The valid characters for channel names are letters, numbers, dashes, underscores, and periods.
+
Note to use this feature, all app versions that your users may update from in your feed must use a version of Sparkle that supports this feature. This feature was added in Sparkle 2.
+
Returns
The set of channel names the updater is allowed to find new updates in. An empty set is the default behavior, which means the updater will only look for updates in the default channel.
Returns the item in the appcast corresponding to the update that should be installed.
+
Please consider using or migrating to other supported features before adopting this method. Specifically: If you want to filter out certain tagged updates (like beta updates), consider -[SPUUpdaterDelegate allowedChannelsForUpdater:] instead. If you want to treat certain updates as informational-only, consider supplying <sparkle:informationalUpdate> with a set of affected versions users are updating from.
+
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.
+
Do not base your logic by filtering out items with a minimum or maximum OS version or minimum autoupdate version, because Sparkle already has logic for determining whether or not those items should be filtered out. Also do not return a non-top level item from the appcast such as a delta item. Delta items will be ignored. Sparkle picks the delta item from your selection if the appropriate one is available.
+
This method will not be invoked with an appcast that has zero items. Pick the best item from the appcast. If an item is available that has the same version as the application or bundle to update, do not pick an item that is worse than that version.
+
This method may be called multiple times for different selections and filters. This method should be efficient.
+
Parameters
+
+
appcast
The appcast that was downloaded from the remote server.
+
updater
The updater instance.
+
+
+
+
Returns
The best valid appcast item. Return SUAppcastItem.emptyAppcastItem if no appcast item is valid. Return nil if you don't want to be delegated this task and want to let Sparkle handle picking the best valid update.
Override this to dynamically specify the entire URL. Alternatively you may want to consider adding a feed parameter using -feedParametersForUpdater:sendingSystemProfile: and having the server which appcast to serve.
Returns whether or not the updater should allow interaction from the installer.
+
Use this to override the default behavior which is to allow interaction with the installer.
+
If interaction is allowed, then an authorization prompt may show up to the user if they do not curently have sufficient privileges to perform the installation of the new update. The installer may also show UI and progress when interaction is allowed.
+
On the other hand, if interaction is not allowed, then an installation may fail if the user does not have sufficient privileges to perform the installation. In this case, the feed and update may not even be downloaded.
+
Note this has no effect if the update has already been downloaded in the background silently and ready to be resumed.
Called when an update is scheduled to be silently installed on quit after downloading the update automatically.
+
Parameters
+
+
updater
The updater instance.
+
item
The appcast item corresponding to the update that is proposed to be installed.
+
immediateInstallHandler
The install handler to immediately install the update. No UI interaction will be shown and the application will be relaunched after installation.
+
+
+
+
Returns
Return YES if the delegate will handle installing the update or NO if the updater should be given responsibility.
+
If the updater is given responsibility, it can later remind the user an update is available if they have not terminated the application for a long time. Also if the updater is given responsibility and the update item is marked critical, the new update will be presented to the user immediately after. Even if the immediateInstallHandler is not invoked, the installer will attempt to install the update on termination.
An error containing information on why a new valid update was not found There are various reasons a new update is unavailable and can't be installed. The userInfo dictionary on the error is also populated with three keys: SPULatestAppcastItemFoundKey: if available, this may provide the latest SUAppcastItem that was found. This will be nil if it's unavailable. SPUNoUpdateFoundReasonKey: This will provide the SUNoUpdateFoundReason. For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version. SPUNoUpdateFoundUserInitiatedKey: A boolean that indicates if a new update was not found when the user intitiated an update check manually.
For example, this may be used to prevent Sparkle from interrupting a setup assistant. Alternatively, you may want to consider starting the updater after eg: the setup assistant finishes
Returns an object that compares version numbers to determine their arithmetic relation to each other.
+
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. Note that the standard version comparator may be used during installation for preventing a downgrade, even if you provide a custom comparator here.
+("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.")
- __deprecated_msg
+
+
+
Detailed Description
+
The API in Sparkle for controlling the user interaction.
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle's internal drivers tell an object that implements this protocol what actions to take and show to the user.
+
Every method in this protocol can be assumed to be called from the main thread.
Stop and tear down everything. Dismiss all update windows, alerts, progress, etc from the user. Basically, stop everything that could have been started. Sparkle may invoke this when aborting or finishing an update.
Show the user the content length of the new update that will be downloaded.
+
Parameters
+
+
expectedContentLength
The expected content length of the new update being downloaded. An implementor should be able to handle if this value is invalid (more or less than actual content length downloaded). Additionally, this method may be called more than once for the same download in rare scenarios.
Show the user that the update finished downloading and started extracting.
+
Sparkle uses this to show an indeterminate progress bar.
+
Note that an update can resume at this point after having been downloaded before, so this may be called without any of the download callbacks being invoked prior.
Show the user that the update is ready to install & relaunch.
+
Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed. Note if the target application has already terminated, this method may not be invoked.
+
Parameters
+
+
reply
A reply of SPUUserUpdateChoiceInstall installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.
+
+
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.
+
A reply of SPUUserUpdateChoiceSkip cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.
+
Before this point, -showInstallingUpdate will be called.
Show or dismiss progress while a termination signal is being sent to the application from Sparkle's installer.
+
Terminating and relaunching the application (if requested to be relaunched) may happen quickly, or it may take some time to perform the final installation, or the termination signal can be canceled or delayed by the application or user.
+
It is up to the implementor whether or not to decide to continue showing installation progress or dismissing UI that won't remain obscuring other parts of the user interface.
+
This will not be invoked if the application that is being updated is already terminated.
Let the user know a new update is found and ask them what they want to do. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.
+
Parameters
+
+
appcastItem
The Appcast Item containing information that reflects the new update.
+
state
The current state of the user update. The state.stage values are: SPUUpdateStateNotDownloaded - Update has not been downloaded yet. SPUUpdateStateDownloaded - Update has already been downloaded but not started installing yet. SPUUpdateStateInstalling - Update has been downloaded and already started installing.
+
+
+
+
state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background.
+
Additionally, these properties on the appcastItem are of importance: appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you'll want to support this case. appcastItem.majorUpgrade indicates if the update is a major or paid upgrade. appcastItem.criticalUpdate indicates if the update is a critical update.
+
Parameters
+
+
reply
A reply of SPUUserUpdateChoiceInstall begins or resumes downloading or installing the update. If the state.stage is SPUUserUpdateStateInstalling, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch"). Do not use this reply if appcastItem.informationOnlyUpdate is YES.
+
+
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update for the time being. The user may be reminded of the update at a later point. If the state.stage is SPUUserUpdateStateDownloaded, the downloaded update is kept after dismissing until the next time an update is shown to the user. If the state.stage is SPUUserUpdateStateInstalling, the installing update is also preserved after dismissing. In this state however, the update will also still be installed after the application is terminated.
+
A reply of SPUUserUpdateChoiceSkip skips this particular version and won't notify the user again, unless they initiate an update check themselves. If appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped. If the state.stage is SPUUpdateStateInstalling, the installation is also canceled when the update is skipped.
Show the user the current presented update or its progress in utmost focus.
+
The user wishes to check for updates while the user is being shown update progress. Bring whatever is on screen to frontmost focus (permission request, update information, downloading or extraction status, choice to install update, etc).
Show the user that the update installation finished.
+
Let the user know that the update finished installing.
+
This will only be invoked if the updater process is still alive, which is typically not the case if the updater's lifetime is tied to the application it is updating. This implementation must not try to reference the old bundle prior to the installation, which will no longer be around.
+
Before this point, -showSendingTerminationSignal or -showReadyToInstallAndRelaunch: may be called.
+
Parameters
+
+
relaunched
Indicates if the update was relaunched.
+
acknowledgement
Acknowledge to the updater that the finished installation was shown.
Let the user know a new update was not found after they tried initiating an update check. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.
+
Parameters
+
+
error
The error associated with why a new update was not found. There are various reasons a new update is unavailable and can't be installed. This error object is populated with recovery and suggestion strings suitable to be shown in an alert.
+
+
+
+
The userInfo dictionary is also populated with two keys: SPULatestAppcastItemFoundKey: if available, this may provide the latest SUAppcastItem that was found. SPUNoUpdateFoundReasonKey: if available, this will provide the SUNoUpdateFoundReason. For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
+
Parameters
+
+
acknowledgement
Acknowledge to the updater that no update found error was shown.
Show the user that the new update's release notes could not be downloaded.
+
This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
+
Parameters
+
+
error
The error associated with why the new update's release notes could not be downloaded.
Show the user the release notes for the new update.
+
Display the release notes to the user. This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
+
Parameters
+
+
downloadData
The data for the release notes that was downloaded from the new update's appcast.
Called before showing a modal alert window,","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html#/c:objc(pl)SPUStandardUserDriverDelegate(im)standardUserDriverDidShowModalAlert":{"name":"-standardUserDriverDidShowModalAlert","abstract":"
Called after showing a modal alert window,","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html#/c:objc(pl)SPUStandardUserDriverDelegate(im)standardUserDriverRequestsVersionDisplayer":{"name":"-standardUserDriverRequestsVersionDisplayer","abstract":"
Returns an object that formats version numbers for display to the user.","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html":{"name":"SPUStandardUserDriverDelegate","abstract":"
A protocol for Sparkle’s standard user driver’s delegate
Begins a “probing” check for updates which will not actually offer to","parent_name":"SPUUpdater"},"Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)canCheckForUpdates":{"name":"canCheckForUpdates","abstract":"
A property indicating whether or not updates can be checked by the user.
initWithMajorUpgrade:criticalUpdate:informationalUpdate:minimumOperatingSystemVersionIsOK:maximumOperatingSystemVersionIsOK: (defined in SPUAppcastItemState)
resolveStateWithInformationalUpdateVersions:minimumOperatingSystemVersion:maximumOperatingSystemVersion:minimumAutoupdateVersion:criticalUpdateDictionary: (defined in SPUAppcastItemStateResolver)
Accessible property for the updater's user driver.
+
+
+
Detailed Description
+
A controller class that instantiates a SPUUpdater and allows binding UI to it.
+
This class can be instantiated in a nib or created programatically using initWithUpdaterDelegate:userDriverDelegate: or initWithStartingUpdater:updaterDelegate:userDriverDelegate:.
+
The controller's updater targets the application's main bundle and uses Sparkle's standard user interface. Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too.
+
The controller creates an SPUUpdater instance and allows hooking up the check for updates action and handling menu item validation. It also allows hooking up the updater's and user driver's delegates.
+
If you need more control over what bundle you want to update or you want to provide a custom user interface (via SPUUserDriver), please use SPUUpdater directly instead.
Explicitly checks for updates and displays a progress dialog while doing so.
+
This method is meant for a main menu item. Connect any NSMenuItem to this action in Interface Builder or programmatically, and Sparkle will check for updates and report back its findings verbosely when it is invoked.
+
When the target/action of the menu item is set to this controller and this method, this controller also handles enabling/disabling the menu item by checking -[SPUUpdater canCheckForUpdates]
+
This action checks updates by invoking -[SPUUpdater checkForUpdates]
Create a new SPUStandardUpdaterController programmatically allowing you to specify whether or not to start the updater immediately.
+
You can specify whether or not you want to start the updater immediately. If you do not start the updater, you must invoke -[SPUStandardUpdaterController startUpdater] at a later time to start it.
You cannot call this initializer directly. You must instantiate a SPUStandardUpdaterController inside of a nib (typically the MainMenu nib) to use it.
+
To create a SPUStandardUpdaterController programatically, use initWithUpdaterDelegate:userDriverDelegate: or initWithStartingUpdater:updaterDelegate:userDriverDelegate: instead.
Starts the updater if it has not already been started.
+
You should only call this method yourself if you opted out of starting the updater on initialization. Hence, do not call this yourself if you are instantiating this controller from a nib.
+
This invokes -[SPUUpdater startUpdater:]. If the application is misconfigured with Sparkle, an error is logged and an alert is shown to the user (after a few seconds) to contact the developer. If you want more control over this behavior, you can create your own SPUUpdater instead.
Some properties on the updater can be binded via KVO
+
When instantiated from a nib, don't perform update checks before the application has finished launching in a MainMenu nib (i.e applicationDidFinishLaunching:) or before the corresponding window/view controller has been loaded (i.e, windowDidLoad or viewDidLoad). The updater is not guaranteed to be started yet before these points.
Checks for updates, and displays progress while doing so if needed.
+
This is meant for users initiating a new update check or checking the current update progress.
+
If an update hasn't started, the user may be shown that a new check for updates is occurring. If an update has already been downloaded or begun installing, the user may be presented to install that update. If the user is already being presented with an update, that update will be shown to the user in active focus.
+
This will find updates that the user has previously opted into skipping.
+
See canCheckForUpdates property which can determine if this method may be invoked.
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.
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.
The bundle that should be targetted for updating. This must not be nil.
+
applicationBundle
The application bundle that should be waited for termination and relaunched (unless overridden). Usually this can be the same as hostBundle. This may differ when updating a plug-in or other non-application bundle.
+
userDriver
The user driver that Sparkle uses for user update interaction
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:]
+
Passing nil will remove any feed URL that has been set in the host bundle's user defaults.
+
For beta updates, you may consider migrating to -[SPUUpdaterDelegate allowedChannelsForUpdater:] in the future.
+
This method must be called on the main thread; calls from background threads will have no effect.
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, an update cycle is started in the next main runloop cycle. During this cycle, a permission prompt may be brought up (if needed) for checking if the user wants automatic update checking. Otherwise if automatic update checks are enabled, a scheduled update alert may be brought up if enough time has elapsed since the last check.
+
After starting the updater and before the next runloop cycle, one of -checkForUpdates, -checkForUpdatesInBackground, or -checkForUpdateInformation can be invoked. This may be useful if you want to check for updates immediately or without showing a permission prompt.
+
If the updater cannot be started (i.e, due to a configuration issue in the application), you may want to fall back appropriately. For example, the standard updater controller (SPUStandardUpdaterController) alerts the user that the app is misconfigured and to contact the developer.
+
This must be called on the main thread.
+
Parameters
+
+
error
The error that is populated if this method fails. Pass NULL if not interested in the error information.
+
+
+
+
Returns
YES if the updater started otherwise NO with a populated error
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
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.
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.
A property indicating whether or not an update session is in progress.
+
An update session is in progress when the appcast is being downloaded, an update is being downloaded, an update is being shown, update permission is being requested, or the installer is being started. An active session is when Sparkle's fired scheduler is running.
+
Note an update session may be inactive even though Sparkle's installer (ran as a separate process) may be running, or even though the update has been downloaded but the installation has been deferred. In both of these cases, a new update session may be activated with the update resumed at a later point (automatically or manually).
+
See also canCheckForUpdates property which is more suited for menu item validation.
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
Indicates whether or not anonymous system profile information is sent when checking for updates.
+
+
+
Detailed Description
+
This class can be used for reading certain updater settings.
+
It retrieves the settings by first looking into the host's user defaults. If the setting is not found in there, then the host's Info.plist file is looked at.
Initializes with data from a dictionary provided by the RSS class and state resolver.
+
This initializer method is intended to be marked "private" and discouraged from public usage. This method is available however. Talk to us to describe your use case and if you need to construct appcast items yourself.
A class used for performing file operations more suitable than NSFileManager for performing installation work. All operations on this class may be used on thread other than the main thread. This class provides just basic file operations and stays away from including much application-level logic.
Changes the owner and group IDs of an item at a specified target URL to match another URL
Parameters
+
+
targetURL
A URL pointing to the target item whose owner and group IDs to alter. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
matchURL
A URL pointing to the item whose owner and group IDs will be used for changing on the targetURL. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's owner and group IDs have changed to match the origin's ones, otherwise NO along with a populated error object
+
If the owner and group IDs match on the root items of targetURL and matchURL, this method stops and assumes that nothing needs to be done. Otherwise this method recursively changes the IDs if the target is a directory. If an item in the directory is encountered that is unable to be changed, then this method stops and returns NO. While this method will try to change the group ID, being unable to change the group ID does not result in a failure if the owner ID can be changed or matched.
A URL pointing to the item to move. The item at this URL must exist.
+
destinationURL
A URL pointing to the destination the item will be moved at. An item must not already exist at this URL.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was copied successfully, otherwise NO along with a populated error object
A URL pointing to the directory to create. The item at this URL must not exist, and the parent directory of this URL must already exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was created successfully, otherwise NO along with a populated error object
Creates a temporary directory on the same volume as a provided URL
Parameters
+
+
preferredName
A name that may be used when creating the temporary directory. Note that in the uncothirdStageErrormmon case this name is used, the temporary directory will be created inside the directory pointed by appropriateURL
+
appropriateURL
A URL to a directory that resides on the volume that the temporary directory will be created on. In the uncommon case, the temporary directory may be created inside this directory.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
A URL pointing to the newly created temporary directory, or nil with a populated error object if an error occurs.
+
When moving an item from a source to a destination, it is desirable to create a temporary intermediate destination on the same volume as the destination to ensure that the item will be moved, and not copied, from the intermediate point to the final destination. This ensures file atomicity.
A URL pointing to the item to move. The item at this URL must exist.
+
destinationURL
A URL pointing to the destination the item will be moved at. An item must not already exist at this URL.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was moved successfully, otherwise NO along with a populated error object
+
If sourceURL and destinationURL reside on the same volume, this operation will be an atomic move operation. Otherwise this will be equivalent to a copy & remove which will be a nonatomic operation.
Releases Apple's quarantine extended attribute from the item at the specified root URL
Parameters
+
+
rootURL
A URL pointing to the item to release from Apple's quarantine. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if all the items at the target could be released from quarantine, otherwise NO if any items couldn't along with a populated error object
+
This method removes quarantine attributes from an item, ideally an application, so that when the user launches a new application themselves, they don't have to witness the system dialog alerting them that they downloaded an application from the internet and asking if they want to continue. Note that this may not exactly mimic the system behavior when a user opens an application for the first time (i.e, the xattr isn't deleted), but this should be sufficient enough for our purposes.
+
This method may return NO even if some items do get released from quarantine if the target URL is pointing to a directory. Thus if an item cannot be released from quarantine, this method still continues on to the next enumerated item.
A URL pointing to the item to remove. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the item was removed successfully, otherwise NO along with a populated error object
Replaces an original item with a new item atomically.
Parameters
+
+
originalItemURL
A URL pointing to the original item to replace. The item at this URL must exist.
+
newItemURL
A URL pointing to the new item that will replace the original item.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the original item was replaced with the new item successfully, otherwise NO along with a populated error object
+
originalItemURL and newItemURL must reside on the same volume. If the operation succeeds, this will be be an atomic operation. Otherwise on failure you may need to re-try using move operations. This operation will fail on non-apfs volumes or volumes that don't support rename swapping. Both originalItemURL and newItemURL must exist.
Updates the access time of an item at a specified root URL to the current time
Parameters
+
+
targetURL
A URL pointing to the target item whose access time to update to the current time. This will be applied recursively if the item is a directory. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's access times have been updated, otherwise NO along with a populated error object
+
This method updates the access time of an item to the current time, ideal for letting the system know not to remove a file or directory when placing it at a temporary directory.
Updates the modification and access time of an item at a specified target URL to the current time
Parameters
+
+
targetURL
A URL pointing to the target item whose modification and access time to update. The item at this URL must exist.
+
error
If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.
+
+
+
+
Returns
YES if the target item's modification and access times have been updated, otherwise NO along with a populated error object
+
This method updates the modification and access time of an item to the current time, ideal for letting the system know we installed a new file or application.
+
This is not an atomic operation.
+
+
+
+The documentation for this class was generated from the following files:
Returns a singleton instance of the comparator. More...
+
+
+
Detailed Description
+
Sparkle's default version comparator.
+
This comparator is adapted from MacPAD, by Kevin Ballard. It's "dumb" in that it does essentially string comparison, in components split by character type.
');
+ }
+ }
+ $('#main-menu').smartmenus();
+}
+/* @license-end */
diff --git a/documentation/api-reference/menudata.js b/documentation/api-reference/menudata.js
new file mode 100644
index 0000000..7eff031
--- /dev/null
+++ b/documentation/api-reference/menudata.js
@@ -0,0 +1,63 @@
+/*
+ @licstart The following is the entire license notice for the JavaScript code in this file.
+
+ The MIT License (MIT)
+
+ Copyright (C) 1997-2020 by Dimitri van Heesch
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ and associated documentation files (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all copies or
+ substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ @licend The above is the entire license notice for the JavaScript code in this file
+*/
+var menudata={children:[
+{text:"Main Page",url:"index.html"},
+{text:"Classes",url:"annotated.html",children:[
+{text:"Class List",url:"annotated.html"},
+{text:"Class Index",url:"classes.html"},
+{text:"Class Hierarchy",url:"hierarchy.html"},
+{text:"Class Members",url:"functions.html",children:[
+{text:"All",url:"functions.html",children:[
+{text:"a",url:"functions.html#index_a"},
+{text:"b",url:"functions.html#index_b"},
+{text:"c",url:"functions.html#index_c"},
+{text:"d",url:"functions.html#index_d"},
+{text:"f",url:"functions.html#index_f"},
+{text:"h",url:"functions.html#index_h"},
+{text:"i",url:"functions.html#index_i"},
+{text:"l",url:"functions.html#index_l"},
+{text:"m",url:"functions.html#index_m"},
+{text:"n",url:"functions.html#index_n"},
+{text:"r",url:"functions.html#index_r"},
+{text:"s",url:"functions.html#index_s"},
+{text:"t",url:"functions.html#index_t"},
+{text:"u",url:"functions.html#index_u"},
+{text:"v",url:"functions.html#index_v"}]},
+{text:"Functions",url:"functions_func.html",children:[
+{text:"a",url:"functions_func.html#index_a"},
+{text:"b",url:"functions_func.html#index_b"},
+{text:"c",url:"functions_func.html#index_c"},
+{text:"d",url:"functions_func.html#index_d"},
+{text:"f",url:"functions_func.html#index_f"},
+{text:"i",url:"functions_func.html#index_i"},
+{text:"m",url:"functions_func.html#index_m"},
+{text:"n",url:"functions_func.html#index_n"},
+{text:"r",url:"functions_func.html#index_r"},
+{text:"s",url:"functions_func.html#index_s"},
+{text:"u",url:"functions_func.html#index_u"},
+{text:"v",url:"functions_func.html#index_v"}]},
+{text:"Properties",url:"functions_prop.html"}]}]},
+{text:"Files",url:"files.html",children:[
+{text:"File List",url:"files.html"}]}]}
diff --git a/documentation/api-reference/nav_f.png b/documentation/api-reference/nav_f.png
new file mode 100644
index 0000000..72a58a5
Binary files /dev/null and b/documentation/api-reference/nav_f.png differ
diff --git a/documentation/api-reference/nav_g.png b/documentation/api-reference/nav_g.png
new file mode 100644
index 0000000..2093a23
Binary files /dev/null and b/documentation/api-reference/nav_g.png differ
diff --git a/documentation/api-reference/nav_h.png b/documentation/api-reference/nav_h.png
new file mode 100644
index 0000000..33389b1
Binary files /dev/null and b/documentation/api-reference/nav_h.png differ
diff --git a/documentation/api-reference/open.png b/documentation/api-reference/open.png
new file mode 100644
index 0000000..30f75c7
Binary files /dev/null and b/documentation/api-reference/open.png differ
diff --git a/documentation/api-reference/protocol_installer_progress_delegate-p-members.html b/documentation/api-reference/protocol_installer_progress_delegate-p-members.html
new file mode 100644
index 0000000..24e7e34
--- /dev/null
+++ b/documentation/api-reference/protocol_installer_progress_delegate-p-members.html
@@ -0,0 +1,82 @@
+
+
+
+
+
+
+
+Sparkle: Member List
+
+
+
+
+
+
+
+
+
+
Returns the set of Sparkle channels the updater is allowed to find new updates from.
+
An appcast item can specify a channel the update is posted to. Without specifying a channel, the appcast item is posted to the default channel. For instance: <sparkle:version>2.0 Beta 1</sparkle:version> <sparkle:channel>beta</sparkle:channel>
+
This example posts an update to the 'beta' channel, so only updaters that are allowed to use the 'beta' channel can find this update.
+
If the <sparkle:channel> is not present, the update item is posted to the default channel and can be found by any updater.
+
You can pick any name you'd like for the channel. The valid characters for channel names are letters, numbers, dashes, underscores, and periods.
+
Note to use this feature, all app versions that your users may update from in your feed must use a version of Sparkle that supports this feature. This feature was added in Sparkle 2.
+
Returns
The set of channel names the updater is allowed to find new updates in. An empty set is the default behavior, which means the updater will only look for updates in the default channel.
Returns the item in the appcast corresponding to the update that should be installed.
+
Please consider using or migrating to other supported features before adopting this method. Specifically: If you want to filter out certain tagged updates (like beta updates), consider -[SPUUpdaterDelegate allowedChannelsForUpdater:] instead. If you want to treat certain updates as informational-only, consider supplying <sparkle:informationalUpdate> with a set of affected versions users are updating from.
+
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.
+
Do not base your logic by filtering out items with a minimum or maximum OS version or minimum autoupdate version, because Sparkle already has logic for determining whether or not those items should be filtered out. Also do not return a non-top level item from the appcast such as a delta item. Delta items will be ignored. Sparkle picks the delta item from your selection if the appropriate one is available.
+
This method will not be invoked with an appcast that has zero items. Pick the best item from the appcast. If an item is available that has the same version as the application or bundle to update, do not pick an item that is worse than that version.
+
This method may be called multiple times for different selections and filters. This method should be efficient.
+
Parameters
+
+
appcast
The appcast that was downloaded from the remote server.
+
updater
The updater instance.
+
+
+
+
Returns
The best valid appcast item. Return SUAppcastItem.emptyAppcastItem if no appcast item is valid. Return nil if you don't want to be delegated this task and want to let Sparkle handle picking the best valid update.
Override this to dynamically specify the entire URL. Alternatively you may want to consider adding a feed parameter using -feedParametersForUpdater:sendingSystemProfile: and having the server which appcast to serve.
Returns whether or not the updater should allow interaction from the installer.
+
Use this to override the default behavior which is to allow interaction with the installer.
+
If interaction is allowed, then an authorization prompt may show up to the user if they do not curently have sufficient privileges to perform the installation of the new update. The installer may also show UI and progress when interaction is allowed.
+
On the other hand, if interaction is not allowed, then an installation may fail if the user does not have sufficient privileges to perform the installation. In this case, the feed and update may not even be downloaded.
+
Note this has no effect if the update has already been downloaded in the background silently and ready to be resumed.
Called when an update is scheduled to be silently installed on quit after downloading the update automatically.
+
Parameters
+
+
updater
The updater instance.
+
item
The appcast item corresponding to the update that is proposed to be installed.
+
immediateInstallHandler
The install handler to immediately install the update. No UI interaction will be shown and the application will be relaunched after installation.
+
+
+
+
Returns
Return YES if the delegate will handle installing the update or NO if the updater should be given responsibility.
+
If the updater is given responsibility, it can later remind the user an update is available if they have not terminated the application for a long time. Also if the updater is given responsibility and the update item is marked critical, the new update will be presented to the user immediately after. Even if the immediateInstallHandler is not invoked, the installer will attempt to install the update on termination.
An error containing information on why a new valid update was not found There are various reasons a new update is unavailable and can't be installed. The userInfo dictionary on the error is also populated with three keys: SPULatestAppcastItemFoundKey: if available, this may provide the latest SUAppcastItem that was found. This will be nil if it's unavailable. SPUNoUpdateFoundReasonKey: This will provide the SUNoUpdateFoundReason. For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version. SPUNoUpdateFoundUserInitiatedKey: A boolean that indicates if a new update was not found when the user intitiated an update check manually.
For example, this may be used to prevent Sparkle from interrupting a setup assistant. Alternatively, you may want to consider starting the updater after eg: the setup assistant finishes
Returns an object that compares version numbers to determine their arithmetic relation to each other.
+
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. Note that the standard version comparator may be used during installation for preventing a downgrade, even if you provide a custom comparator here.
+("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.")
- __deprecated_msg
+
+
+
Detailed Description
+
The API in Sparkle for controlling the user interaction.
+
This protocol is used for implementing a user interface for the Sparkle updater. Sparkle's internal drivers tell an object that implements this protocol what actions to take and show to the user.
+
Every method in this protocol can be assumed to be called from the main thread.
Stop and tear down everything. Dismiss all update windows, alerts, progress, etc from the user. Basically, stop everything that could have been started. Sparkle may invoke this when aborting or finishing an update.
Show the user the content length of the new update that will be downloaded.
+
Parameters
+
+
expectedContentLength
The expected content length of the new update being downloaded. An implementor should be able to handle if this value is invalid (more or less than actual content length downloaded). Additionally, this method may be called more than once for the same download in rare scenarios.
Show the user that the update finished downloading and started extracting.
+
Sparkle uses this to show an indeterminate progress bar.
+
Note that an update can resume at this point after having been downloaded before, so this may be called without any of the download callbacks being invoked prior.
Show the user that the update is ready to install & relaunch.
+
Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed. Note if the target application has already terminated, this method may not be invoked.
+
Parameters
+
+
reply
A reply of SPUUserUpdateChoiceInstall installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.
+
+
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.
+
A reply of SPUUserUpdateChoiceSkip cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.
+
Before this point, -showInstallingUpdate will be called.
Show or dismiss progress while a termination signal is being sent to the application from Sparkle's installer.
+
Terminating and relaunching the application (if requested to be relaunched) may happen quickly, or it may take some time to perform the final installation, or the termination signal can be canceled or delayed by the application or user.
+
It is up to the implementor whether or not to decide to continue showing installation progress or dismissing UI that won't remain obscuring other parts of the user interface.
+
This will not be invoked if the application that is being updated is already terminated.
Let the user know a new update is found and ask them what they want to do. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.
+
Parameters
+
+
appcastItem
The Appcast Item containing information that reflects the new update.
+
state
The current state of the user update. The state.stage values are: SPUUpdateStateNotDownloaded - Update has not been downloaded yet. SPUUpdateStateDownloaded - Update has already been downloaded but not started installing yet. SPUUpdateStateInstalling - Update has been downloaded and already started installing.
+
+
+
+
state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background.
+
Additionally, these properties on the appcastItem are of importance: appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you'll want to support this case. appcastItem.majorUpgrade indicates if the update is a major or paid upgrade. appcastItem.criticalUpdate indicates if the update is a critical update.
+
Parameters
+
+
reply
A reply of SPUUserUpdateChoiceInstall begins or resumes downloading or installing the update. If the state.stage is SPUUserUpdateStateInstalling, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch"). Do not use this reply if appcastItem.informationOnlyUpdate is YES.
+
+
+
+
A reply of SPUUserUpdateChoiceDismiss dismisses the update for the time being. The user may be reminded of the update at a later point. If the state.stage is SPUUserUpdateStateDownloaded, the downloaded update is kept after dismissing until the next time an update is shown to the user. If the state.stage is SPUUserUpdateStateInstalling, the installing update is also preserved after dismissing. In this state however, the update will also still be installed after the application is terminated.
+
A reply of SPUUserUpdateChoiceSkip skips this particular version and won't notify the user again, unless they initiate an update check themselves. If appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped. If the state.stage is SPUUpdateStateInstalling, the installation is also canceled when the update is skipped.
Show the user the current presented update or its progress in utmost focus.
+
The user wishes to check for updates while the user is being shown update progress. Bring whatever is on screen to frontmost focus (permission request, update information, downloading or extraction status, choice to install update, etc).
Show the user that the update installation finished.
+
Let the user know that the update finished installing.
+
This will only be invoked if the updater process is still alive, which is typically not the case if the updater's lifetime is tied to the application it is updating. This implementation must not try to reference the old bundle prior to the installation, which will no longer be around.
+
Before this point, -showSendingTerminationSignal or -showReadyToInstallAndRelaunch: may be called.
+
Parameters
+
+
relaunched
Indicates if the update was relaunched.
+
acknowledgement
Acknowledge to the updater that the finished installation was shown.
Let the user know a new update was not found after they tried initiating an update check. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.
+
Parameters
+
+
error
The error associated with why a new update was not found. There are various reasons a new update is unavailable and can't be installed. This error object is populated with recovery and suggestion strings suitable to be shown in an alert.
+
+
+
+
The userInfo dictionary is also populated with two keys: SPULatestAppcastItemFoundKey: if available, this may provide the latest SUAppcastItem that was found. SPUNoUpdateFoundReasonKey: if available, this will provide the SUNoUpdateFoundReason. For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
+
Parameters
+
+
acknowledgement
Acknowledge to the updater that no update found error was shown.
Show the user that the new update's release notes could not be downloaded.
+
This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
+
Parameters
+
+
error
The error associated with why the new update's release notes could not be downloaded.
Show the user the release notes for the new update.
+
Display the release notes to the user. This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.
+
Parameters
+
+
downloadData
The data for the release notes that was downloaded from the new update's appcast.
Called before showing a modal alert window,","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html#/c:objc(pl)SPUStandardUserDriverDelegate(im)standardUserDriverDidShowModalAlert":{"name":"-standardUserDriverDidShowModalAlert","abstract":"
Called after showing a modal alert window,","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html#/c:objc(pl)SPUStandardUserDriverDelegate(im)standardUserDriverRequestsVersionDisplayer":{"name":"-standardUserDriverRequestsVersionDisplayer","abstract":"
Returns an object that formats version numbers for display to the user.","parent_name":"SPUStandardUserDriverDelegate"},"Protocols/SPUStandardUserDriverDelegate.html":{"name":"SPUStandardUserDriverDelegate","abstract":"
A protocol for Sparkle’s standard user driver’s delegate
Begins a “probing” check for updates which will not actually offer to","parent_name":"SPUUpdater"},"Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)canCheckForUpdates":{"name":"canCheckForUpdates","abstract":"
A property indicating whether or not updates can be checked by the user.
+ 
+ 
+
+
Instance Methods inherited from 
+ 
+
+
+
+
+
+
+ 
+ 
+
+
+
+
+
+
+
+
+
+
+ 
+
+
+ 
+ 
+ 
+ 
+ 
+
+
+ 
+ 
+ 
+ 
+
+
+
+
+ 
+ 
+ 
+
+
+
+
+
+
+ 
+ 
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+ 
+ 
+ 
+ 
+ 
+
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+
+
+
+
+
+
+ 
+
+
+
+
+
+
+ 
+
+