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