chrome/browser/icon_manager.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // Class for finding and caching Windows explorer icons. The IconManager
   6 // lives on the UI thread but performs icon extraction work on the file thread
   7 // to avoid blocking the UI thread with potentially expensive COM and disk
   8 // operations.
   9 //
  10 // Terminology
  11 //
  12 // Windows files have icons associated with them that can be of two types:
  13 //   1. "Per class": the icon used for this file is used for all files with the
  14 //      same file extension or class. Examples are PDF or MP3 files, which use
  15 //      the same icon for all files of that type.
  16 //   2. "Per instance": the icon used for this file is embedded in the file
  17 //      itself and is unique. Executable files are typically "per instance".
  18 //
  19 // Files that end in the following extensions are considered "per instance":
  20 //   .exe
  21 //   .dll
  22 //   .ico
  23 // The IconManager will do explicit icon loads on the full path of these files
  24 // and cache the results per file. All other file types will be looked up by
  25 // file extension and the results will be cached per extension. That way, all
  26 // .mp3 files will share one icon, but all .exe files will have their own icon.
  27 //
  28 // POSIX files don't have associated icons. We query the OS by the file's
  29 // mime type.
  30 //
  31 // The IconManager can be queried in two ways:
  32 //   1. A quick, synchronous check of its caches which does not touch the disk:
  33 //      IconManager::LookupIcon()
  34 //   2. An asynchronous icon load from a file on the file thread:
  35 //      IconManager::LoadIcon()
  36 //
  37 // When using the second (asynchronous) method, callers must supply a callback
  38 // which will be run once the icon has been extracted. The icon manager will
  39 // cache the results of the icon extraction so that subsequent lookups will be
  40 // fast.
  41 //
  42 // Icon bitmaps returned should be treated as const since they may be referenced
  43 // by other clients. Make a copy of the icon if you need to modify it.
  44
  45 #ifndef CHROME_BROWSER_ICON_MANAGER_H_
  46 #define CHROME_BROWSER_ICON_MANAGER_H_
  47
  48 #include <map>
  49 #include <memory>
  50
  51 #include "base/files/file_path.h"
  52 #include "base/memory/weak_ptr.h"
  53 #include "base/task/cancelable_task_tracker.h"
  54 #include "chrome/browser/icon_loader.h"
  55 #include "ui/gfx/image/image.h"
  56
  57 class IconManager {
  58  public:
  59   IconManager();
  60
  61   IconManager(const IconManager&) = delete;
  62   IconManager& operator=(const IconManager&) = delete;
  63
  64   ~IconManager();
  65
  66   // Synchronous call to examine the internal caches for the icon. Returns the
  67   // icon if we have already loaded it, or null if we don't have it and must
  68   // load it via LoadIcon(). The returned bitmap is owned by the IconManager and
  69   // must not be free'd by the caller. If the caller needs to modify the icon,
  70   // it must make a copy and modify the copy.
  71   gfx::Image* LookupIconFromFilepath(const base::FilePath& file_path,
  72                                      IconLoader::IconSize size,
  73                                      float scale);
  74
  75   using IconRequestCallback = base::OnceCallback<void(gfx::Image)>;
  76
  77   // Asynchronous call to lookup and return the icon associated with file. The
  78   // work is done on the file thread, with the callbacks running on the thread
  79   // this function is called.
  80   //
  81   // Note:
  82   // 1. This does *not* check the cache.
  83   // 2. The returned bitmap pointer is *not* owned by callback. So callback
  84   //    should never keep it or delete it.
  85   // 3. The gfx::Image pointer passed to the callback will be null if decoding
  86   //    failed.
  87   base::CancelableTaskTracker::TaskId LoadIcon(
  88       const base::FilePath& file_name,
  89       IconLoader::IconSize size,
  90       float scale,
  91       IconRequestCallback callback,
  92       base::CancelableTaskTracker* tracker);
  93
  94  private:
  95   gfx::Image* DoLookupIconFromFilepath(const base::FilePath& file_path,
  96                                        IconLoader::IconSize size,
  97                                        float scale);
  98
  99   void OnIconLoaded(IconRequestCallback callback,
 100                     base::FilePath file_path,
 101                     IconLoader::IconSize size,
 102                     float scale,
 103                     gfx::Image result,
 104                     const IconLoader::IconGroup& group);
 105
 106   struct CacheKey {
 107     CacheKey(const IconLoader::IconGroup& group,
 108              IconLoader::IconSize size,
 109              float scale);
 110
 111     // Used as a key in the map below, so we need this comparator.
 112     bool operator<(const CacheKey &other) const;
 113
 114     IconLoader::IconGroup group;
 115     IconLoader::IconSize size;
 116     float scale;
 117   };
 118
 119   std::map<base::FilePath, IconLoader::IconGroup> group_cache_;
 120   std::map<CacheKey, gfx::Image> icon_cache_;
 121
 122   base::WeakPtrFactory<IconManager> weak_factory_{this};
 123 };
 124
 125 #endif  // CHROME_BROWSER_ICON_MANAGER_H_