Home | History | Annotate | Download | only in win 
      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 
     51   ShortcutProperties() : icon_index(-1), dual_mode(false), options(0U) {}
     52 
     53   void set_target(const FilePath& target_in) {
     54     target = target_in;
     55     options |= PROPERTIES_TARGET;
     56   }
     57 
     58   void set_working_dir(const FilePath& working_dir_in) {
     59     working_dir = working_dir_in;
     60     options |= PROPERTIES_WORKING_DIR;
     61   }
     62 
     63   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 
     70   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 
     77   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 
     83   void set_app_id(const string16& app_id_in) {
     84     app_id = app_id_in;
     85     options |= PROPERTIES_APP_ID;
     86   }
     87 
     88   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. The function returns true if all
    134 // requested properties are successfully read. Otherwise some reads have failed
    135 // and intermediate values written to |properties| should be ignored.
    136 BASE_EXPORT bool ResolveShortcutProperties(const FilePath& shortcut_path,
    137                                            uint32 options,
    138                                            ShortcutProperties* properties);
    139 
    140 // Resolves Windows shortcut (.LNK file).
    141 // This is a wrapper to ResolveShortcutProperties() to handle the common use
    142 // case of resolving target and arguments. |target_path| and |args| are
    143 // optional output variables that are ignored if NULL (but at least one must be
    144 // non-NULL). The function returns true if all requested fields are found
    145 // successfully. Callers can safely use the same variable for both
    146 // |shortcut_path| and |target_path|.
    147 BASE_EXPORT bool ResolveShortcut(const FilePath& shortcut_path,
    148                                  FilePath* target_path,
    149                                  string16* args);
    150 
    151 // Pins a shortcut to the Windows 7 taskbar. The shortcut file must already
    152 // exist and be a shortcut that points to an executable. The app id of the
    153 // shortcut is used to group windows and must be set correctly.
    154 BASE_EXPORT bool TaskbarPinShortcutLink(const wchar_t* shortcut);
    155 
    156 // Unpins a shortcut from the Windows 7 taskbar. The shortcut must exist and
    157 // already be pinned to the taskbar. The app id of the shortcut is used as the
    158 // identifier for the taskbar item to remove and must be set correctly.
    159 BASE_EXPORT bool TaskbarUnpinShortcutLink(const wchar_t* shortcut);
    160 
    161 }  // namespace win
    162 }  // namespace base
    163 
    164 #endif  // BASE_WIN_SHORTCUT_H_
    165