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 ShortcutPropertiesShortcutProperties51 ShortcutProperties() : icon_index(-1), dual_mode(false), options(0U) {} 52 set_targetShortcutProperties53 void set_target(const FilePath& target_in) { 54 target = target_in; 55 options |= PROPERTIES_TARGET; 56 } 57 set_working_dirShortcutProperties58 void set_working_dir(const FilePath& working_dir_in) { 59 working_dir = working_dir_in; 60 options |= PROPERTIES_WORKING_DIR; 61 } 62 set_argumentsShortcutProperties63 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 set_descriptionShortcutProperties70 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 set_iconShortcutProperties77 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 set_app_idShortcutProperties83 void set_app_id(const string16& app_id_in) { 84 app_id = app_id_in; 85 options |= PROPERTIES_APP_ID; 86 } 87 set_dual_modeShortcutProperties88 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_ 167