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 = 1 << 0,
  35     PROPERTIES_WORKING_DIR = 1 << 1,
  36     PROPERTIES_ARGUMENTS = 1 << 2,
  37     PROPERTIES_DESCRIPTION = 1 << 3,
  38     PROPERTIES_ICON = 1 << 4,
  39     PROPERTIES_APP_ID = 1 << 5,
  40     PROPERTIES_DUAL_MODE = 1 << 6,
  41   };
  42
  43   ShortcutProperties() : icon_index(-1), dual_mode(false), options(0U) {}
  44
  45   void set_target(const FilePath& target_in) {
  46     target = target_in;
  47     options |= PROPERTIES_TARGET;
  48   }
  49
  50   void set_working_dir(const FilePath& working_dir_in) {
  51     working_dir = working_dir_in;
  52     options |= PROPERTIES_WORKING_DIR;
  53   }
  54
  55   void set_arguments(const string16& arguments_in) {
  56     // Size restriction as per MSDN at http://goo.gl/TJ7q5.
  57     DCHECK(arguments_in.size() < MAX_PATH);
  58     arguments = arguments_in;
  59     options |= PROPERTIES_ARGUMENTS;
  60   }
  61
  62   void set_description(const string16& description_in) {
  63     // Size restriction as per MSDN at http://goo.gl/OdNQq.
  64     DCHECK(description_in.size() < MAX_PATH);
  65     description = description_in;
  66     options |= PROPERTIES_DESCRIPTION;
  67   }
  68
  69   void set_icon(const FilePath& icon_in, int icon_index_in) {
  70     icon = icon_in;
  71     icon_index = icon_index_in;
  72     options |= PROPERTIES_ICON;
  73   }
  74
  75   void set_app_id(const string16& app_id_in) {
  76     app_id = app_id_in;
  77     options |= PROPERTIES_APP_ID;
  78   }
  79
  80   void set_dual_mode(bool dual_mode_in) {
  81     dual_mode = dual_mode_in;
  82     options |= PROPERTIES_DUAL_MODE;
  83   }
  84
  85   // The target to launch from this shortcut. This is mandatory when creating
  86   // a shortcut.
  87   FilePath target;
  88   // The name of the working directory when launching the shortcut.
  89   FilePath working_dir;
  90   // The arguments to be applied to |target| when launching from this shortcut.
  91   // The length of this string must be less than MAX_PATH.
  92   string16 arguments;
  93   // The localized description of the shortcut.
  94   // The length of this string must be less than MAX_PATH.
  95   string16 description;
  96   // The path to the icon (can be a dll or exe, in which case |icon_index| is
  97   // the resource id).
  98   FilePath icon;
  99   int icon_index;
 100   // The app model id for the shortcut (Win7+).
 101   string16 app_id;
 102   // Whether this is a dual mode shortcut (Win8+).
 103   bool dual_mode;
 104   // Bitfield made of IndividualProperties. Properties set in |options| will be
 105   // set on the shortcut, others will be ignored.
 106   uint32 options;
 107 };
 108
 109 // This method creates (or updates) a shortcut link at |shortcut_path| using the
 110 // information given through |properties|.
 111 // Ensure you have initialized COM before calling into this function.
 112 // |operation|: a choice from the ShortcutOperation enum.
 113 // If |operation| is SHORTCUT_REPLACE_EXISTING or SHORTCUT_UPDATE_EXISTING and
 114 // |shortcut_path| does not exist, this method is a no-op and returns false.
 115 BASE_EXPORT bool CreateOrUpdateShortcutLink(
 116     const FilePath& shortcut_path,
 117     const ShortcutProperties& properties,
 118     ShortcutOperation operation);
 119
 120 // Resolve Windows shortcut (.LNK file)
 121 // This methods tries to resolve a shortcut .LNK file. The path of the shortcut
 122 // to resolve is in |shortcut_path|. If |target_path| is not NULL, the target
 123 // will be resolved and placed in |target_path|. If |args| is not NULL, the
 124 // arguments will be retrieved and placed in |args|. The function returns true
 125 // if all requested fields are found successfully.
 126 // Callers can safely use the same variable for both |shortcut_path| and
 127 // |target_path|.
 128 BASE_EXPORT bool ResolveShortcut(const FilePath& shortcut_path,
 129                                  FilePath* target_path,
 130                                  string16* args);
 131
 132 // Pins a shortcut to the Windows 7 taskbar. The shortcut file must already
 133 // exist and be a shortcut that points to an executable. The app id of the
 134 // shortcut is used to group windows and must be set correctly.
 135 BASE_EXPORT bool TaskbarPinShortcutLink(const wchar_t* shortcut);
 136
 137 // Unpins a shortcut from the Windows 7 taskbar. The shortcut must exist and
 138 // already be pinned to the taskbar. The app id of the shortcut is used as the
 139 // identifier for the taskbar item to remove and must be set correctly.
 140 BASE_EXPORT bool TaskbarUnpinShortcutLink(const wchar_t* shortcut);
 141
 142 }  // namespace win
 143 }  // namespace base
 144
 145 #endif  // BASE_WIN_SHORTCUT_H_