1 // Copyright 2012 The Chromium Authors 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 <guiddef.h> 9 #include <stdint.h> 10 11 #include "base/base_export.h" 12 #include "base/check.h" 13 #include "base/files/file_path.h" 14 15 namespace base { 16 namespace win { 17 18 enum class ShortcutOperation { 19 // Create a new shortcut (overwriting if necessary). 20 kCreateAlways = 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 kReplaceExisting, 25 // Update specified properties only on an existing shortcut. 26 kUpdateExisting, 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 using IndividualProperties = uint32_t; 35 static constexpr IndividualProperties PROPERTIES_TARGET = 1U << 0; 36 static constexpr IndividualProperties PROPERTIES_WORKING_DIR = 1U << 1; 37 static constexpr IndividualProperties PROPERTIES_ARGUMENTS = 1U << 2; 38 static constexpr IndividualProperties PROPERTIES_DESCRIPTION = 1U << 3; 39 static constexpr IndividualProperties PROPERTIES_ICON = 1U << 4; 40 static constexpr IndividualProperties PROPERTIES_APP_ID = 1U << 5; 41 static constexpr IndividualProperties PROPERTIES_DUAL_MODE = 1U << 6; 42 static constexpr IndividualProperties PROPERTIES_TOAST_ACTIVATOR_CLSID = 1U 43 << 7; 44 // Be sure to update the values below when adding a new property. 45 static constexpr IndividualProperties PROPERTIES_ALL = 46 PROPERTIES_TARGET | PROPERTIES_WORKING_DIR | PROPERTIES_ARGUMENTS | 47 PROPERTIES_DESCRIPTION | PROPERTIES_ICON | PROPERTIES_APP_ID | 48 PROPERTIES_DUAL_MODE | PROPERTIES_TOAST_ACTIVATOR_CLSID; 49 50 ShortcutProperties(); 51 ShortcutProperties(const ShortcutProperties& other); 52 ~ShortcutProperties(); 53 set_targetShortcutProperties54 void set_target(const FilePath& target_in) { 55 target = target_in; 56 options |= PROPERTIES_TARGET; 57 } 58 set_working_dirShortcutProperties59 void set_working_dir(const FilePath& working_dir_in) { 60 working_dir = working_dir_in; 61 options |= PROPERTIES_WORKING_DIR; 62 } 63 set_argumentsShortcutProperties64 void set_arguments(const std::wstring& arguments_in) { 65 arguments = arguments_in; 66 options |= PROPERTIES_ARGUMENTS; 67 } 68 69 void set_description(const std::wstring& description_in); 70 set_iconShortcutProperties71 void set_icon(const FilePath& icon_in, int icon_index_in) { 72 icon = icon_in; 73 icon_index = icon_index_in; 74 options |= PROPERTIES_ICON; 75 } 76 set_app_idShortcutProperties77 void set_app_id(const std::wstring& app_id_in) { 78 app_id = app_id_in; 79 options |= PROPERTIES_APP_ID; 80 } 81 set_dual_modeShortcutProperties82 void set_dual_mode(bool dual_mode_in) { 83 dual_mode = dual_mode_in; 84 options |= PROPERTIES_DUAL_MODE; 85 } 86 set_toast_activator_clsidShortcutProperties87 void set_toast_activator_clsid(const CLSID& toast_activator_clsid_in) { 88 toast_activator_clsid = toast_activator_clsid_in; 89 options |= PROPERTIES_TOAST_ACTIVATOR_CLSID; 90 } 91 92 // The target to launch from this shortcut. This is mandatory when creating 93 // a shortcut. 94 FilePath target; 95 // The name of the working directory when launching the shortcut. 96 FilePath working_dir; 97 // The arguments to be applied to |target| when launching from this shortcut. 98 std::wstring arguments; 99 // The localized description of the shortcut. 100 // The length of this string must be no larger than INFOTIPSIZE. 101 std::wstring description; 102 // The path to the icon (can be a dll or exe, in which case |icon_index| is 103 // the resource id). 104 FilePath icon; 105 int icon_index = -1; 106 // The app model id for the shortcut. 107 std::wstring app_id; 108 // Whether this is a dual mode shortcut (Windows). 109 bool dual_mode = false; 110 // The CLSID of the COM object registered with the OS via the shortcut. This 111 // is for app activation via user interaction with a toast notification in the 112 // Action Center. (Win10 version 1607, build 14393, and beyond). 113 CLSID toast_activator_clsid; 114 // Bitfield made of IndividualProperties. Properties set in |options| will be 115 // set on the shortcut, others will be ignored. 116 uint32_t options = 0U; 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 kReplaceExisting or kUpdateExisting 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_t 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 std::wstring* args); 154 155 } // namespace win 156 } // namespace base 157 158 #endif // BASE_WIN_SHORTCUT_H_ 159