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