Move Windows Jump List boilerplate out of jumplist_win for reuse

JumpListUpdater encapsulates the boilerplate for updating Windows
jump lists. Most of this code was moved out of jumplist_win for
reuse by app windows. COM interface definitions were removed from
jumplist_win.cc.

BUG=339253
TEST=Right-click on the Chrome icon in the Windows 7+ taskbar and
verify that the functionality has not changed.

Review URL: https://codereview.chromium.org/168583011

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@251960 0039d316-1c4b-4281-b951-d872f2087c98

chrome/browser/jumplist_updater_win.cc

+// Copyright 2014 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.
+
+#include "chrome/browser/jumplist_updater_win.h"
+
+#include <windows.h>
+#include <propkey.h>
+#include <shobjidl.h>
+
+#include "base/files/file_path.h"
+#include "base/path_service.h"
+#include "base/win/win_util.h"
+#include "base/win/windows_version.h"
+
+namespace {
+
+// Creates an IShellLink object.
+// An IShellLink object is almost the same as an application shortcut, and it
+// requires three items: the absolute path to an application, an argument
+// string, and a title string.
+bool AddShellLink(base::win::ScopedComPtr<IObjectCollection> collection,
+                  const std::wstring& application_path,
+                  scoped_refptr<ShellLinkItem> item) {
+  // Create an IShellLink object.
+  base::win::ScopedComPtr<IShellLink> link;
+  HRESULT result = link.CreateInstance(CLSID_ShellLink, NULL,
+                                       CLSCTX_INPROC_SERVER);
+  if (FAILED(result))
+    return false;
+
+  // Set the application path.
+  // We should exit this function when this call fails because it doesn't make
+  // any sense to add a shortcut that we cannot execute.
+  result = link->SetPath(application_path.c_str());
+  if (FAILED(result))
+    return false;
+
+  // Attach the command-line switches of this process before the given
+  // arguments and set it as the arguments of this IShellLink object.
+  // We also exit this function when this call fails because it isn't useful to
+  // add a shortcut that cannot open the given page.
+  std::wstring arguments(item->GetArguments());
+  if (!arguments.empty()) {
+    result = link->SetArguments(arguments.c_str());
+    if (FAILED(result))
+      return false;
+  }
+
+  // Attach the given icon path to this IShellLink object.
+  // Since an icon is an optional item for an IShellLink object, so we don't
+  // have to exit even when it fails.
+  if (!item->icon_path().empty())
+    link->SetIconLocation(item->icon_path().c_str(), item->icon_index());
+
+  // Set the title of the IShellLink object.
+  // The IShellLink interface does not have any functions which update its
+  // title because this interface is originally for creating an application
+  // shortcut which doesn't have titles.
+  // So, we should use the IPropertyStore interface to set its title.
+  base::win::ScopedComPtr<IPropertyStore> property_store;
+  result = link.QueryInterface(property_store.Receive());
+  if (FAILED(result))
+    return false;
+
+  if (!base::win::SetStringValueForPropertyStore(
+          property_store.get(),
+          PKEY_Title,
+          item->title().c_str())) {
+    return false;
+  }
+
+  // Add this IShellLink object to the given collection.
+  return SUCCEEDED(collection->AddObject(link));
+}
+
+}  // namespace
+
+
+// ShellLinkItem
+
+ShellLinkItem::ShellLinkItem()
+    : command_line_(CommandLine::NO_PROGRAM),
+      icon_index_(0) {
+}
+
+ShellLinkItem::~ShellLinkItem() {}
+
+std::wstring ShellLinkItem::GetArguments() const {
+  return command_line_.GetArgumentsString();
+}
+
+CommandLine* ShellLinkItem::GetCommandLine() {
+  return &command_line_;
+}
+
+
+// JumpListUpdater
+
+JumpListUpdater::JumpListUpdater(const std::wstring& app_user_model_id)
+    : app_user_model_id_(app_user_model_id),
+      user_max_items_(0) {
+}
+
+JumpListUpdater::~JumpListUpdater() {
+}
+
+// static
+bool JumpListUpdater::IsEnabled() {
+  // JumpList is implemented only on Windows 7 or later.
+  return base::win::GetVersion() >= base::win::VERSION_WIN7;
+}
+
+bool JumpListUpdater::BeginUpdate() {
+  // This instance is expected to be one-time-use only.
+  DCHECK(!destination_list_.get());
+
+  // Check preconditions.
+  if (!JumpListUpdater::IsEnabled() || app_user_model_id_.empty())
+    return false;
+
+  // Create an ICustomDestinationList object and attach it to our application.
+  HRESULT result = destination_list_.CreateInstance(CLSID_DestinationList, NULL,
+                                                    CLSCTX_INPROC_SERVER);
+  if (FAILED(result))
+    return false;
+
+  // Set the App ID for this JumpList.
+  result = destination_list_->SetAppID(app_user_model_id_.c_str());
+  if (FAILED(result))
+    return false;
+
+  // Start a transaction that updates the JumpList of this application.
+  // This implementation just replaces the all items in this JumpList, so
+  // we don't have to use the IObjectArray object returned from this call.
+  // It seems Windows 7 RC (Build 7100) automatically checks the items in this
+  // removed list and prevent us from adding the same item.
+  UINT max_slots;
+  base::win::ScopedComPtr<IObjectArray> removed;
+  result = destination_list_->BeginList(&max_slots, __uuidof(*removed),
+                                        removed.ReceiveVoid());
+  if (FAILED(result))
+    return false;
+
+  user_max_items_ = max_slots;
+
+  return true;
+}
+
+bool JumpListUpdater::CommitUpdate() {
+  if (!destination_list_.get())
+    return false;
+
+  // Commit this transaction and send the updated JumpList to Windows.
+  return SUCCEEDED(destination_list_->CommitList());
+}
+
+bool JumpListUpdater::AddTasks(const ShellLinkItemList& link_items) {
+  if (!destination_list_.get())
+    return false;
+
+  // Retrieve the absolute path to "chrome.exe".
+  base::FilePath application_path;
+  if (!PathService::Get(base::FILE_EXE, &application_path))
+    return false;
+
+  // Create an EnumerableObjectCollection object to be added items of the
+  // "Task" category.
+  base::win::ScopedComPtr<IObjectCollection> collection;
+  HRESULT result = collection.CreateInstance(CLSID_EnumerableObjectCollection,
+                                             NULL, CLSCTX_INPROC_SERVER);
+  if (FAILED(result))
+    return false;
+
+  // Add items to the "Task" category.
+  for (ShellLinkItemList::const_iterator it = link_items.begin();
+       it != link_items.end(); ++it) {
+    AddShellLink(collection, application_path.value(), *it);
+  }
+
+  // We can now add the new list to the JumpList.
+  // ICustomDestinationList::AddUserTasks() also uses the IObjectArray
+  // interface to retrieve each item in the list. So, we retrieve the
+  // IObjectArray interface from the EnumerableObjectCollection object.
+  base::win::ScopedComPtr<IObjectArray> object_array;
+  result = collection.QueryInterface(object_array.Receive());
+  if (FAILED(result))
+    return false;
+
+  return SUCCEEDED(destination_list_->AddUserTasks(object_array));
+}
+
+bool JumpListUpdater::AddCustomCategory(const std::wstring& category_name,
+                                        const ShellLinkItemList& link_items,
+                                        size_t max_items) {
+ if (!destination_list_.get())
+    return false;
+
+  // Retrieve the absolute path to "chrome.exe".
+  base::FilePath application_path;
+  if (!PathService::Get(base::FILE_EXE, &application_path))
+    return false;
+
+  // Exit this function when the given vector does not contain any items
+  // because an ICustomDestinationList::AppendCategory() call fails in this
+  // case.
+  if (link_items.empty() || !max_items)
+    return true;
+
+  // Create an EnumerableObjectCollection object.
+  // We once add the given items to this collection object and add this
+  // collection to the JumpList.
+  base::win::ScopedComPtr<IObjectCollection> collection;
+  HRESULT result = collection.CreateInstance(CLSID_EnumerableObjectCollection,
+                                             NULL, CLSCTX_INPROC_SERVER);
+  if (FAILED(result))
+    return false;
+
+  for (ShellLinkItemList::const_iterator item = link_items.begin();
+       item != link_items.end() && max_items > 0; ++item, --max_items) {
+    scoped_refptr<ShellLinkItem> link(*item);
+    AddShellLink(collection, application_path.value(), link);
+  }
+
+  // We can now add the new list to the JumpList.
+  // The ICustomDestinationList::AppendCategory() function needs the
+  // IObjectArray interface to retrieve each item in the list. So, we retrive
+  // the IObjectArray interface from the IEnumerableObjectCollection object
+  // and use it.
+  // It seems the ICustomDestinationList::AppendCategory() function just
+  // replaces all items in the given category with the ones in the new list.
+  base::win::ScopedComPtr<IObjectArray> object_array;
+  result = collection.QueryInterface(object_array.Receive());
+  if (FAILED(result))
+    return false;
+
+  return SUCCEEDED(destination_list_->AppendCategory(category_name.c_str(),
+                                                     object_array));
+}

chrome/browser/jumplist_updater_win.h

+// Copyright 2014 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 CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_
+#define CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_
+
+#include <windows.h>
+#include <shobjidl.h>
+
+#include <string>
+#include <vector>
+
+#include "base/command_line.h"
+#include "base/memory/ref_counted.h"
+#include "base/win/scoped_comptr.h"
+#include "third_party/skia/include/core/SkBitmap.h"
+
+// Represents a class used for creating an IShellLink object.
+// Even though an IShellLink also needs the absolute path to an application to
+// be executed, this class does not have any variables for it because current
+// users always use "chrome.exe" as the application.
+class ShellLinkItem : public base::RefCountedThreadSafe<ShellLinkItem> {
+ public:
+  ShellLinkItem();
+
+  const std::wstring& title() const { return title_; }
+  const std::wstring& icon_path() const { return icon_path_; }
+  int icon_index() const { return icon_index_; }
+  const SkBitmap& icon_data() const { return icon_data_; }
+
+  std::wstring GetArguments() const;
+  CommandLine* GetCommandLine();
+
+  void set_title(const std::wstring& title) {
+    title_ = title;
+  }
+
+  void set_icon(const std::wstring& path, int index) {
+    icon_path_ = path;
+    icon_index_ = index;
+  }
+
+  void set_icon_data(const SkBitmap& data) {
+    icon_data_ = data;
+  }
+
+ private:
+  friend class base::RefCountedThreadSafe<ShellLinkItem>;
+  ~ShellLinkItem();
+
+  // Used for storing and appending command-line arguments.
+  CommandLine command_line_;
+
+  // The string to be displayed in a JumpList.
+  std::wstring title_;
+
+  // The absolute path to an icon to be displayed in a JumpList.
+  std::wstring icon_path_;
+
+  // The icon index in the icon file. If an icon file consists of two or more
+  // icons, set this value to identify the icon. If an icon file consists of
+  // one icon, this value is 0.
+  int icon_index_;
+
+  // Icon bitmap. Used by the browser JumpList.
+  // Note that an icon path must be supplied to IShellLink, so users of this
+  // class must save icon data to disk.
+  SkBitmap icon_data_;
+
+  DISALLOW_COPY_AND_ASSIGN(ShellLinkItem);
+};
+
+typedef std::vector<scoped_refptr<ShellLinkItem> > ShellLinkItemList;
+
+
+// A utility class that hides the boilerplate for updating Windows JumpLists.
+// Note that JumpLists are available in Windows 7 and later only.
+//
+// Example of usage:
+//
+//    JumpListUpdater updater(app_id);
+//    if (updater.BeginUpdate()) {
+//      updater.AddTasks(...);
+//      updater.AddCustomCategory(...);
+//      updater.CommitUpdate();
+//    }
+//
+// Note:
+// - Each JumpListUpdater instance is expected to be used once only.
+// - The JumpList must be updated in its entirety, i.e. even if a category has
+//   not changed, all its items must be added in each update.
+class JumpListUpdater {
+ public:
+  explicit JumpListUpdater(const std::wstring& app_user_model_id);
+  ~JumpListUpdater();
+
+  // Returns true if JumpLists are enabled on this OS.
+  static bool IsEnabled();
+
+  // Returns the current user setting for the maximum number of items to display
+  // in JumpLists. The setting is retrieved in BeginUpdate().
+  size_t user_max_items() const { return user_max_items_; }
+
+  // Starts a transaction that updates the JumpList of this application.
+  // This must be called prior to updating the JumpList. If this function
+  // returns false, this instance should not be used.
+  bool BeginUpdate();
+
+  // Commits the update.
+  bool CommitUpdate();
+
+  // Updates the predefined "Tasks" category of the JumpList.
+  bool AddTasks(const ShellLinkItemList& link_items);
+
+  // Updates an unregistered category of the JumpList.
+  // This function cannot update registered categories (such as "Tasks")
+  // because special steps are required for updating them.
+  // |max_items| specifies the maximum number of items from |link_items| to add
+  // to the JumpList.
+  bool AddCustomCategory(const std::wstring& category_name,
+                         const ShellLinkItemList& link_items,
+                         size_t max_items);
+
+ private:
+  // The app ID.
+  std::wstring app_user_model_id_;
+
+  // Windows API interface used to modify JumpLists.
+  base::win::ScopedComPtr<ICustomDestinationList> destination_list_;
+
+  // The current user setting for "Number of recent items to display in Jump
+  // Lists" option in the "Taskbar and Start Menu Properties".
+  size_t user_max_items_;
+
+  DISALLOW_COPY_AND_ASSIGN(JumpListUpdater);
+};
+
+#endif  // CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_

chrome/browser/jumplist_win.h

@@ -10,20 +10,16 @@
 #include <utility>
 #include <vector>
 
-#include "base/memory/ref_counted.h"
+#include "base/files/file_path.h"
 #include "base/memory/weak_ptr.h"
 #include "base/synchronization/lock.h"
 #include "base/task/cancelable_task_tracker.h"
 #include "chrome/browser/history/history_service.h"
 #include "chrome/browser/history/history_types.h"
+#include "chrome/browser/jumplist_updater_win.h"
 #include "chrome/browser/sessions/tab_restore_service.h"
 #include "chrome/browser/sessions/tab_restore_service_observer.h"
 #include "content/public/browser/browser_thread.h"
-#include "third_party/skia/include/core/SkBitmap.h"
-
-namespace base {
-class FilePath;
-}
 
 namespace chrome {
 struct FaviconImageResult;
@@ -36,69 +32,6 @@ class NotificationRegistrar;
 class Profile;
 class PageUsageData;
 
-// Represents a class used for creating an IShellLink object by the utility
-// functions in this file.
-// This class consists of three strings and a integer.
-// * arguments (std::wstring)
-//   The arguments for the application.
-// * title (std::wstring)
-//   The string to be displayed in a JumpList.
-// * icon (std::wstring)
-//   The absolute path to an icon to be displayed in a JumpList.
-// * index (int)
-//   The icon index in the icon file. If an icon file consists of two or more
-//   icons, set this value to identify the icon. If an icon file consists of
-// one icon, this value is 0.
-// Even though an IShellLink also needs the absolute path to an application to
-// be executed, this class does not have any variables for it because our
-// utility functions always use "chrome.exe" as the application and we don't
-// need it.
-class ShellLinkItem : public base::RefCountedThreadSafe<ShellLinkItem> {
- public:
-  ShellLinkItem() : index_(0), favicon_(false) {
-  }
-
-  const std::wstring& arguments() const { return arguments_; }
-  const std::wstring& title() const { return title_; }
-  const std::wstring& icon() const { return icon_; }
-  int index() const { return index_; }
-  const SkBitmap& data() const { return data_; }
-
-  void SetArguments(const std::wstring& arguments) {
-    arguments_ = arguments;
-  }
-
-  void SetTitle(const std::wstring& title) {
-    title_ = title;
-  }
-
-  void SetIcon(const std::wstring& icon, int index, bool favicon) {
-    icon_ = icon;
-    index_ = index;
-    favicon_ = favicon;
-  }
-
-  void SetIconData(const SkBitmap& data) {
-    data_ = data;
-  }
-
- private:
-  friend class base::RefCountedThreadSafe<ShellLinkItem>;
-
-  ~ShellLinkItem() {}
-
-  std::wstring arguments_;
-  std::wstring title_;
-  std::wstring icon_;
-  SkBitmap data_;
-  int index_;
-  bool favicon_;
-
-  DISALLOW_COPY_AND_ASSIGN(ShellLinkItem);
-};
-
-typedef std::vector<scoped_refptr<ShellLinkItem> > ShellLinkItemList;
-
 // A class which implements an application JumpList.
 // This class encapsulates operations required for updating an application
 // JumpList:

chrome/chrome_browser.gypi

@@ -988,6 +988,8 @@
         'browser/jankometer.h',
         'browser/jankometer_android.cc',
         'browser/jankometer_mac.cc',
+        'browser/jumplist_updater_win.cc',
+        'browser/jumplist_updater_win.h',
         'browser/jumplist_win.cc',
         'browser/jumplist_win.h',
         'browser/lifetime/application_lifetime.cc',