/core/externals/update-engine/Core/KSUpdateEngine.h
C++ Header | 326 lines | 90 code | 48 blank | 188 comment | 0 complexity | 074a83bdf6229e55baea2a8651415ea2 MD5 | raw file
1// Copyright 2008 Google Inc. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15#import <Foundation/Foundation.h> 16 17// Treat this header like a top-level framework header, and include 18// everything a typical client might want to use. 19#import "KSCommandRunner.h" 20#import "KSExistenceChecker.h" 21#import "KSMemoryTicketStore.h" 22#import "KSStatsCollection.h" 23#import "KSTicket.h" 24#import "KSTicketStore.h" 25#import "KSUpdateInfo.h" 26 27@class KSAction, KSActionProcessor; 28 29// KSUpdateEngine (protocol) 30// 31// Methods of a KSUpdateEngine that are safe to expose on a vended object over 32// distributed objects (DO). This protocol simply lists the methods and any 33// DO-specific properties (e.g., bycopy, inout) about the methods. Please see 34// the actual method declarations in KSUpdateEngine (below) for details about 35// the methods' semantics, arguments, and return values. 36@protocol KSUpdateEngine <NSObject> 37- (id)delegate; 38- (void)setDelegate:(in byref id)delegate; 39- (void)updateAllProducts; 40- (void)updateProductWithProductID:(in bycopy NSString *)productID; 41- (BOOL)isUpdating; 42- (void)stopAndReset; 43- (void)setParams:(in bycopy NSDictionary *)params; 44- (void)setStatsCollection:(in byref KSStatsCollection *)statsCollection; 45@end 46 47 48// KSUpdateEngine (class) 49// 50// This is the main class for interfacing with UpdateEngine.framework. Clients 51// of the UpdateEngine.framework, such as UpdateEngineAgent, should only need to 52// interact with this one class. 53// 54// Typically, this class will be used to kick off a check for updates for all 55// products, a specific product, or simply to return YES/NO whether an update 56// is available (not yet implemented). A typical usage scenario to check for 57// updates for all tickets, and install those updates may simly look like: 58// 59// id delegate = ... get/create a delegate ... 60// KSUpdateEngine *engine = [KSUpdateEngine engineWithDelegate:delegate]; 61// [engine updateProducts]; // Runs asynchronously 62// 63@interface KSUpdateEngine : NSObject <KSUpdateEngine> { 64 @private 65 KSTicketStore *store_; 66 KSActionProcessor *processor_; 67 NSDictionary *params_; 68 BOOL wasSuccessful_; 69 id delegate_; // weak 70 NSMutableDictionary *stats_; // ProductID -> dictionary of stats. 71} 72 73// Returns the path to the default ticket store if one was set. If one was not 74// set, this method will return nil. 75+ (NSString *)defaultTicketStorePath; 76 77// Overrides the default ticket store path to be |path|. This method is useful 78// for testing because it allows you to change what the system thinks is the 79// default path. 80+ (void)setDefaultTicketStorePath:(NSString *)path; 81 82// A convenience method for creating an autoreleased KSUpdateEngine instance 83// that will use the default ticket store and the specified |delegate|. 84+ (id)engineWithDelegate:(id)delegate; 85 86// A convenience method for creating an autoreleased KSUpdateEngine instance 87// that will use the specified ticket |store| and |delegate|. 88+ (id)engineWithTicketStore:(KSTicketStore *)store delegate:(id)delegate; 89 90// The designated initializer. This method returns a KSUpdateEngine instance 91// that will use the specified ticket |store| and |delegate|. 92- (id)initWithTicketStore:(KSTicketStore *)store delegate:(id)delegate; 93 94// Returns the KSTicketStore that this KSUpdateEngine is using. 95- (KSTicketStore *)ticketStore; 96 97// Returns this KSUpdateEngine's delegate. 98- (id)delegate; 99 100// Sets this KSUpdateEngine's delegate. nil is allowed, in which case no 101// delegate is used. 102- (void)setDelegate:(id)delegate; 103 104// Triggers an update check for all products identified by a ticket in this 105// instance's ticket store. Products whose ticket's existence checker indicates 106// that the product is no longer installed will be ignored. 107- (void)updateAllProducts; 108 109// Triggers an update check for just the one product identified by |productID|. 110// Other products are ignored. If the product's ticket's existence checker 111// indicates that the product is no longer installed, it will be ignored. 112- (void)updateProductWithProductID:(NSString *)productID; 113 114// Returns YES if this KSUpdateEngine is currently doing an udpate check. 115- (BOOL)isUpdating; 116 117// Immediately cancels all updates that may be going on currently, and clears 118// all pending actions in the action processor. This call resets the 119// KSUpdateEngine to its initial state. 120- (void)stopAndReset; 121 122// Configure this KSUpdateEngine with a dictionary of parameters indexed 123// by the keys in KSUpdateEngineParameters.h. 124- (void)setParams:(NSDictionary *)params; 125 126// Get the engine's parameters. 127- (NSDictionary *)params; 128 129// Returns the GTMStatsCollection that the UpdateEngine framework is using for 130// recording stats. Will be nil if one was never set. 131- (KSStatsCollection *)statsCollection; 132 133// Sets the stats collector for the UpdateEngine framework to use. 134- (void)setStatsCollection:(KSStatsCollection *)stats; 135 136@end // KSUpdateEngine 137 138 139// KSUpdateEngineDelegateMethods 140// 141// These are methods that a KSUpdateEngine delegate may implement. There 142// are no required methods, and optional methods will have some reasonable 143// default action if not implemented. 144// 145// The methods are listed in the relative order in which they're called. 146@interface KSUpdateEngine (KSUpdateEngineDelegateMethods) 147 148// Called when UpdateEngine starts processing an update request. 149// 150// Optional. 151- (void)engineStarted:(KSUpdateEngine *)engine; 152 153// Called when there is out-of-band data provided by the server 154// classes. |oob| is a dictionary, keyed by the server URL (an an 155// NSString), whose value is a dictionary of data provided by the 156// class. The contents of the value dictionary varies by server class 157// (if provided at all). If there is no OOB data provided by server 158// classes, this method is not called. 159// 160// Optional. 161- (void)engine:(KSUpdateEngine *)engine hasOutOfBandData:(NSDictionary *)oob; 162 163// Called when a KSServer has some information to report about the product. 164// This method is typically called before the update infos are generated, and 165// can return information for a product that doesn't have an update (hence 166// no update infos flowing through the system). 167// |serverData| is some object value from the server. 168// |productID| is the product that the data concerns 169// |key| is what kind of value it is. 170// KSOmahaServer, for instance, returns "Product active key" information 171// through this route. 172// 173// Optional. 174- (void)engine:(KSUpdateEngine *)engine 175 serverData:(id)stuff 176 forProductID:(NSString *)productID 177 withKey:(NSString *)key; 178 179// Sent to the delegate for each ticket's |productID| when |engine| 180// wants to know about per-product stats. The delegate should return 181// a dictionary containing any of the product stat dictionary keys 182// from KSUpdateEngineParameters.h, such as an NSNumber boxed BOOL 183// stored with the key kUpdateEngineProductStatsActive. 184// 185// If the delegate has no stats to report for this product, it can return 186// nil or an empty dictionary. 187// 188// Optional. 189- (NSDictionary *)engine:(KSUpdateEngine *)engine 190 statsForProductID:(NSString *)productID; 191 192// Sent to the UpdateEngine delegate when product updates are available. The 193// |products| array is an array of NSDictionaries, each of with has keys defined 194// in KSServer.h. The delegate must return an array containing the product 195// dictionaries for the products which are to be prefetched (i.e., downloaded 196// before possibly prompting the user about the update). The two most common 197// return values for this delegate method are the following: 198// 199// nil = Don't prefetch anything (same as empty array) 200// products = Prefetch all of the products (this is the default) 201// 202// Optional - if not implemented, the return value is |products|. 203- (NSArray *)engine:(KSUpdateEngine *)engine 204 shouldPrefetchProducts:(NSArray *)products; 205 206// Sent to the UpdateEngine delegate when product updates are available. The 207// |products| array is an array of KSUpdateInfos, each of with has keys defined 208// in KSUpdateInfo.h. The delegate should return an array of the products from 209// the |products| list that should be installed silently. 210// 211// Optional - if not implemented, the return value is |products|. 212- (NSArray *)engine:(KSUpdateEngine *)engine 213 shouldSilentlyUpdateProducts:(NSArray *)products; 214 215// Returns a KSCommandRunner instance that can run commands on the delegates 216// behalf. UpdateEngine may call this method multiple times to get a 217// KSCommandRunner for running UpdateEngine preinstall and UpdateEngine 218// postinstall scripts (see KSInstallAction for more details on these scripts). 219// 220// Should you implement this method, it should most likely look like 221// the following: 222// 223// - (id<KSCommandRunner>)commandRunnerForEngine:(KSUpdateEngine *)engine { 224// return [KSTaskCommandRunner commandRunner]; 225// } 226// 227// Optional - if not implemented, a KSTaskCommandRunner is created. 228- (id<KSCommandRunner>)commandRunnerForEngine:(KSUpdateEngine *)engine; 229 230// Sent by |engine| when the update as defined by |updateInfo| starts. 231// 232// Optional. 233- (void)engine:(KSUpdateEngine *)engine 234 starting:(KSUpdateInfo *)updateInfo; 235 236// Sent by |engine| when we have progress for |updateInfo|. 237// |progress| is a float that specifies completeness, from 0.0 to 1.0. 238// 239// Optional. 240- (void)engine:(KSUpdateEngine *)engine 241 running:(KSUpdateInfo *)updateInfo 242 progress:(NSNumber *)progress; 243 244// Sent by |engine| when the update as defined by |updateInfo| has finished. 245// |wasSuccess| indicates whether the update was successful, and |wantsReboot| 246// indicates whether the update requested that the machine be rebooted. 247// 248// Optional. 249- (void)engine:(KSUpdateEngine *)engine 250 finished:(KSUpdateInfo *)updateInfo 251 wasSuccess:(BOOL)wasSuccess 252 wantsReboot:(BOOL)wantsReboot; 253 254// Sent to the UpdateEngine delegate when product updates are available. The 255// |products| array is an array of KSUpdateInfos, each of with has keys defined 256// in KSUpdateInfo.h. The delegate can use this list of products to optionally 257// display UI and ask the user what they want to install, or whatever. The 258// return value should be an array containing the product dictionaries that 259// should be updated. If a delegate simply wants to install all of the updates 260// they can trivially implement this method to immediately return the same 261// |products| array that they were given. 262// 263// Optional - if not implemented, the return value is |products|. 264- (NSArray *)engine:(KSUpdateEngine *)engine 265 shouldUpdateProducts:(NSArray *)products; 266 267// Called when UpdateEngine is finished processing an update request. 268// |wasSuccess| indicates whether the update check was successful or not. An 269// update will fail if, for example, there is no network connection. It will NOT 270// fail if an update was downloaded and that update's installer happened to 271// fail. 272// 273// Optional. 274- (void)engineFinished:(KSUpdateEngine *)engine wasSuccess:(BOOL)wasSuccess; 275 276@end // KSUpdateEngineDelegateMethods 277 278 279// KSUpdateEngineActionPrivateCallbackMethods 280// 281// These methods provide a way for KSActions created by this KSUpdateEngine to 282// indirectly communicate with this KSUpdateEngine's delegate. Clients of 283// KSUpdateEngine should *NEVER* call these methods directly. Consider them to 284// be private. 285// 286@interface KSUpdateEngine (KSUpdateEngineActionPrivateCallbackMethods) 287 288// Calls the KSUpdateEngine delegate's -engine:shouldPrefetchProducts: 289// method if it is implemented. Otherwise, the |products| argument is 290// returned. 291- (NSArray *)action:(KSAction *)action 292 shouldPrefetchProducts:(NSArray *)products; 293 294// Calls the KSUpdateEngine delegate's -engine:shouldSilentlyUpdateProducts: 295// method if the delegate implements it. Otherwise, the |products| argument is 296// returned. 297- (NSArray *)action:(KSAction *)action 298 shouldSilentlyUpdateProducts:(NSArray *)products; 299 300// Calls the KSUpdateEngine delegate's -commandRunnerForEngine: method. 301// If the delegate does not implement -commandRunnerForEngine:, a new 302// KSCommandRunner will be created. 303- (id<KSCommandRunner>)commandRunnerForAction:(KSAction *)action; 304 305// Calls the KSUpdateEngine delegate's -engine:starting: method. 306- (void)action:(KSAction *)action 307 starting:(KSUpdateInfo *)updateInfo; 308 309// Calls the KSUpdateEngine delegate's -engine:running:progress: method. 310- (void)action:(KSAction *)action 311 running:(KSUpdateInfo *)updateInfo 312 progress:(NSNumber *)progress; 313 314// Calls the KSUpdateEngine delegate's -engine:finished:wasSuccess:wantsReboot: 315// method. 316- (void)action:(KSAction *)action 317 finished:(KSUpdateInfo *)updateInfo 318 wasSuccess:(BOOL)wasSuccess 319 wantsReboot:(BOOL)wantsReboot; 320 321// Calls the KSUpdateEngine delegate's -engine:shouldUpdateProducts: method if 322// the delegate implements it. Otherwise, the |products| argument is returned. 323- (NSArray *)action:(KSAction *)action 324 shouldUpdateProducts:(NSArray *)products; 325 326@end // KSUpdateEngineActionPrivateCallbackMethods