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

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