favicon_handler.h | Explore in Territory

// Copyright 2012 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_FAVICON_HANDLER_H_
#define COMPONENTS_FAVICON_CORE_FAVICON_HANDLER_H_

#include <stddef.h>

#include <optional>
#include <vector>

#include "base/cancelable_callback.h"
#include "base/containers/flat_set.h"
#include "base/functional/callback_forward.h"
#include "base/memory/raw_ptr.h"
#include "base/task/cancelable_task_tracker.h"
#include "components/favicon/core/favicon_driver_observer.h"
#include "components/favicon/core/favicon_url.h"
#include "components/favicon_base/favicon_callback.h"
#include "ui/gfx/favicon_size.h"
#include "ui/gfx/image/image.h"
#include "url/gurl.h"

class SkBitmap;

namespace favicon {

class CoreFaviconService;

// FaviconHandler works with FaviconDriver to fetch the specific type of
// favicon.
//
// FetchFavicon() requests favicons from CoreFaviconService. CoreFaviconService
// is typically backed by a database (such as HistoryService) and
// asynchronously returns results. At this point FaviconHandler only knows the
// url of the page, and not necessarily the url of the favicon(s). To ensure
// FaviconHandler handles reloading stale favicons as well as reloading a
// favicon on page reload Faviconhandler always requests the favicon from the
// CoreFaviconService regardless of whether the active favicon is valid.
//
// After the navigation two types of events are delivered (which is
// first depends upon who is faster): notification from the CoreFaviconService
// of the request for the favicon
// (OnFaviconDataForInitialURLFromFaviconService), or the favicon urls from
// the page (OnUpdateCandidates()).
// . If CoreFaviconService has a valid up to date favicon for the page, use it.
// . When OnUpdateCandidates() is called, if it matches that of the current page
//   and the current page's favicon is set, do nothing (everything is up to
//   date).
// . On the other hand, if CoreFaviconService does not know the favicon for
//   url, or the favicon is out date, or the favicon urls do not match,
//   then download the favicon. Downloading only happens once
//   CoreFaviconService has completed the request *and* the set of urls is
//   known.
//
// DownloadCurrentCandidateOrAskFaviconService() does the following:
// . If the current favicon is valid but expired, download a new icon.
// . Otherwise ask CoreFaviconService to update the mapping from page url to
//   favicon url and call us back with the favicon. Remember, it is
//   possible for the CoreFaviconService to already have the favicon, just not
//   the mapping between page and favicon url. The callback for this is
//   OnFaviconData().
//
// OnFaviconData() either updates the favicon of the current page (if
// CoreFaviconService knew about the favicon), or requests the renderer to
// download the favicon.
//
// When the renderer downloads favicons, it considers the entire list of
// favicon candidates, if `download_largest_favicon_` is true, the largest
// favicon will be used, otherwise the one that best matches the preferred size
// is chosen (or the first one if there is no preferred  size). Once the
// matching favicon has been determined, SetFavicon is called which updates
// the page's favicon and notifies the database to save the favicon.

class FaviconHandler { … };

}  // namespace favicon

#endif  // COMPONENTS_FAVICON_CORE_FAVICON_HANDLER_H_
chromium/components/favicon/core/favicon_handler.h
