/core/externals/update-engine/Core/KSUpdateEngine.h

  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