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 14namespace base { 15namespace win { 16 17enum 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. 32struct 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. 115BASE_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|. 128BASE_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. 135BASE_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. 140BASE_EXPORT bool TaskbarUnpinShortcutLink(const wchar_t* shortcut); 141 142} // namespace win 143} // namespace base 144 145#endif // BASE_WIN_SHORTCUT_H_ 146