1 // Copyright 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_
6 #define CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_
11 #include "base/version.h"
17 class DictionaryValue;
22 class URLRequestContextGetter;
27 class ResourceThrottle;
30 namespace component_updater {
33 class ComponentPatcher;
35 // Component specific installers must derive from this class and implement
36 // OnUpdateError() and Install(). A valid instance of this class must be
37 // given to ComponentUpdateService::RegisterComponent().
38 class ComponentInstaller {
40 // Called by the component updater on the UI thread when there was a
41 // problem unpacking or verifying the component. |error| is a non-zero
42 // value which is only meaningful to the component updater.
43 virtual void OnUpdateError(int error) = 0;
45 // Called by the component updater when a component has been unpacked
46 // and is ready to be installed. |manifest| contains the CRX manifest
47 // json dictionary and |unpack_path| contains the temporary directory
48 // with all the unpacked CRX files.
49 virtual bool Install(const base::DictionaryValue& manifest,
50 const base::FilePath& unpack_path) = 0;
52 // Set |installed_file| to the full path to the installed |file|. |file| is
53 // the filename of the file in this component's CRX. Returns false if this is
54 // not possible (the file has been removed or modified, or its current
55 // location is unknown). Otherwise, returns true.
56 virtual bool GetInstalledFile(const std::string& file,
57 base::FilePath* installed_file) = 0;
59 virtual ~ComponentInstaller() {}
62 // Defines an interface to observe a CrxComponent.
63 class ComponentObserver {
66 // Sent when the component updater starts doing update checks.
67 COMPONENT_UPDATER_STARTED,
69 // Sent when the component updater is going to take a long nap.
70 COMPONENT_UPDATER_SLEEPING,
72 // Sent when there is a new version of a registered component. After
73 // the notification is sent the component will be downloaded.
74 COMPONENT_UPDATE_FOUND,
76 // Sent when the new component has been downloaded and an installation
77 // or upgrade is about to be attempted.
78 COMPONENT_UPDATE_READY,
80 // Sent when a component has been successfully updated.
83 // Sent when a component has not been updated following an update check:
84 // either there was no update available, or an update failed.
85 COMPONENT_NOT_UPDATED,
88 virtual ~ComponentObserver() {}
90 // The component updater service will call this function when an interesting
91 // event happens for a specific component. |extra| is |event| dependent.
92 virtual void OnEvent(Events event, int extra) = 0;
95 // Describes a particular component that can be installed or updated. This
96 // structure is required to register a component with the component updater.
97 // |pk_hash| is the SHA256 hash of the component's public key. If the component
98 // is to be installed then version should be "0" or "0.0", else it should be
99 // the current version. |observer|, |fingerprint|, and |name| are optional.
100 // |allow_background_download| specifies that the component can be background
101 // downloaded in some cases. The default for this value is |true| and the value
102 // can be overriden at the registration time. This is a temporary change until
103 // the issue 340448 is resolved.
104 struct CrxComponent {
105 std::vector<uint8> pk_hash;
106 ComponentInstaller* installer;
107 ComponentObserver* observer;
109 std::string fingerprint;
111 bool allow_background_download;
116 // Convenience structure to use with component listing / enumeration.
117 struct CrxComponentInfo {
118 // |id| is currently derived from |CrxComponent.pk_hash|, see rest of the
119 // class implementation for details.
127 // The component update service is in charge of installing or upgrading
128 // select parts of chrome. Each part is called a component and managed by
129 // instances of CrxComponent registered using RegisterComponent(). On the
130 // server, each component is packaged as a CRX which is the same format used
131 // to package extensions. To the update service each component is identified
132 // by its public key hash (CrxComponent::pk_hash). If there is an update
133 // available and its version is bigger than (CrxComponent::version), it will
134 // be downloaded, verified and unpacked. Then component-specific installer
135 // ComponentInstaller::Install (of CrxComponent::installer) will be called.
137 // During the normal operation of the component updater some specific
138 // notifications are fired, like COMPONENT_UPDATER_STARTED and
139 // COMPONENT_UPDATE_FOUND. See notification_type.h for more details.
141 // All methods are safe to call ONLY from chrome's UI thread.
142 class ComponentUpdateService {
150 // Controls the component updater behavior.
153 virtual ~Configurator() {}
154 // Delay in seconds from calling Start() to the first update check.
155 virtual int InitialDelay() = 0;
156 // Delay in seconds to every subsequent update check. 0 means don't check.
157 virtual int NextCheckDelay() = 0;
158 // Delay in seconds from each task step. Used to smooth out CPU/IO usage.
159 virtual int StepDelay() = 0;
160 // Delay in seconds between applying updates for different components, if
161 // several updates are available at a given time.
162 virtual int StepDelayMedium() = 0;
163 // Minimum delta time in seconds before checking again the same component.
164 virtual int MinimumReCheckWait() = 0;
165 // Minimum delta time in seconds before an on-demand check is allowed
166 // for the same component.
167 virtual int OnDemandDelay() = 0;
168 // The url that is going to be used update checks over Omaha protocol.
169 virtual GURL UpdateUrl() = 0;
170 // The url where the completion pings are sent. Invalid if and only if
171 // pings are disabled.
172 virtual GURL PingUrl() = 0;
173 // Parameters added to each url request. It can be null if none are needed.
174 virtual std::string ExtraRequestParams() = 0;
175 // How big each update request can be. Don't go above 2000.
176 virtual size_t UrlSizeLimit() = 0;
177 // The source of contexts for all the url requests.
178 virtual net::URLRequestContextGetter* RequestContext() = 0;
179 // True means that all ops are performed in this process.
180 virtual bool InProcess() = 0;
181 // Creates a new ComponentPatcher in a platform-specific way. This is useful
182 // for dependency injection.
183 virtual ComponentPatcher* CreateComponentPatcher() = 0;
184 // True means that this client can handle delta updates.
185 virtual bool DeltasEnabled() const = 0;
186 // True means that the background downloader can be used for downloading
187 // non on-demand components.
188 virtual bool UseBackgroundDownloader() const = 0;
191 // Start doing update checks and installing new versions of registered
192 // components after Configurator::InitialDelay() seconds.
193 virtual Status Start() = 0;
195 // Stop doing update checks. In-flight requests and pending installations
196 // will not be canceled.
197 virtual Status Stop() = 0;
199 // Add component to be checked for updates. You can call this method
200 // before calling Start().
201 virtual Status RegisterComponent(const CrxComponent& component) = 0;
203 // Returns a list of registered components.
204 virtual void GetComponents(std::vector<CrxComponentInfo>* components) = 0;
206 // Returns a network resource throttle. It means that a component will be
207 // downloaded and installed before the resource is unthrottled. This is the
208 // only function callable from the IO thread.
209 virtual content::ResourceThrottle* GetOnDemandResourceThrottle(
210 net::URLRequest* request, const std::string& crx_id) = 0;
212 virtual ~ComponentUpdateService() {}
214 friend class ::ComponentsUI;
215 friend class OnDemandTester;
218 // Ask the component updater to do an update check for a previously
219 // registered component, immediately. If an update or check is already
220 // in progress, returns |kInProgress|.
221 // There is no guarantee that the item will actually be updated,
222 // since an update may not be available. Listeners for the component will
223 // know the outcome of the check.
224 virtual Status OnDemandUpdate(const std::string& component_id) = 0;
227 // Creates the component updater. You must pass a valid |config| allocated on
228 // the heap which the component updater will own.
229 ComponentUpdateService* ComponentUpdateServiceFactory(
230 ComponentUpdateService::Configurator* config);
232 } // namespace component_updater
234 #endif // CHROME_BROWSER_COMPONENT_UPDATER_COMPONENT_UPDATER_SERVICE_H_