components/favicon/core/large_icon_service.h - chromium/src - Git at Google

 // Copyright 2015 The Chromium Authors
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_
 #define COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_

 #include <optional>

 #include "base/task/cancelable_task_tracker.h"
 #include "components/favicon_base/favicon_callback.h"
 #include "components/keyed_service/core/keyed_service.h"

 namespace net {
 struct NetworkTrafficAnnotationTag;
 }

 class GURL;

 namespace favicon {

 // The large icon service provides methods to access large icons. The actual
 // implementation of this uses Google's favicon service.
 class LargeIconService : public KeyedService {
  public:
   // Controls the icon size in pixels returned by the
   // `GetLargeIconFromCacheFallbackToGoogleServer()`. This enum is used to
   // ensure icons are requested at standard sizes, because the underlying
   // favicon database stores at most 1 icon per domain and favicons are
   // requested from the Google server at a single hard-coded size.
   enum class StandardIconSize {
     k16x16 = 0,
     k32x32 = 1,
   };
   // Controls the behavior when there is no icon bigger than the minimum size to
   // return.
   enum class NoBigEnoughIconBehavior {
     // Return the biggest favicon bitmap available.
     kReturnBitmap = 0,
     // Extract the dominant color of the smaller image.
     kReturnFallbackColor = 1,
     // Empty return.
     kReturnEmpty = 2,
   };

   LargeIconService(const LargeIconService&) = delete;
   LargeIconService& operator=(const LargeIconService&) = delete;

   // Requests the best large icon for the page at `page_url`.
   // Case 1. An icon exists whose size is >= MAX(`min_source_size_in_pixel`,
   // `desired_size_in_pixel`):
   // - If `desired_size_in_pixel` == 0: returns icon as is.
   // - Else: returns the icon resized to `desired_size_in_pixel`.
   // Case 2. An icon exists whose size is >= `min_source_size_in_pixel` and <
   // `desired_size_in_pixel`:
   // - Same as 1 with the biggest icon.
   // Case 3. An icon exists whose size is < `min_source_size_in_pixel`:
   // - Extracts dominant color of smaller image, returns a fallback icon style
   //   that has a matching background.
   // Case 4. No icon exists.
   // - Returns the default fallback icon style.
   // For cases 3 and 4, this function returns the style of the fallback icon
   // instead of rendering an icon so clients can render the icon themselves.
   virtual base::CancelableTaskTracker::TaskId
   GetLargeIconRawBitmapOrFallbackStyleForPageUrl(
       const GURL& page_url,
       int min_source_size_in_pixel,
       int desired_size_in_pixel,
       favicon_base::LargeIconCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Behaves the same as GetLargeIconRawBitmapOrFallbackStyleForPageUrl(), only
   // returns the large icon (if available) decoded.
   virtual base::CancelableTaskTracker::TaskId
   GetLargeIconImageOrFallbackStyleForPageUrl(
       const GURL& page_url,
       int min_source_size_in_pixel,
       int desired_size_in_pixel,
       favicon_base::LargeIconImageCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Queries the favicon database for an icon larger than
   // `min_source_size_in_pixel`. If `size_in_pixel_to_resize_to` is specified,
   // the returned icon will be resized to the passed-in size. The resizing also
   // occurs if there is no big enough icon and `no_big_enough_icon_behavior` ==
   // NoBigEnoughIconBehavior::kReturnBitmap. `no_big_enough_icon_behavior`
   // controls the returned value if there is no icon larger than
   // `min_source_size_in_pixel` in the database.
   virtual base::CancelableTaskTracker::TaskId GetLargeIconRawBitmapForPageUrl(
       const GURL& page_url,
       int min_source_size_in_pixel,
       std::optional<int> size_in_pixel_to_resize_to,
       NoBigEnoughIconBehavior no_big_enough_icon_behavior,
       favicon_base::LargeIconCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Behaves the same as GetLargeIconRawBitmapOrFallbackStyleForPageUrl, except
   // uses icon URL instead of page URL.
   virtual base::CancelableTaskTracker::TaskId
   GetLargeIconRawBitmapOrFallbackStyleForIconUrl(
       const GURL& icon_url,
       int min_source_size_in_pixel,
       int desired_size_in_pixel,
       favicon_base::LargeIconCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Requests the best icon for the page at `page_url`. Fallbacks to the host's
   // favicon, and resizes the most similar bitmat to `desired_size_in_pizel` if
   // no exact match is found.
   virtual base::CancelableTaskTracker::TaskId
   GetIconRawBitmapOrFallbackStyleForPageUrl(
       const GURL& page_url,
       int desired_size_in_pixel,
       favicon_base::LargeIconCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Fetches the best large icon for the page at `page_url` from a Google
   // favicon server and stores the result in the FaviconService database
   // (implemented in HistoryService). The write will be a no-op if the local
   // favicon database contains an icon for `page_url`, so clients are
   // encouraged to use GetLargeIconOrFallbackStyle() first.
   //
   // A parameter in the server request representing the desired favicon size is
   // set according solely to the device and scale factor. However, it serves
   // only as a hint to the service, no guarantees on the fetched size are
   // provided.
   //
   // If `should_trim_page_url_path` is set to true, the path will be removed
   // from the URL used to query the server but the result will be stored under
   // the full URL provided to the API.
   //
   // The callback is triggered when the operation finishes, where `success`
   // tells whether the fetch actually managed to database a new icon in the
   // FaviconService.
   //
   // WARNING: This function will share the `page_url` with a Google server. This
   // can be used only for urls that are not privacy sensitive or for users that
   // sync their history with Google servers.
   // TODO(crbug.com/41425581): It is not clear from the name of this function,
   // that it actually adds the icon to the local cache. Maybe
   // "StoreLargeIcon..."?
   virtual void GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache(
       const GURL& page_url,
       bool should_trim_page_url_path,
       const net::NetworkTrafficAnnotationTag& traffic_annotation,
       favicon_base::GoogleFaviconServerCallback callback) = 0;

   // Requests the best large icon for the `page_url` via
   // `GetLargeIconRawBitmapForPageUrl()`. `min_source_size` and
   // `size_to_resize_to` are converted to integer values before being processed
   // further. They and `no_big_enough_icon_behavior` control the behavior of the
   // `GetLargeIconRawBitmapForPageUrl()`. If no icon (of any size) is found in
   // the local cache for `page_url`, the icon is queried from the Google server
   // via `GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache()`.
   //
   // Note: it's possible to obtain an image bigger than the largest standard
   // size (32x32) if the user has visited the `page_url` previously a mobile
   // device and the passed-in `size_to_resize_to` is `std::nullopt`.
   //
   // WARNING: This function may share the `page_url` with a Google server if the
   // icon is not found locally. This can be used only for urls that are not
   // privacy sensitive or for users that sync their history with Google servers.
   virtual void GetLargeIconFromCacheFallbackToGoogleServer(
       const GURL& page_url,
       StandardIconSize min_source_size,
       std::optional<StandardIconSize> size_to_resize_to,
       NoBigEnoughIconBehavior no_big_enough_icon_behavior,
       bool should_trim_page_url_path,
       const net::NetworkTrafficAnnotationTag& traffic_annotation,
       favicon_base::LargeIconCallback callback,
       base::CancelableTaskTracker* tracker) = 0;

   // Update the time that the icon at `icon_url` was requested. This should be
   // called after obtaining the icon by GetLargeIcon*OrFallbackStyle() for any
   // icon that _may_ originate from the Google favicon server (i.e. if the
   // caller uses
   // GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache()). This
   // postpones the automatic eviction of the favicon from the database.
   virtual void TouchIconFromGoogleServer(const GURL& icon_url) = 0;
  protected:
   LargeIconService() = default;
 };

 }  // namespace favicon

 #endif  // COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_
	// Copyright 2015 The Chromium Authors
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_
	#define COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_

	#include <optional>

	#include "base/task/cancelable_task_tracker.h"
	#include "components/favicon_base/favicon_callback.h"
	#include "components/keyed_service/core/keyed_service.h"

	namespace net {
	struct NetworkTrafficAnnotationTag;
	}

	class GURL;

	namespace favicon {

	// The large icon service provides methods to access large icons. The actual
	// implementation of this uses Google's favicon service.
	class LargeIconService : public KeyedService {
	public:
	// Controls the icon size in pixels returned by the
	// `GetLargeIconFromCacheFallbackToGoogleServer()`. This enum is used to
	// ensure icons are requested at standard sizes, because the underlying
	// favicon database stores at most 1 icon per domain and favicons are
	// requested from the Google server at a single hard-coded size.
	enum class StandardIconSize {
	k16x16 = 0,
	k32x32 = 1,
	};
	// Controls the behavior when there is no icon bigger than the minimum size to
	// return.
	enum class NoBigEnoughIconBehavior {
	// Return the biggest favicon bitmap available.
	kReturnBitmap = 0,
	// Extract the dominant color of the smaller image.
	kReturnFallbackColor = 1,
	// Empty return.
	kReturnEmpty = 2,
	};

	LargeIconService(const LargeIconService&) = delete;
	LargeIconService& operator=(const LargeIconService&) = delete;

	// Requests the best large icon for the page at `page_url`.
	// Case 1. An icon exists whose size is >= MAX(`min_source_size_in_pixel`,
	// `desired_size_in_pixel`):
	// - If `desired_size_in_pixel` == 0: returns icon as is.
	// - Else: returns the icon resized to `desired_size_in_pixel`.
	// Case 2. An icon exists whose size is >= `min_source_size_in_pixel` and <
	// `desired_size_in_pixel`:
	// - Same as 1 with the biggest icon.
	// Case 3. An icon exists whose size is < `min_source_size_in_pixel`:
	// - Extracts dominant color of smaller image, returns a fallback icon style
	// that has a matching background.
	// Case 4. No icon exists.
	// - Returns the default fallback icon style.
	// For cases 3 and 4, this function returns the style of the fallback icon
	// instead of rendering an icon so clients can render the icon themselves.
	virtual base::CancelableTaskTracker::TaskId
	GetLargeIconRawBitmapOrFallbackStyleForPageUrl(
	const GURL& page_url,
	int min_source_size_in_pixel,
	int desired_size_in_pixel,
	favicon_base::LargeIconCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Behaves the same as GetLargeIconRawBitmapOrFallbackStyleForPageUrl(), only
	// returns the large icon (if available) decoded.
	virtual base::CancelableTaskTracker::TaskId
	GetLargeIconImageOrFallbackStyleForPageUrl(
	const GURL& page_url,
	int min_source_size_in_pixel,
	int desired_size_in_pixel,
	favicon_base::LargeIconImageCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Queries the favicon database for an icon larger than
	// `min_source_size_in_pixel`. If `size_in_pixel_to_resize_to` is specified,
	// the returned icon will be resized to the passed-in size. The resizing also
	// occurs if there is no big enough icon and `no_big_enough_icon_behavior` ==
	// NoBigEnoughIconBehavior::kReturnBitmap. `no_big_enough_icon_behavior`
	// controls the returned value if there is no icon larger than
	// `min_source_size_in_pixel` in the database.
	virtual base::CancelableTaskTracker::TaskId GetLargeIconRawBitmapForPageUrl(
	const GURL& page_url,
	int min_source_size_in_pixel,
	std::optional<int> size_in_pixel_to_resize_to,
	NoBigEnoughIconBehavior no_big_enough_icon_behavior,
	favicon_base::LargeIconCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Behaves the same as GetLargeIconRawBitmapOrFallbackStyleForPageUrl, except
	// uses icon URL instead of page URL.
	virtual base::CancelableTaskTracker::TaskId
	GetLargeIconRawBitmapOrFallbackStyleForIconUrl(
	const GURL& icon_url,
	int min_source_size_in_pixel,
	int desired_size_in_pixel,
	favicon_base::LargeIconCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Requests the best icon for the page at `page_url`. Fallbacks to the host's
	// favicon, and resizes the most similar bitmat to `desired_size_in_pizel` if
	// no exact match is found.
	virtual base::CancelableTaskTracker::TaskId
	GetIconRawBitmapOrFallbackStyleForPageUrl(
	const GURL& page_url,
	int desired_size_in_pixel,
	favicon_base::LargeIconCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Fetches the best large icon for the page at `page_url` from a Google
	// favicon server and stores the result in the FaviconService database
	// (implemented in HistoryService). The write will be a no-op if the local
	// favicon database contains an icon for `page_url`, so clients are
	// encouraged to use GetLargeIconOrFallbackStyle() first.
	//
	// A parameter in the server request representing the desired favicon size is
	// set according solely to the device and scale factor. However, it serves
	// only as a hint to the service, no guarantees on the fetched size are
	// provided.
	//
	// If `should_trim_page_url_path` is set to true, the path will be removed
	// from the URL used to query the server but the result will be stored under
	// the full URL provided to the API.
	//
	// The callback is triggered when the operation finishes, where `success`
	// tells whether the fetch actually managed to database a new icon in the
	// FaviconService.
	//
	// WARNING: This function will share the `page_url` with a Google server. This
	// can be used only for urls that are not privacy sensitive or for users that
	// sync their history with Google servers.
	// TODO(crbug.com/41425581): It is not clear from the name of this function,
	// that it actually adds the icon to the local cache. Maybe
	// "StoreLargeIcon..."?
	virtual void GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache(
	const GURL& page_url,
	bool should_trim_page_url_path,
	const net::NetworkTrafficAnnotationTag& traffic_annotation,
	favicon_base::GoogleFaviconServerCallback callback) = 0;

	// Requests the best large icon for the `page_url` via
	// `GetLargeIconRawBitmapForPageUrl()`. `min_source_size` and
	// `size_to_resize_to` are converted to integer values before being processed
	// further. They and `no_big_enough_icon_behavior` control the behavior of the
	// `GetLargeIconRawBitmapForPageUrl()`. If no icon (of any size) is found in
	// the local cache for `page_url`, the icon is queried from the Google server
	// via `GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache()`.
	//
	// Note: it's possible to obtain an image bigger than the largest standard
	// size (32x32) if the user has visited the `page_url` previously a mobile
	// device and the passed-in `size_to_resize_to` is `std::nullopt`.
	//
	// WARNING: This function may share the `page_url` with a Google server if the
	// icon is not found locally. This can be used only for urls that are not
	// privacy sensitive or for users that sync their history with Google servers.
	virtual void GetLargeIconFromCacheFallbackToGoogleServer(
	const GURL& page_url,
	StandardIconSize min_source_size,
	std::optional<StandardIconSize> size_to_resize_to,
	NoBigEnoughIconBehavior no_big_enough_icon_behavior,
	bool should_trim_page_url_path,
	const net::NetworkTrafficAnnotationTag& traffic_annotation,
	favicon_base::LargeIconCallback callback,
	base::CancelableTaskTracker* tracker) = 0;

	// Update the time that the icon at `icon_url` was requested. This should be
	// called after obtaining the icon by GetLargeIcon*OrFallbackStyle() for any
	// icon that _may_ originate from the Google favicon server (i.e. if the
	// caller uses
	// GetLargeIconOrFallbackStyleFromGoogleServerSkippingLocalCache()). This
	// postpones the automatic eviction of the favicon from the database.
	virtual void TouchIconFromGoogleServer(const GURL& icon_url) = 0;
	protected:
	LargeIconService() = default;
	};

	} // namespace favicon

	#endif // COMPONENTS_FAVICON_CORE_LARGE_ICON_SERVICE_H_