base/win/shortcut.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_WIN_SHORTCUT_H_
   6 #define BASE_WIN_SHORTCUT_H_
   7
   8 #include <windows.h>
   9
  10 #include "base/base_export.h"
  11 #include "base/files/file_path.h"
  12 #include "base/logging.h"
  13 #include "base/strings/string16.h"
  14
  15 namespace base {
  16 namespace win {
  17
  18 enum ShortcutOperation {
  19   // Create a new shortcut (overwriting if necessary).
  20   SHORTCUT_CREATE_ALWAYS = 0,
  21   // Overwrite an existing shortcut (fails if the shortcut doesn't exist).
  22   // If the arguments are not specified on the new shortcut, keep the old
  23   // shortcut's arguments.
  24   SHORTCUT_REPLACE_EXISTING,
  25   // Update specified properties only on an existing shortcut.
  26   SHORTCUT_UPDATE_EXISTING,
  27 };
  28
  29 // Properties for shortcuts. Properties set will be applied to the shortcut on
  30 // creation/update, others will be ignored.
  31 // Callers are encouraged to use the setters provided which take care of
  32 // setting |options| as desired.
  33 struct BASE_EXPORT ShortcutProperties {
  34   enum IndividualProperties {
  35     PROPERTIES_TARGET = 1U << 0,
  36     PROPERTIES_WORKING_DIR = 1U << 1,
  37     PROPERTIES_ARGUMENTS = 1U << 2,
  38     PROPERTIES_DESCRIPTION = 1U << 3,
  39     PROPERTIES_ICON = 1U << 4,
  40     PROPERTIES_APP_ID = 1U << 5,
  41     PROPERTIES_DUAL_MODE = 1U << 6,
  42     // Be sure to update the values below when adding a new property.
  43     PROPERTIES_BASIC = PROPERTIES_TARGET |
  44         PROPERTIES_WORKING_DIR |
  45         PROPERTIES_ARGUMENTS |
  46         PROPERTIES_DESCRIPTION |
  47         PROPERTIES_ICON,
  48     PROPERTIES_WIN7 = PROPERTIES_APP_ID | PROPERTIES_DUAL_MODE,
  49     PROPERTIES_ALL = PROPERTIES_BASIC | PROPERTIES_WIN7
  50   };
  51
  52   ShortcutProperties();
  53   ~ShortcutProperties();
  54
  55   void set_target(const FilePath& target_in) {
  56     target = target_in;
  57     options |= PROPERTIES_TARGET;
  58   }
  59
  60   void set_working_dir(const FilePath& working_dir_in) {
  61     working_dir = working_dir_in;
  62     options |= PROPERTIES_WORKING_DIR;
  63   }
  64
  65   void set_arguments(const string16& arguments_in) {
  66     // Size restriction as per MSDN at http://goo.gl/TJ7q5.
  67     DCHECK(arguments_in.size() < MAX_PATH);
  68     arguments = arguments_in;
  69     options |= PROPERTIES_ARGUMENTS;
  70   }
  71
  72   void set_description(const string16& description_in) {
  73     // Size restriction as per MSDN at http://goo.gl/OdNQq.
  74     DCHECK(description_in.size() < MAX_PATH);
  75     description = description_in;
  76     options |= PROPERTIES_DESCRIPTION;
  77   }
  78
  79   void set_icon(const FilePath& icon_in, int icon_index_in) {
  80     icon = icon_in;
  81     icon_index = icon_index_in;
  82     options |= PROPERTIES_ICON;
  83   }
  84
  85   void set_app_id(const string16& app_id_in) {
  86     app_id = app_id_in;
  87     options |= PROPERTIES_APP_ID;
  88   }
  89
  90   void set_dual_mode(bool dual_mode_in) {
  91     dual_mode = dual_mode_in;
  92     options |= PROPERTIES_DUAL_MODE;
  93   }
  94
  95   // The target to launch from this shortcut. This is mandatory when creating
  96   // a shortcut.
  97   FilePath target;
  98   // The name of the working directory when launching the shortcut.
  99   FilePath working_dir;
 100   // The arguments to be applied to |target| when launching from this shortcut.
 101   // The length of this string must be less than MAX_PATH.
 102   string16 arguments;
 103   // The localized description of the shortcut.
 104   // The length of this string must be less than MAX_PATH.
 105   string16 description;
 106   // The path to the icon (can be a dll or exe, in which case |icon_index| is
 107   // the resource id).
 108   FilePath icon;
 109   int icon_index;
 110   // The app model id for the shortcut (Win7+).
 111   string16 app_id;
 112   // Whether this is a dual mode shortcut (Win8+).
 113   bool dual_mode;
 114   // Bitfield made of IndividualProperties. Properties set in |options| will be
 115   // set on the shortcut, others will be ignored.
 116   uint32 options;
 117 };
 118
 119 // This method creates (or updates) a shortcut link at |shortcut_path| using the
 120 // information given through |properties|.
 121 // Ensure you have initialized COM before calling into this function.
 122 // |operation|: a choice from the ShortcutOperation enum.
 123 // If |operation| is SHORTCUT_REPLACE_EXISTING or SHORTCUT_UPDATE_EXISTING and
 124 // |shortcut_path| does not exist, this method is a no-op and returns false.
 125 BASE_EXPORT bool CreateOrUpdateShortcutLink(
 126     const FilePath& shortcut_path,
 127     const ShortcutProperties& properties,
 128     ShortcutOperation operation);
 129
 130 // Resolves Windows shortcut (.LNK file).
 131 // This methods tries to resolve selected properties of a shortcut .LNK file.
 132 // The path of the shortcut to resolve is in |shortcut_path|. |options| is a bit
 133 // field composed of ShortcutProperties::IndividualProperties, to specify which
 134 // properties to read. It should be non-0. The resulting data are read into
 135 // |properties|, which must not be NULL. Note: PROPERTIES_TARGET will retrieve
 136 // the target path as stored in the shortcut but won't attempt to resolve that
 137 // path so it may not be valid. The function returns true if all requested
 138 // properties are successfully read. Otherwise some reads have failed and
 139 // intermediate values written to |properties| should be ignored.
 140 BASE_EXPORT bool ResolveShortcutProperties(const FilePath& shortcut_path,
 141                                            uint32 options,
 142                                            ShortcutProperties* properties);
 143
 144 // Resolves Windows shortcut (.LNK file).
 145 // This is a wrapper to ResolveShortcutProperties() to handle the common use
 146 // case of resolving target and arguments. |target_path| and |args| are
 147 // optional output variables that are ignored if NULL (but at least one must be
 148 // non-NULL). The function returns true if all requested fields are found
 149 // successfully. Callers can safely use the same variable for both
 150 // |shortcut_path| and |target_path|.
 151 BASE_EXPORT bool ResolveShortcut(const FilePath& shortcut_path,
 152                                  FilePath* target_path,
 153                                  string16* args);
 154
 155 // Pins a shortcut to the Windows 7+ taskbar. The |shortcut| file must already
 156 // exist and be a shortcut that points to an executable. The app id of the
 157 // shortcut is used to group windows and must be set correctly.
 158 BASE_EXPORT bool PinShortcutToTaskbar(const FilePath& shortcut);
 159
 160 // Unpins a shortcut from the Windows 7+ taskbar. The |shortcut| must exist and
 161 // already be pinned to the taskbar. The app id of the shortcut is used as the
 162 // identifier for the taskbar item to remove and must be set correctly.
 163 BASE_EXPORT bool UnpinShortcutFromTaskbar(const FilePath& shortcut);
 164
 165 // Pins a shortcut to the Windows 10+ start menu. The |shortcut| file must
 166 // already exist and be a shortcut that points to an executable. The app id of
 167 // the shortcut is used as an identifier by the shell to know that all shortcuts
 168 // with this app id point to this pin (i.e. "Unpin" instead of "Pin" in those
 169 // shortcuts' context menus). Unpinning is unecessary on uninstall as Windows
 170 // handles getting rid of stale Start pins.
 171 BASE_EXPORT bool PinShortcutToStart(const FilePath& shortcut);
 172
 173 // Unpins a shortcut from the Windows 10+ start menu. The |shortcut| must exist
 174 // and already be pinned to the start menu. The app id of the shortcut is used
 175 // as the identifier for the start menu item to remove and must be set
 176 // correctly.
 177 BASE_EXPORT bool UnpinShortcutFromStart(const FilePath& shortcut);
 178
 179 }  // namespace win
 180 }  // namespace base
 181
 182 #endif  // BASE_WIN_SHORTCUT_H_