Frameworks/Sparkle.framework/Versions/A/Headers/SUUpdater.h
branchadium-1.5.10.4
changeset 5985 5883c460b8cb
parent 5924 f0f2d246891c
equal deleted inserted replaced
5984:c42b73c02750 5985:5883c460b8cb
     7 //
     7 //
     8 
     8 
     9 #ifndef SUUPDATER_H
     9 #ifndef SUUPDATER_H
    10 #define SUUPDATER_H
    10 #define SUUPDATER_H
    11 
    11 
    12 #import <Foundation/Foundation.h>
    12 #if __has_feature(modules)
       
    13 @import Cocoa;
       
    14 #else
       
    15 #import <Cocoa/Cocoa.h>
       
    16 #endif
    13 #import "SUExport.h"
    17 #import "SUExport.h"
    14 #import "SUVersionComparisonProtocol.h"
    18 #import "SUVersionComparisonProtocol.h"
    15 #import "SUVersionDisplayProtocol.h"
    19 #import "SUVersionDisplayProtocol.h"
    16 
    20 
    17 @class SUUpdateDriver, SUAppcastItem, SUHost, SUAppcast;
    21 @class SUAppcastItem, SUAppcast;
    18 
    22 
    19 @protocol SUUpdaterDelegate;
    23 @protocol SUUpdaterDelegate;
    20 
    24 
    21 /*!
    25 /*!
    22     The main API in Sparkle for controlling the update mechanism.
    26     The main API in Sparkle for controlling the update mechanism.
    26  */
    30  */
    27 SU_EXPORT @interface SUUpdater : NSObject
    31 SU_EXPORT @interface SUUpdater : NSObject
    28 
    32 
    29 @property (unsafe_unretained) IBOutlet id<SUUpdaterDelegate> delegate;
    33 @property (unsafe_unretained) IBOutlet id<SUUpdaterDelegate> delegate;
    30 
    34 
       
    35 /*!
       
    36  The shared updater for the main bundle.
       
    37  
       
    38  This is equivalent to passing [NSBundle mainBundle] to SUUpdater::updaterForBundle:
       
    39  */
    31 + (SUUpdater *)sharedUpdater;
    40 + (SUUpdater *)sharedUpdater;
       
    41 
       
    42 /*!
       
    43  The shared updater for a specified bundle.
       
    44 
       
    45  If an updater has already been initialized for the provided bundle, that shared instance will be returned.
       
    46  */
    32 + (SUUpdater *)updaterForBundle:(NSBundle *)bundle;
    47 + (SUUpdater *)updaterForBundle:(NSBundle *)bundle;
       
    48 
       
    49 /*!
       
    50  Designated initializer for SUUpdater.
       
    51  
       
    52  If an updater has already been initialized for the provided bundle, that shared instance will be returned.
       
    53  */
    33 - (instancetype)initForBundle:(NSBundle *)bundle;
    54 - (instancetype)initForBundle:(NSBundle *)bundle;
    34 
    55 
       
    56 /*!
       
    57  Explicitly checks for updates and displays a progress dialog while doing so.
       
    58 
       
    59  This method is meant for a main menu item.
       
    60  Connect any menu item to this action in Interface Builder,
       
    61  and Sparkle will check for updates and report back its findings verbosely
       
    62  when it is invoked.
       
    63 
       
    64  This will find updates that the user has opted into skipping.
       
    65  */
       
    66 - (IBAction)checkForUpdates:(id)sender;
       
    67 
       
    68 /*!
       
    69  The menu item validation used for the -checkForUpdates: action
       
    70  */
       
    71 - (BOOL)validateMenuItem:(NSMenuItem *)menuItem;
       
    72 
       
    73 /*!
       
    74  Checks for updates, but does not display any UI unless an update is found.
       
    75 
       
    76  This is meant for programmatically initating a check for updates. That is,
       
    77  it will display no UI unless it actually finds an update, in which case it
       
    78  proceeds as usual.
       
    79 
       
    80  If automatic downloading of updates it turned on and allowed, however,
       
    81  this will invoke that behavior, and if an update is found, it will be downloaded
       
    82  in the background silently and will be prepped for installation.
       
    83 
       
    84  This will not find updates that the user has opted into skipping.
       
    85  */
       
    86 - (void)checkForUpdatesInBackground;
       
    87 
       
    88 /*!
       
    89  A property indicating whether or not to check for updates automatically.
       
    90 
       
    91  Setting this property will persist in the host bundle's user defaults.
       
    92  The update schedule cycle will be reset in a short delay after the property's new value is set.
       
    93  This is to allow reverting this property without kicking off a schedule change immediately
       
    94  */
       
    95 @property BOOL automaticallyChecksForUpdates;
       
    96 
       
    97 /*!
       
    98  A property indicating whether or not updates can be automatically downloaded in the background.
       
    99 
       
   100  Note that automatic downloading of updates can be disallowed by the developer
       
   101  or by the user's system if silent updates cannot be done (eg: if they require authentication).
       
   102  In this case, -automaticallyDownloadsUpdates will return NO regardless of how this property is set.
       
   103 
       
   104  Setting this property will persist in the host bundle's user defaults.
       
   105  */
       
   106 @property BOOL automaticallyDownloadsUpdates;
       
   107 
       
   108 /*!
       
   109  A property indicating the current automatic update check interval.
       
   110 
       
   111  Setting this property will persist in the host bundle's user defaults.
       
   112  The update schedule cycle will be reset in a short delay after the property's new value is set.
       
   113  This is to allow reverting this property without kicking off a schedule change immediately
       
   114  */
       
   115 @property NSTimeInterval updateCheckInterval;
       
   116 
       
   117 /*!
       
   118  Begins a "probing" check for updates which will not actually offer to
       
   119  update to that version.
       
   120 
       
   121  However, the delegate methods
       
   122  SUUpdaterDelegate::updater:didFindValidUpdate: and
       
   123  SUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
       
   124  so you can use that information in your UI.
       
   125 
       
   126  Updates that have been skipped by the user will not be found.
       
   127  */
       
   128 - (void)checkForUpdateInformation;
       
   129 
       
   130 /*!
       
   131  The URL of the appcast used to download update information.
       
   132 
       
   133  Setting this property will persist in the host bundle's user defaults.
       
   134  If you don't want persistence, you may want to consider instead implementing
       
   135  SUUpdaterDelegate::feedURLStringForUpdater: or SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
       
   136 
       
   137  This property must be called on the main thread.
       
   138  */
       
   139 @property (copy) NSURL *feedURL;
       
   140 
       
   141 /*!
       
   142  The host bundle that is being updated.
       
   143  */
    35 @property (readonly, strong) NSBundle *hostBundle;
   144 @property (readonly, strong) NSBundle *hostBundle;
       
   145 
       
   146 /*!
       
   147  The bundle this class (SUUpdater) is loaded into.
       
   148  */
    36 @property (strong, readonly) NSBundle *sparkleBundle;
   149 @property (strong, readonly) NSBundle *sparkleBundle;
    37 
   150 
    38 @property BOOL automaticallyChecksForUpdates;
   151 /*!
    39 
   152  The user agent used when checking for updates.
    40 @property NSTimeInterval updateCheckInterval;
   153 
    41 
   154  The default implementation can be overrided.
    42 /*!
   155  */
    43  * The URL of the appcast used to download update information.
       
    44  *
       
    45  * This property must be called on the main thread.
       
    46  */
       
    47 @property (copy) NSURL *feedURL;
       
    48 
       
    49 @property (nonatomic, copy) NSString *userAgentString;
   156 @property (nonatomic, copy) NSString *userAgentString;
    50 
   157 
       
   158 /*!
       
   159  The HTTP headers used when checking for updates.
       
   160 
       
   161  The keys of this dictionary are HTTP header fields (NSString) and values are corresponding values (NSString)
       
   162  */
       
   163 #if __has_feature(objc_generics)
       
   164 @property (copy) NSDictionary<NSString *, NSString *> *httpHeaders;
       
   165 #else
    51 @property (copy) NSDictionary *httpHeaders;
   166 @property (copy) NSDictionary *httpHeaders;
    52 
   167 #endif
       
   168 
       
   169 /*!
       
   170  A property indicating whether or not the user's system profile information is sent when checking for updates.
       
   171 
       
   172  Setting this property will persist in the host bundle's user defaults.
       
   173  */
    53 @property BOOL sendsSystemProfile;
   174 @property BOOL sendsSystemProfile;
    54 
   175 
    55 @property BOOL automaticallyDownloadsUpdates;
   176 /*!
    56 
   177  A property indicating the decryption password used for extracting updates shipped as Apple Disk Images (dmg)
    57 /*!
   178  */
    58     Explicitly checks for updates and displays a progress dialog while doing so.
   179 @property (nonatomic, copy) NSString *decryptionPassword;
    59 
       
    60     This method is meant for a main menu item.
       
    61     Connect any menu item to this action in Interface Builder,
       
    62     and Sparkle will check for updates and report back its findings verbosely
       
    63     when it is invoked.
       
    64  */
       
    65 - (IBAction)checkForUpdates:(id)sender;
       
    66 
       
    67 /*!
       
    68     Checks for updates, but does not display any UI unless an update is found.
       
    69 
       
    70     This is meant for programmatically initating a check for updates. That is,
       
    71     it will display no UI unless it actually finds an update, in which case it
       
    72     proceeds as usual.
       
    73 
       
    74     If the fully automated updating is turned on, however, this will invoke that
       
    75     behavior, and if an update is found, it will be downloaded and prepped for
       
    76     installation.
       
    77  */
       
    78 - (void)checkForUpdatesInBackground;
       
    79 
   180 
    80 /*!
   181 /*!
    81     Checks for updates and, if available, immediately downloads and installs them.
   182     Checks for updates and, if available, immediately downloads and installs them.
    82     A progress dialog is shown but the user will never be prompted to read the
   183     A progress dialog is shown but the user will never be prompted to read the
    83     release notes.
   184     release notes.
    84     
   185 
    85     You may want to respond to the userDidCancelDownload delegate method in case
   186     You may want to respond to the userDidCancelDownload delegate method in case
    86     the user clicks the "Cancel" button while the update is downloading.
   187     the user clicks the "Cancel" button while the update is downloading.
       
   188 
       
   189     If you are writing a UI-less background application, you probably want to instead use
       
   190     SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationInvocation:
    87  */
   191  */
    88 - (void)installUpdatesIfAvailable;
   192 - (void)installUpdatesIfAvailable;
    89 
   193 
    90 /*!
   194 /*!
    91     Returns the date of last update check.
   195     Returns the date of last update check.
    92 
   196 
    93     \returns \c nil if no check has been performed.
   197     \returns \c nil if no check has been performed.
    94  */
   198  */
    95 @property (readonly, copy) NSDate *lastUpdateCheckDate;
   199 @property (readonly, copy) NSDate *lastUpdateCheckDate;
    96 
       
    97 /*!
       
    98     Begins a "probing" check for updates which will not actually offer to
       
    99     update to that version.
       
   100 
       
   101     However, the delegate methods
       
   102     SUUpdaterDelegate::updater:didFindValidUpdate: and
       
   103     SUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
       
   104     so you can use that information in your UI.
       
   105  */
       
   106 - (void)checkForUpdateInformation;
       
   107 
   200 
   108 /*!
   201 /*!
   109     Appropriately schedules or cancels the update checking timer according to
   202     Appropriately schedules or cancels the update checking timer according to
   110     the preferences for time interval and automatic checks.
   203     the preferences for time interval and automatic checks.
   111 
   204 
   112     This call does not change the date of the next check,
   205     This call does not change the date of the next check,
   113     but only the internal NSTimer.
   206     but only the internal NSTimer.
   114  */
   207  */
   115 - (void)resetUpdateCycle;
   208 - (void)resetUpdateCycle;
   116 
   209 
       
   210 /*!
       
   211    A property indicating whether or not an update is in progress.
       
   212 
       
   213    Note this property is not indicative of whether or not user initiated updates can be performed.
       
   214    Use SUUpdater::validateMenuItem: for that instead.
       
   215  */
   117 @property (readonly) BOOL updateInProgress;
   216 @property (readonly) BOOL updateInProgress;
   118 
   217 
   119 @end
   218 @end
   120 
   219 
   121 // -----------------------------------------------------------------------------
       
   122 // SUUpdater Notifications for events that might be interesting to more than just the delegate
       
   123 // The updater will be the notification object
       
   124 // -----------------------------------------------------------------------------
       
   125 SU_EXPORT extern NSString *const SUUpdaterDidFinishLoadingAppCastNotification;
       
   126 SU_EXPORT extern NSString *const SUUpdaterDidFindValidUpdateNotification;
       
   127 SU_EXPORT extern NSString *const SUUpdaterDidNotFindUpdateNotification;
       
   128 SU_EXPORT extern NSString *const SUUpdaterWillRestartNotification;
       
   129 #define SUUpdaterWillRelaunchApplicationNotification SUUpdaterWillRestartNotification;
       
   130 #define SUUpdaterWillInstallUpdateNotification SUUpdaterWillRestartNotification;
       
   131 
       
   132 // Key for the SUAppcastItem object in the SUUpdaterDidFindValidUpdateNotification userInfo
       
   133 SU_EXPORT extern NSString *const SUUpdaterAppcastItemNotificationKey;
       
   134 // Key for the SUAppcast object in the SUUpdaterDidFinishLoadingAppCastNotification userInfo
       
   135 SU_EXPORT extern NSString *const SUUpdaterAppcastNotificationKey;
       
   136 
       
   137 // -----------------------------------------------------------------------------
       
   138 //	SUUpdater Delegate:
       
   139 // -----------------------------------------------------------------------------
       
   140 
       
   141 /*!
       
   142     Provides methods to control the behavior of an SUUpdater object.
       
   143  */
       
   144 @protocol SUUpdaterDelegate <NSObject>
       
   145 @optional
       
   146 
       
   147 /*!
       
   148     Returns whether to allow Sparkle to pop up.
       
   149 
       
   150     For example, this may be used to prevent Sparkle from interrupting a setup assistant.
       
   151 
       
   152     \param updater The SUUpdater instance.
       
   153  */
       
   154 - (BOOL)updaterMayCheckForUpdates:(SUUpdater *)updater;
       
   155 
       
   156 /*!
       
   157     Returns additional parameters to append to the appcast URL's query string.
       
   158 
       
   159     This is potentially based on whether or not Sparkle will also be sending along the system profile.
       
   160 
       
   161     \param updater The SUUpdater instance.
       
   162     \param sendingProfile Whether the system profile will also be sent.
       
   163 
       
   164     \return An array of dictionaries with keys: "key", "value", "displayKey", "displayValue", the latter two being specifically for display to the user.
       
   165  */
       
   166 - (NSArray *)feedParametersForUpdater:(SUUpdater *)updater sendingSystemProfile:(BOOL)sendingProfile;
       
   167 
       
   168 /*!
       
   169     Returns a custom appcast URL.
       
   170 
       
   171     Override this to dynamically specify the entire URL.
       
   172 
       
   173     \param updater The SUUpdater instance.
       
   174  */
       
   175 - (NSString *)feedURLStringForUpdater:(SUUpdater *)updater;
       
   176 
       
   177 /*!
       
   178     Returns whether Sparkle should prompt the user about automatic update checks.
       
   179 
       
   180     Use this to override the default behavior.
       
   181 
       
   182     \param updater The SUUpdater instance.
       
   183  */
       
   184 - (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:(SUUpdater *)updater;
       
   185 
       
   186 /*!
       
   187     Called after Sparkle has downloaded the appcast from the remote server.
       
   188 
       
   189     Implement this if you want to do some special handling with the appcast once it finishes loading.
       
   190 
       
   191     \param updater The SUUpdater instance.
       
   192     \param appcast The appcast that was downloaded from the remote server.
       
   193  */
       
   194 - (void)updater:(SUUpdater *)updater didFinishLoadingAppcast:(SUAppcast *)appcast;
       
   195 
       
   196 /*!
       
   197     Returns the item in the appcast corresponding to the update that should be installed.
       
   198 
       
   199     If you're using special logic or extensions in your appcast,
       
   200     implement this to use your own logic for finding a valid update, if any,
       
   201     in the given appcast.
       
   202 
       
   203     \param appcast The appcast that was downloaded from the remote server.
       
   204     \param updater The SUUpdater instance.
       
   205  */
       
   206 - (SUAppcastItem *)bestValidUpdateInAppcast:(SUAppcast *)appcast forUpdater:(SUUpdater *)updater;
       
   207 
       
   208 /*!
       
   209     Called when a valid update is found by the update driver.
       
   210 
       
   211     \param updater The SUUpdater instance.
       
   212     \param item The appcast item corresponding to the update that is proposed to be installed.
       
   213  */
       
   214 - (void)updater:(SUUpdater *)updater didFindValidUpdate:(SUAppcastItem *)item;
       
   215 
       
   216 /*!
       
   217     Called when a valid update is not found.
       
   218 
       
   219     \param updater The SUUpdater instance.
       
   220  */
       
   221 - (void)updaterDidNotFindUpdate:(SUUpdater *)updater;
       
   222 
       
   223 /*!
       
   224     Called immediately before downloading the specified update.
       
   225 
       
   226     \param updater The SUUpdater instance.
       
   227     \param item The appcast item corresponding to the update that is proposed to be downloaded.
       
   228     \param request The mutable URL request that will be used to download the update.
       
   229  */
       
   230 - (void)updater:(SUUpdater *)updater willDownloadUpdate:(SUAppcastItem *)item withRequest:(NSMutableURLRequest *)request;
       
   231 
       
   232 /*!
       
   233     Called after the specified update failed to download.
       
   234 
       
   235     \param updater The SUUpdater instance.
       
   236     \param item The appcast item corresponding to the update that failed to download.
       
   237     \param error The error generated by the failed download.
       
   238  */
       
   239 - (void)updater:(SUUpdater *)updater failedToDownloadUpdate:(SUAppcastItem *)item error:(NSError *)error;
       
   240 
       
   241 /*!
       
   242     Called when the user clicks the cancel button while and update is being downloaded.
       
   243 
       
   244     \param updater The SUUpdater instance.
       
   245  */
       
   246 - (void)userDidCancelDownload:(SUUpdater *)updater;
       
   247 
       
   248 /*!
       
   249     Called immediately before installing the specified update.
       
   250 
       
   251     \param updater The SUUpdater instance.
       
   252     \param item The appcast item corresponding to the update that is proposed to be installed.
       
   253  */
       
   254 - (void)updater:(SUUpdater *)updater willInstallUpdate:(SUAppcastItem *)item;
       
   255 
       
   256 /*!
       
   257     Returns whether the relaunch should be delayed in order to perform other tasks.
       
   258 
       
   259     This is not called if the user didn't relaunch on the previous update,
       
   260     in that case it will immediately restart.
       
   261 
       
   262     \param updater The SUUpdater instance.
       
   263     \param item The appcast item corresponding to the update that is proposed to be installed.
       
   264     \param invocation The invocation that must be completed before continuing with the relaunch.
       
   265 
       
   266     \return \c YES to delay the relaunch until \p invocation is invoked.
       
   267  */
       
   268 - (BOOL)updater:(SUUpdater *)updater shouldPostponeRelaunchForUpdate:(SUAppcastItem *)item untilInvoking:(NSInvocation *)invocation;
       
   269 
       
   270 /*!
       
   271     Returns whether the application should be relaunched at all.
       
   272 
       
   273     Some apps \b cannot be relaunched under certain circumstances.
       
   274     This method can be used to explicitly prevent a relaunch.
       
   275 
       
   276     \param updater The SUUpdater instance.
       
   277  */
       
   278 - (BOOL)updaterShouldRelaunchApplication:(SUUpdater *)updater;
       
   279 
       
   280 /*!
       
   281     Called immediately before relaunching.
       
   282 
       
   283     \param updater The SUUpdater instance.
       
   284  */
       
   285 - (void)updaterWillRelaunchApplication:(SUUpdater *)updater;
       
   286 
       
   287 /*!
       
   288     Returns an object that compares version numbers to determine their arithmetic relation to each other.
       
   289 
       
   290     This method allows you to provide a custom version comparator.
       
   291     If you don't implement this method or return \c nil,
       
   292     the standard version comparator will be used.
       
   293 
       
   294     \sa SUStandardVersionComparator
       
   295 
       
   296     \param updater The SUUpdater instance.
       
   297  */
       
   298 - (id<SUVersionComparison>)versionComparatorForUpdater:(SUUpdater *)updater;
       
   299 
       
   300 /*!
       
   301     Returns an object that formats version numbers for display to the user.
       
   302 
       
   303     If you don't implement this method or return \c nil,
       
   304     the standard version formatter will be used.
       
   305 
       
   306     \sa SUUpdateAlert
       
   307 
       
   308     \param updater The SUUpdater instance.
       
   309  */
       
   310 - (id<SUVersionDisplay>)versionDisplayerForUpdater:(SUUpdater *)updater;
       
   311 
       
   312 /*!
       
   313     Returns the path which is used to relaunch the client after the update is installed.
       
   314 
       
   315     The default is the path of the host bundle.
       
   316 
       
   317     \param updater The SUUpdater instance.
       
   318  */
       
   319 - (NSString *)pathToRelaunchForUpdater:(SUUpdater *)updater;
       
   320 
       
   321 /*!
       
   322     Called before an updater shows a modal alert window,
       
   323     to give the host the opportunity to hide attached windows that may get in the way.
       
   324 
       
   325     \param updater The SUUpdater instance.
       
   326  */
       
   327 - (void)updaterWillShowModalAlert:(SUUpdater *)updater;
       
   328 
       
   329 /*!
       
   330     Called after an updater shows a modal alert window,
       
   331     to give the host the opportunity to hide attached windows that may get in the way.
       
   332 
       
   333     \param updater The SUUpdater instance.
       
   334  */
       
   335 - (void)updaterDidShowModalAlert:(SUUpdater *)updater;
       
   336 
       
   337 /*!
       
   338     Called when an update is scheduled to be silently installed on quit.
       
   339 
       
   340     \param updater The SUUpdater instance.
       
   341     \param item The appcast item corresponding to the update that is proposed to be installed.
       
   342     \param invocation Can be used to trigger an immediate silent install and relaunch.
       
   343  */
       
   344 - (void)updater:(SUUpdater *)updater willInstallUpdateOnQuit:(SUAppcastItem *)item immediateInstallationInvocation:(NSInvocation *)invocation;
       
   345 
       
   346 /*!
       
   347     Calls after an update that was scheduled to be silently installed on quit has been canceled.
       
   348 
       
   349     \param updater The SUUpdater instance.
       
   350     \param item The appcast item corresponding to the update that was proposed to be installed.
       
   351  */
       
   352 - (void)updater:(SUUpdater *)updater didCancelInstallUpdateOnQuit:(SUAppcastItem *)item;
       
   353 
       
   354 /*!
       
   355     Called after an update is aborted due to an error.
       
   356 
       
   357     \param updater The SUUpdater instance.
       
   358     \param error The error that caused the abort
       
   359  */
       
   360 - (void)updater:(SUUpdater *)updater didAbortWithError:(NSError *)error;
       
   361 
       
   362 @end
       
   363 
       
   364 #endif
   220 #endif