SUAppcastItem

Objective-C

@interface SUAppcastItem : NSObject <NSSecureCoding>

Swift

class SUAppcastItem : NSObject, NSSecureCoding

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.

Extended documentation and examples on using appcast item features are available at: https://sparkle-project.org/documentation/publishing/

  • The version of the update item.

    Sparkle uses this property to compare update items and determine the best available update item in the SUAppcast.

    This corresponds to the application update’s CFBundleVersion

    This is extracted from the <sparkle:version> element, or the sparkle:version attribute from the <enclosure> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull versionString;

    Swift

    var versionString: String { get }

  • The human-readable display version of the update item if provided.

    This is the version string shown to the user when they are notified of a new update.

    This corresponds to the application update’s CFBundleShortVersionString

    This is extracted from the <sparkle:shortVersionString> element, or the sparkle:shortVersionString attribute from the <enclosure> element.

    If no short version string is available, this falls back to the update’s versionString.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull displayVersionString;

    Swift

    var displayVersionString: String { get }

  • The file URL to the update item if provided.

    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.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *fileURL;

    Swift

    var fileURL: URL? { get }

  • The content length of the download in bytes.

    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.

    Declaration

    Objective-C

    @property (nonatomic, readonly) uint64_t contentLength;

    Swift

    var contentLength: UInt64 { get }

  • The info URL to the update item if 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.

    The informational link will be used if informationOnlyUpdate is YES

    This is extracted from the <link> element.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *infoURL;

    Swift

    var infoURL: URL? { get }

  • Indicates whether or not the update item is only informational and has no download.

    If infoURL is not present, this is NO

    If fileURL is not present, this is YES

    Otherwise this is determined based on the contents extracted from the <sparkle:informationalUpdate> element.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isInformationOnlyUpdate) BOOL informationOnlyUpdate;

    Swift

    var isInformationOnlyUpdate: Bool { get }

  • The title of the appcast item if provided.

    This is extracted from the <title> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *title;

    Swift

    var title: String? { get }

  • The date string of the appcast item if provided.

    The date property is constructed from this property and expects this string to comply with the following date format: E, dd MMM yyyy HH:mm:ss Z

    This is extracted from the <pubDate> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *dateString;

    Swift

    var dateString: String? { get }

  • The date constructed from the dateString property if provided.

    Sparkle by itself only uses this property for phased group rollouts specified via phasedRolloutInterval, but clients may query this property too.

    This date is constructed using the en_US locale.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSDate *date;

    Swift

    var date: Date? { get }

  • The release notes URL of the appcast item if provided.

    This external link points to an HTML file that Sparkle downloads and renders to show the user a new or old update item’s changelog.

    An alternative to using an external release notes link is providing an embedded itemDescription.

    This is extracted from the <sparkle:releaseNotesLink> element.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *releaseNotesURL;

    Swift

    var releaseNotesURL: URL? { get }

  • The description of the appcast item if provided.

    A description may be provided for inline/embedded release notes for new updates using <![CDATA[...]]> This is an alternative to providing a releaseNotesURL.

    This is extracted from the <description> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *itemDescription;

    Swift

    var itemDescription: String? { get }

  • The format of the itemDescription for inline/embedded release notes if provided.

    This may be:

    • html
    • plain-text

    This is extracted from the sparkle:descriptionFormat attribute in the <description> element.

    If the format is not provided in the <description> element of the appcast item, then this property may default to html.

    If the <description> element of the appcast item is not available, this property is nil.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *itemDescriptionFormat;

    Swift

    var itemDescriptionFormat: String? { get }

  • The full release notes URL of the appcast item if provided.

    The link should point to the product’s full changelog.

    Sparkle’s standard user interface offers to show these full release notes when a user checks for a new update and no new update is available.

    This is extracted from the <sparkle:fullReleaseNotesLink> element.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *fullReleaseNotesURL;

    Swift

    var fullReleaseNotesURL: URL? { get }

  • The required minimum system operating version string for this update if provided.

    This version string should contain three period-separated components.

    Example: 10.13.0

    Use minimumOperatingSystemVersionIsOK property to test if the current running system passes this requirement.

    This is extracted from the <sparkle:minimumSystemVersion> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *minimumSystemVersion;

    Swift

    var minimumSystemVersion: String? { get }

  • Indicates whether or not the current running system passes the minimumSystemVersion requirement.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL minimumOperatingSystemVersionIsOK;

    Swift

    var minimumOperatingSystemVersionIsOK: Bool { get }

  • The required maximum system operating version string for this update if provided.

    A maximum system operating version requirement should only be made in unusual scenarios.

    This version string should contain three period-separated components.

    Example: 10.14.0

    Use maximumOperatingSystemVersionIsOK property to test if the current running system passes this requirement.

    This is extracted from the <sparkle:maximumSystemVersion> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *maximumSystemVersion;

    Swift

    var maximumSystemVersion: String? { get }

  • Indicates whether or not the current running system passes the maximumSystemVersion requirement.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL maximumOperatingSystemVersionIsOK;

    Swift

    var maximumOperatingSystemVersionIsOK: Bool { get }

  • The channel the update item is on if provided.

    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.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *channel;

    Swift

    var channel: String? { get }

  • The installation type of the update at fileURL

    This may be:

    • 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.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull installationType;

    Swift

    var installationType: String { get }

  • The phased rollout interval of the update item in seconds if provided.

    This is the interval between when different groups of users are notified of a new update.

    For this property to be used by Sparkle, the published date on the update item must be present as well.

    After each interval after the update item’s date, a new group of users become eligible for being notified of the new update.

    This is extracted from the <sparkle:phasedRolloutInterval> element.

    Old applications must be using Sparkle 1.25 or later to support phased rollout intervals, otherwise they may assume updates are immediately available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSNumber *phasedRolloutInterval;

    Swift

    @NSCopying var phasedRolloutInterval: NSNumber? { get }

  • 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 automatically unless an update specifies ignoreSkippedUpgradesBelowVersion.

    This version string corresponds to the application’s CFBundleVersion

    This is extracted from the <sparkle:minimumAutoupdateVersion> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *minimumAutoupdateVersion;

    Swift

    var minimumAutoupdateVersion: String? { get }

  • Indicates whether or not the update item is a major upgrade.

    An update is a major upgrade if the application’s bundle version doesn’t meet the minimumAutoupdateVersion requirement.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isMajorUpgrade) BOOL majorUpgrade;

    Swift

    var isMajorUpgrade: Bool { get }

  • Previously skipped upgrades by the user will be ignored if they skipped an update whose version precedes this version.

    This can only be applied if the update is a majorUpgrade.

    This version string corresponds to the application’s CFBundleVersion

    This is extracted from the <sparkle:ignoreSkippedUpgradesBelowVersion> element.

    Old applications must be using Sparkle 2.1 or later, otherwise this property will be ignored.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *ignoreSkippedUpgradesBelowVersion;

    Swift

    var ignoreSkippedUpgradesBelowVersion: String? { get }

  • 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.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isCriticalUpdate) BOOL criticalUpdate;

    Swift

    var isCriticalUpdate: Bool { get }

  • 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.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *osString;

    Swift

    var osString: String? { get }

  • Indicates whether or not this update item is for macOS.

    This is determined from the osString property.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isMacOsUpdate) BOOL macOsUpdate;

    Swift

    var isMacOsUpdate: Bool { get }

  • The delta updates for this update item.

    Sparkle uses these to download and apply a smaller update based on the version the user is updating from.

    The key is based on the sparkle:version of the update. The value is an update item that will have deltaUpdate be YES

    Clients typically should not need to examine the contents of the delta updates.

    This is extracted from the <sparkle:deltas> element.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSDictionary<NSString *, SUAppcastItem *> *deltaUpdates;

    Swift

    var deltaUpdates: [String : SUAppcastItem]? { get }

  • The expected size of the Sparkle executable file before applying this delta update.

    This attribute is used to test if the delta item can still be applied. If Sparkle’s executable file has changed (e.g. from having an architecture stripped), then the delta item cannot be applied.

    This is extracted from the sparkle:deltaFromSparkleExecutableSize attribute from the <enclosure> element of a sparkle:deltas item. This attribute is optional for delta update items.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSNumber *deltaFromSparkleExecutableSize;

    Swift

    var deltaFromSparkleExecutableSize: NSNumber? { get }

  • An expected set of Sparkle’s locales present on disk before applying this delta update.

    This attribute is used to test if the delta item can still be applied. If Sparkle’s list of locales present on disk (.lproj directories) do not contain any items from this set, (e.g. from having localization files stripped) then the delta item cannot be applied. This set does not need to be a complete list of locales. Sparkle may even decide to not process all them. 1-10 should be a decent amount.

    This is extracted from the sparkle:deltaFromSparkleLocales attribute from the <enclosure> element of a sparkle:deltas item. The locales extracted from this attribute are delimited by a comma (e.g. “en,ca,fr,hr,hu”). This attribute is optional for delta update items.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSSet<NSString *> *deltaFromSparkleLocales;

    Swift

    var deltaFromSparkleLocales: Set<String>? { get }

  • Indicates whether or not the update item is a delta update.

    An update item is a delta update if it is in the deltaUpdates of another update item.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isDeltaUpdate) BOOL deltaUpdate;

    Swift

    var isDeltaUpdate: Bool { get }

  • The dictionary representing the entire appcast item.

    This is useful for querying custom extensions or elements from the appcast item.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSDictionary *_Nonnull propertiesDictionary;

    Swift

    var propertiesDictionary: [AnyHashable : Any] { get }

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)init NS_UNAVAILABLE;

  • An empty appcast item.

    This may be used as a potential return value in -[SPUUpdaterDelegate bestValidUpdateInAppcast:forUpdater:]

    Declaration

    Objective-C

    + (nonnull instancetype)emptyAppcastItem;

    Swift

    class func empty() -> Self

  • Deprecated

    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

    - (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.");

    Swift

    init?(dictionary dict: [AnyHashable : Any])

  • Deprecated

    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

    - (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.");

    Swift

    init?(dictionary dict: [AnyHashable : Any], failureReason error: AutoreleasingUnsafeMutablePointer<NSString?>?)

  • Deprecated

    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

    - (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.");

    Swift

    init?(dictionary dict: [AnyHashable : Any], relativeTo appcastURL: URL?, failureReason error: AutoreleasingUnsafeMutablePointer<NSString?>?)