Frameworks/Sparkle.framework/Versions/A/Headers/SUUpdaterDelegate.h
branchadium-1.5.10.4
changeset 5985 5883c460b8cb
equal deleted inserted replaced
5984:c42b73c02750 5985:5883c460b8cb
       
     1 //
       
     2 //  SUUpdaterDelegate.h
       
     3 //  Sparkle
       
     4 //
       
     5 //  Created by Mayur Pawashe on 12/25/16.
       
     6 //  Copyright © 2016 Sparkle Project. All rights reserved.
       
     7 //
       
     8 
       
     9 #if __has_feature(modules)
       
    10 @import Foundation;
       
    11 #else
       
    12 #import <Foundation/Foundation.h>
       
    13 #endif
       
    14 
       
    15 #import "SUExport.h"
       
    16 
       
    17 @protocol SUVersionComparison, SUVersionDisplay;
       
    18 @class SUUpdater, SUAppcast, SUAppcastItem;
       
    19 
       
    20 NS_ASSUME_NONNULL_BEGIN
       
    21 
       
    22 // -----------------------------------------------------------------------------
       
    23 // SUUpdater Notifications for events that might be interesting to more than just the delegate
       
    24 // The updater will be the notification object
       
    25 // -----------------------------------------------------------------------------
       
    26 SU_EXPORT extern NSString *const SUUpdaterDidFinishLoadingAppCastNotification;
       
    27 SU_EXPORT extern NSString *const SUUpdaterDidFindValidUpdateNotification;
       
    28 SU_EXPORT extern NSString *const SUUpdaterDidNotFindUpdateNotification;
       
    29 SU_EXPORT extern NSString *const SUUpdaterWillRestartNotification;
       
    30 #define SUUpdaterWillRelaunchApplicationNotification SUUpdaterWillRestartNotification;
       
    31 #define SUUpdaterWillInstallUpdateNotification SUUpdaterWillRestartNotification;
       
    32 
       
    33 // Key for the SUAppcastItem object in the SUUpdaterDidFindValidUpdateNotification userInfo
       
    34 SU_EXPORT extern NSString *const SUUpdaterAppcastItemNotificationKey;
       
    35 // Key for the SUAppcast object in the SUUpdaterDidFinishLoadingAppCastNotification userInfo
       
    36 SU_EXPORT extern NSString *const SUUpdaterAppcastNotificationKey;
       
    37 
       
    38 // -----------------------------------------------------------------------------
       
    39 //	SUUpdater Delegate:
       
    40 // -----------------------------------------------------------------------------
       
    41 
       
    42 /*!
       
    43  Provides methods to control the behavior of an SUUpdater object.
       
    44  */
       
    45 @protocol SUUpdaterDelegate <NSObject>
       
    46 @optional
       
    47 
       
    48 /*!
       
    49  Returns whether to allow Sparkle to pop up.
       
    50  
       
    51  For example, this may be used to prevent Sparkle from interrupting a setup assistant.
       
    52  
       
    53  \param updater The SUUpdater instance.
       
    54  */
       
    55 - (BOOL)updaterMayCheckForUpdates:(SUUpdater *)updater;
       
    56 
       
    57 /*!
       
    58  Returns additional parameters to append to the appcast URL's query string.
       
    59  
       
    60  This is potentially based on whether or not Sparkle will also be sending along the system profile.
       
    61  
       
    62  \param updater The SUUpdater instance.
       
    63  \param sendingProfile Whether the system profile will also be sent.
       
    64  
       
    65  \return An array of dictionaries with keys: "key", "value", "displayKey", "displayValue", the latter two being specifically for display to the user.
       
    66  */
       
    67 #if __has_feature(objc_generics)
       
    68 - (NSArray<NSDictionary<NSString *, NSString *> *> *)feedParametersForUpdater:(SUUpdater *)updater sendingSystemProfile:(BOOL)sendingProfile;
       
    69 #else
       
    70 - (NSArray *)feedParametersForUpdater:(SUUpdater *)updater sendingSystemProfile:(BOOL)sendingProfile;
       
    71 #endif
       
    72 
       
    73 /*!
       
    74  Returns a custom appcast URL.
       
    75  
       
    76  Override this to dynamically specify the entire URL.
       
    77  
       
    78  An alternative may be to use SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
       
    79  and let the server handle what kind of feed to provide.
       
    80  
       
    81  \param updater The SUUpdater instance.
       
    82  */
       
    83 - (nullable NSString *)feedURLStringForUpdater:(SUUpdater *)updater;
       
    84 
       
    85 /*!
       
    86  Returns whether Sparkle should prompt the user about automatic update checks.
       
    87  
       
    88  Use this to override the default behavior.
       
    89  
       
    90  \param updater The SUUpdater instance.
       
    91  */
       
    92 - (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:(SUUpdater *)updater;
       
    93 
       
    94 /*!
       
    95  Called after Sparkle has downloaded the appcast from the remote server.
       
    96  
       
    97  Implement this if you want to do some special handling with the appcast once it finishes loading.
       
    98  
       
    99  \param updater The SUUpdater instance.
       
   100  \param appcast The appcast that was downloaded from the remote server.
       
   101  */
       
   102 - (void)updater:(SUUpdater *)updater didFinishLoadingAppcast:(SUAppcast *)appcast;
       
   103 
       
   104 /*!
       
   105  Returns the item in the appcast corresponding to the update that should be installed.
       
   106  
       
   107  If you're using special logic or extensions in your appcast,
       
   108  implement this to use your own logic for finding a valid update, if any,
       
   109  in the given appcast.
       
   110  
       
   111  \param appcast The appcast that was downloaded from the remote server.
       
   112  \param updater The SUUpdater instance.
       
   113  */
       
   114 - (nullable SUAppcastItem *)bestValidUpdateInAppcast:(SUAppcast *)appcast forUpdater:(SUUpdater *)updater;
       
   115 
       
   116 /*!
       
   117  Called when a valid update is found by the update driver.
       
   118  
       
   119  \param updater The SUUpdater instance.
       
   120  \param item The appcast item corresponding to the update that is proposed to be installed.
       
   121  */
       
   122 - (void)updater:(SUUpdater *)updater didFindValidUpdate:(SUAppcastItem *)item;
       
   123 
       
   124 /*!
       
   125  Called when a valid update is not found.
       
   126  
       
   127  \param updater The SUUpdater instance.
       
   128  */
       
   129 - (void)updaterDidNotFindUpdate:(SUUpdater *)updater;
       
   130 
       
   131 /*!
       
   132  Called immediately before downloading the specified update.
       
   133  
       
   134  \param updater The SUUpdater instance.
       
   135  \param item The appcast item corresponding to the update that is proposed to be downloaded.
       
   136  \param request The mutable URL request that will be used to download the update.
       
   137  */
       
   138 - (void)updater:(SUUpdater *)updater willDownloadUpdate:(SUAppcastItem *)item withRequest:(NSMutableURLRequest *)request;
       
   139 
       
   140 /*!
       
   141  Called after the specified update failed to download.
       
   142  
       
   143  \param updater The SUUpdater instance.
       
   144  \param item The appcast item corresponding to the update that failed to download.
       
   145  \param error The error generated by the failed download.
       
   146  */
       
   147 - (void)updater:(SUUpdater *)updater failedToDownloadUpdate:(SUAppcastItem *)item error:(NSError *)error;
       
   148 
       
   149 /*!
       
   150  Called when the user clicks the cancel button while and update is being downloaded.
       
   151  
       
   152  \param updater The SUUpdater instance.
       
   153  */
       
   154 - (void)userDidCancelDownload:(SUUpdater *)updater;
       
   155 
       
   156 /*!
       
   157  Called immediately before installing the specified update.
       
   158  
       
   159  \param updater The SUUpdater instance.
       
   160  \param item The appcast item corresponding to the update that is proposed to be installed.
       
   161  */
       
   162 - (void)updater:(SUUpdater *)updater willInstallUpdate:(SUAppcastItem *)item;
       
   163 
       
   164 /*!
       
   165  Returns whether the relaunch should be delayed in order to perform other tasks.
       
   166  
       
   167  This is not called if the user didn't relaunch on the previous update,
       
   168  in that case it will immediately restart.
       
   169  
       
   170  \param updater The SUUpdater instance.
       
   171  \param item The appcast item corresponding to the update that is proposed to be installed.
       
   172  \param invocation The invocation that must be completed with `[invocation invoke]` before continuing with the relaunch.
       
   173  
       
   174  \return \c YES to delay the relaunch until \p invocation is invoked.
       
   175  */
       
   176 - (BOOL)updater:(SUUpdater *)updater shouldPostponeRelaunchForUpdate:(SUAppcastItem *)item untilInvoking:(NSInvocation *)invocation;
       
   177 
       
   178 /*!
       
   179  Returns whether the application should be relaunched at all.
       
   180  
       
   181  Some apps \b cannot be relaunched under certain circumstances.
       
   182  This method can be used to explicitly prevent a relaunch.
       
   183  
       
   184  \param updater The SUUpdater instance.
       
   185  */
       
   186 - (BOOL)updaterShouldRelaunchApplication:(SUUpdater *)updater;
       
   187 
       
   188 /*!
       
   189  Called immediately before relaunching.
       
   190  
       
   191  \param updater The SUUpdater instance.
       
   192  */
       
   193 - (void)updaterWillRelaunchApplication:(SUUpdater *)updater;
       
   194 
       
   195 /*!
       
   196  Returns an object that compares version numbers to determine their arithmetic relation to each other.
       
   197  
       
   198  This method allows you to provide a custom version comparator.
       
   199  If you don't implement this method or return \c nil,
       
   200  the standard version comparator will be used.
       
   201  
       
   202  \sa SUStandardVersionComparator
       
   203  
       
   204  \param updater The SUUpdater instance.
       
   205  */
       
   206 - (nullable id<SUVersionComparison>)versionComparatorForUpdater:(SUUpdater *)updater;
       
   207 
       
   208 /*!
       
   209  Returns an object that formats version numbers for display to the user.
       
   210  
       
   211  If you don't implement this method or return \c nil,
       
   212  the standard version formatter will be used.
       
   213  
       
   214  \sa SUUpdateAlert
       
   215  
       
   216  \param updater The SUUpdater instance.
       
   217  */
       
   218 - (nullable id<SUVersionDisplay>)versionDisplayerForUpdater:(SUUpdater *)updater;
       
   219 
       
   220 /*!
       
   221  Returns the path which is used to relaunch the client after the update is installed.
       
   222  
       
   223  The default is the path of the host bundle.
       
   224  
       
   225  \param updater The SUUpdater instance.
       
   226  */
       
   227 - (nullable NSString *)pathToRelaunchForUpdater:(SUUpdater *)updater;
       
   228 
       
   229 /*!
       
   230  Called before an updater shows a modal alert window,
       
   231  to give the host the opportunity to hide attached windows that may get in the way.
       
   232  
       
   233  \param updater The SUUpdater instance.
       
   234  */
       
   235 - (void)updaterWillShowModalAlert:(SUUpdater *)updater;
       
   236 
       
   237 /*!
       
   238  Called after an updater shows a modal alert window,
       
   239  to give the host the opportunity to hide attached windows that may get in the way.
       
   240  
       
   241  \param updater The SUUpdater instance.
       
   242  */
       
   243 - (void)updaterDidShowModalAlert:(SUUpdater *)updater;
       
   244 
       
   245 /*!
       
   246  Called when an update is scheduled to be silently installed on quit.
       
   247  This is after an update has been automatically downloaded in the background.
       
   248  (i.e. SUUpdater::automaticallyDownloadsUpdates is YES)
       
   249  
       
   250  \param updater The SUUpdater instance.
       
   251  \param item The appcast item corresponding to the update that is proposed to be installed.
       
   252  \param invocation Can be used to trigger an immediate silent install and relaunch.
       
   253  */
       
   254 - (void)updater:(SUUpdater *)updater willInstallUpdateOnQuit:(SUAppcastItem *)item immediateInstallationInvocation:(NSInvocation *)invocation;
       
   255 
       
   256 /*!
       
   257  Calls after an update that was scheduled to be silently installed on quit has been canceled.
       
   258  
       
   259  \param updater The SUUpdater instance.
       
   260  \param item The appcast item corresponding to the update that was proposed to be installed.
       
   261  */
       
   262 - (void)updater:(SUUpdater *)updater didCancelInstallUpdateOnQuit:(SUAppcastItem *)item;
       
   263 
       
   264 /*!
       
   265  Called after an update is aborted due to an error.
       
   266  
       
   267  \param updater The SUUpdater instance.
       
   268  \param error The error that caused the abort
       
   269  */
       
   270 - (void)updater:(SUUpdater *)updater didAbortWithError:(NSError *)error;
       
   271 
       
   272 @end
       
   273 
       
   274 NS_ASSUME_NONNULL_END