extensions/browser/updater/extension_downloader_delegate.h - chromium/src - Git at Google

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_
 #define EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_

 #include <set>
 #include <string>

 #include "base/callback.h"
 #include "base/time/time.h"
 #include "extensions/browser/crx_file_info.h"
 #include "extensions/browser/updater/manifest_fetch_data.h"

 class GURL;

 namespace extensions {

 class ExtensionDownloaderDelegate {
  public:
   virtual ~ExtensionDownloaderDelegate();

   // Passed as an argument to ExtensionDownloader::OnExtensionDownloadFailed()
   // to detail the reason for the failure.
   enum Error {
     // Background networking is disabled.
     DISABLED,

     // Failed to fetch the manifest for this extension.
     MANIFEST_FETCH_FAILED,

     // The manifest couldn't be parsed.
     MANIFEST_INVALID,

     // The manifest was fetched and parsed, and there are no updates for
     // this extension.
     NO_UPDATE_AVAILABLE,

     // There was an update for this extension but the download of the crx
     // failed.
     CRX_FETCH_FAILED,
   };

   // Passed as an argument OnExtensionDownloadStageChanged() to detail how
   // downloading is going on. Typical sequence is: PENDING ->
   // QUEUED_FOR_MANIFEST -> DOWNLOADING_MANIFEST -> PARSING_MANIFEST ->
   // MANIFEST_LOADED -> QUEUED_FOR_CRX -> DOWNLOADING_CRX -> FINISHED. Stages
   // QUEUED_FOR_MANIFEST and QUEUED_FOR_CRX are optional and may be skipped.
   // Failure on any stage will result in skipping all remained stages, moving to
   // FINISHED instantly. Special stages DOWNLOADING_MANIFEST_RETRY and
   // DOWNLOADING_CRX_RETRY are similar to QUEUED_* ones, but signify that
   // download failed at least once already. So, this may result in sequence like
   // ... -> MANIFEST_LOADED -> QUEUED_FOR_CRX -> DOWNLOADING_CRX ->
   // DOWNLOADING_CRX_RETRY -> DOWNLOADING_CRX -> FINISHED.
   // Note: enum used for UMA. Do NOT reorder or remove entries. Don't forget to
   // update enums.xml (name: ExtensionInstallationDownloadingStage) when adding
   // new entries.
   enum Stage {
     // Downloader just received extension download request.
     PENDING = 0,

     // Extension is in manifest loading queue.
     QUEUED_FOR_MANIFEST = 1,

     // There is an active request to download extension's manifest.
     DOWNLOADING_MANIFEST = 2,

     // There were one or more unsuccessful tries to download manifest, but we'll
     // try more.
     DOWNLOADING_MANIFEST_RETRY = 3,

     // Manifest downloaded and is about to parse.
     PARSING_MANIFEST = 4,

     // Manifest downloaded and successfully parsed.
     MANIFEST_LOADED = 5,

     // Extension in CRX loading queue.
     QUEUED_FOR_CRX = 6,

     // There is an active request to download extension archive.
     DOWNLOADING_CRX = 7,

     // There were one or more unsuccessful tries to download archive, but we'll
     // try more.
     DOWNLOADING_CRX_RETRY = 8,

     // Downloading finished, either successfully or not.
     FINISHED = 9,

     // Magic constant used by the histogram macros.
     // Always update it to the max value.
     kMaxValue = FINISHED,
   };

   // Passed as an argument to the completion callbacks to signal whether
   // the extension update sent a ping.
   struct PingResult {
     PingResult();
     ~PingResult();

     // Whether a ping was sent.
     bool did_ping;

     // The start of day, from the server's perspective. This is only valid
     // when |did_ping| is true.
     base::Time day_start;
   };

   // A callback that is called to indicate if ExtensionDownloader should ignore
   // the cached entry and download a new .crx file.
   typedef base::Callback<void(bool should_download)> InstallCallback;

   // One of the following 3 methods is always invoked for a given extension
   // id, if AddExtension() or AddPendingExtension() returned true when that
   // extension was added to the ExtensionDownloader.
   // To avoid duplicate work, ExtensionDownloader might merge multiple identical
   // requests, so there is not necessarily a separate invocation of one of these
   // methods for each call to AddExtension/AddPendingExtension. If it is
   // important to be able to match up AddExtension calls with
   // OnExtensionDownload callbacks, you need to make sure that for every call to
   // AddExtension/AddPendingExtension the combination of extension id and
   // request id is unique. The OnExtensionDownload related callbacks will then
   // be called with all request ids that resulted in that extension being
   // checked.

   // Invoked several times during downloading, |stage| contains current stage
   // of downloading.
   virtual void OnExtensionDownloadStageChanged(const std::string& id,
                                                Stage stage);

   // Invoked if the extension couldn't be downloaded. |error| contains the
   // failure reason.
   virtual void OnExtensionDownloadFailed(const std::string& id,
                                          Error error,
                                          const PingResult& ping_result,
                                          const std::set<int>& request_ids);

   // Invoked if the extension had an update available and its crx was
   // successfully downloaded to |path|. |ownership_passed| is true if delegate
   // should get ownership of the file. The downloader may be able to get the
   // .crx file both from a locally cached version or by issuing a network
   // request. If the install attempt by the delegate fails and the source was
   // the cache, the cached version may be corrupt (or simply not the desired
   // one), and we'd like to try downloading the .crx from the network and have
   // the delegate attempt install again. So if the |callback| parameter is
   // non-null (if the file was taken from the cache), on install failure the
   // downloader should be notified to try download from network by calling the
   // callback with true; on successful install it should be called with false so
   // that downloader could release all downloaded metadata. After downloading
   // the delegate will be once again called with OnExtensionDownloadFinished (or
   // OnExtensionDownloadFailed) called again with the same |request_ids|.
   virtual void OnExtensionDownloadFinished(const CRXFileInfo& file,
                                            bool file_ownership_passed,
                                            const GURL& download_url,
                                            const std::string& version,
                                            const PingResult& ping_result,
                                            const std::set<int>& request_ids,
                                            const InstallCallback& callback) = 0;

   // Invoked when an extension fails to load, but a retry is triggered.
   // It allows unittests to easily set up and verify resourse request and
   // load results between a failure / retry sequence.
   virtual void OnExtensionDownloadRetryForTests();

   // The remaining methods are used by the ExtensionDownloader to retrieve
   // information about extensions from the delegate.

   // Invoked to fill the PingData for the given extension id. Returns false
   // if PingData should not be included for this extension's update check
   // (this is the default).
   virtual bool GetPingDataForExtension(const std::string& id,
                                        ManifestFetchData::PingData* ping);

   // Invoked to get the update url data for this extension's update url, if
   // there is any. The default implementation returns an empty string.
   virtual std::string GetUpdateUrlData(const std::string& id);

   // Invoked to determine whether extension |id| is currently
   // pending installation.
   virtual bool IsExtensionPending(const std::string& id) = 0;

   // Invoked to get the current version of extension |id|. Returns false if
   // that extension is not installed.
   virtual bool GetExtensionExistingVersion(const std::string& id,
                                            std::string* version) = 0;
 };

 }  // namespace extensions

 #endif  // EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_
	// Copyright (c) 2012 The Chromium Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_
	#define EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_

	#include <set>
	#include <string>

	#include "base/callback.h"
	#include "base/time/time.h"
	#include "extensions/browser/crx_file_info.h"
	#include "extensions/browser/updater/manifest_fetch_data.h"

	class GURL;

	namespace extensions {

	class ExtensionDownloaderDelegate {
	public:
	virtual ~ExtensionDownloaderDelegate();

	// Passed as an argument to ExtensionDownloader::OnExtensionDownloadFailed()
	// to detail the reason for the failure.
	enum Error {
	// Background networking is disabled.
	DISABLED,

	// Failed to fetch the manifest for this extension.
	MANIFEST_FETCH_FAILED,

	// The manifest couldn't be parsed.
	MANIFEST_INVALID,

	// The manifest was fetched and parsed, and there are no updates for
	// this extension.
	NO_UPDATE_AVAILABLE,

	// There was an update for this extension but the download of the crx
	// failed.
	CRX_FETCH_FAILED,
	};

	// Passed as an argument OnExtensionDownloadStageChanged() to detail how
	// downloading is going on. Typical sequence is: PENDING ->
	// QUEUED_FOR_MANIFEST -> DOWNLOADING_MANIFEST -> PARSING_MANIFEST ->
	// MANIFEST_LOADED -> QUEUED_FOR_CRX -> DOWNLOADING_CRX -> FINISHED. Stages
	// QUEUED_FOR_MANIFEST and QUEUED_FOR_CRX are optional and may be skipped.
	// Failure on any stage will result in skipping all remained stages, moving to
	// FINISHED instantly. Special stages DOWNLOADING_MANIFEST_RETRY and
	// DOWNLOADING_CRX_RETRY are similar to QUEUED_* ones, but signify that
	// download failed at least once already. So, this may result in sequence like
	// ... -> MANIFEST_LOADED -> QUEUED_FOR_CRX -> DOWNLOADING_CRX ->
	// DOWNLOADING_CRX_RETRY -> DOWNLOADING_CRX -> FINISHED.
	// Note: enum used for UMA. Do NOT reorder or remove entries. Don't forget to
	// update enums.xml (name: ExtensionInstallationDownloadingStage) when adding
	// new entries.
	enum Stage {
	// Downloader just received extension download request.
	PENDING = 0,

	// Extension is in manifest loading queue.
	QUEUED_FOR_MANIFEST = 1,

	// There is an active request to download extension's manifest.
	DOWNLOADING_MANIFEST = 2,

	// There were one or more unsuccessful tries to download manifest, but we'll
	// try more.
	DOWNLOADING_MANIFEST_RETRY = 3,

	// Manifest downloaded and is about to parse.
	PARSING_MANIFEST = 4,

	// Manifest downloaded and successfully parsed.
	MANIFEST_LOADED = 5,

	// Extension in CRX loading queue.
	QUEUED_FOR_CRX = 6,

	// There is an active request to download extension archive.
	DOWNLOADING_CRX = 7,

	// There were one or more unsuccessful tries to download archive, but we'll
	// try more.
	DOWNLOADING_CRX_RETRY = 8,

	// Downloading finished, either successfully or not.
	FINISHED = 9,

	// Magic constant used by the histogram macros.
	// Always update it to the max value.
	kMaxValue = FINISHED,
	};

	// Passed as an argument to the completion callbacks to signal whether
	// the extension update sent a ping.
	struct PingResult {
	PingResult();
	~PingResult();

	// Whether a ping was sent.
	bool did_ping;

	// The start of day, from the server's perspective. This is only valid
	// when \|did_ping\| is true.
	base::Time day_start;
	};

	// A callback that is called to indicate if ExtensionDownloader should ignore
	// the cached entry and download a new .crx file.
	typedef base::Callback<void(bool should_download)> InstallCallback;

	// One of the following 3 methods is always invoked for a given extension
	// id, if AddExtension() or AddPendingExtension() returned true when that
	// extension was added to the ExtensionDownloader.
	// To avoid duplicate work, ExtensionDownloader might merge multiple identical
	// requests, so there is not necessarily a separate invocation of one of these
	// methods for each call to AddExtension/AddPendingExtension. If it is
	// important to be able to match up AddExtension calls with
	// OnExtensionDownload callbacks, you need to make sure that for every call to
	// AddExtension/AddPendingExtension the combination of extension id and
	// request id is unique. The OnExtensionDownload related callbacks will then
	// be called with all request ids that resulted in that extension being
	// checked.

	// Invoked several times during downloading, \|stage\| contains current stage
	// of downloading.
	virtual void OnExtensionDownloadStageChanged(const std::string& id,
	Stage stage);

	// Invoked if the extension couldn't be downloaded. \|error\| contains the
	// failure reason.
	virtual void OnExtensionDownloadFailed(const std::string& id,
	Error error,
	const PingResult& ping_result,
	const std::set<int>& request_ids);

	// Invoked if the extension had an update available and its crx was
	// successfully downloaded to \|path\|. \|ownership_passed\| is true if delegate
	// should get ownership of the file. The downloader may be able to get the
	// .crx file both from a locally cached version or by issuing a network
	// request. If the install attempt by the delegate fails and the source was
	// the cache, the cached version may be corrupt (or simply not the desired
	// one), and we'd like to try downloading the .crx from the network and have
	// the delegate attempt install again. So if the \|callback\| parameter is
	// non-null (if the file was taken from the cache), on install failure the
	// downloader should be notified to try download from network by calling the
	// callback with true; on successful install it should be called with false so
	// that downloader could release all downloaded metadata. After downloading
	// the delegate will be once again called with OnExtensionDownloadFinished (or
	// OnExtensionDownloadFailed) called again with the same \|request_ids\|.
	virtual void OnExtensionDownloadFinished(const CRXFileInfo& file,
	bool file_ownership_passed,
	const GURL& download_url,
	const std::string& version,
	const PingResult& ping_result,
	const std::set<int>& request_ids,
	const InstallCallback& callback) = 0;

	// Invoked when an extension fails to load, but a retry is triggered.
	// It allows unittests to easily set up and verify resourse request and
	// load results between a failure / retry sequence.
	virtual void OnExtensionDownloadRetryForTests();

	// The remaining methods are used by the ExtensionDownloader to retrieve
	// information about extensions from the delegate.

	// Invoked to fill the PingData for the given extension id. Returns false
	// if PingData should not be included for this extension's update check
	// (this is the default).
	virtual bool GetPingDataForExtension(const std::string& id,
	ManifestFetchData::PingData* ping);

	// Invoked to get the update url data for this extension's update url, if
	// there is any. The default implementation returns an empty string.
	virtual std::string GetUpdateUrlData(const std::string& id);

	// Invoked to determine whether extension \|id\| is currently
	// pending installation.
	virtual bool IsExtensionPending(const std::string& id) = 0;

	// Invoked to get the current version of extension \|id\|. Returns false if
	// that extension is not installed.
	virtual bool GetExtensionExistingVersion(const std::string& id,
	std::string* version) = 0;
	};

	} // namespace extensions

	#endif // EXTENSIONS_BROWSER_UPDATER_EXTENSION_DOWNLOADER_DELEGATE_H_