shortcut.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  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. #ifndef BASE_WIN_SHORTCUT_H_
  5. #define BASE_WIN_SHORTCUT_H_
  6. #include <guiddef.h>
  7. #include <stdint.h>
  8. #include "base/base_export.h"
  9. #include "base/check.h"
  10. #include "base/files/file_path.h"
  11. namespace base {
  12. namespace win {
  13. enum class ShortcutOperation {
  14. // Create a new shortcut (overwriting if necessary).
  15. kCreateAlways = 0,
  16. // Overwrite an existing shortcut (fails if the shortcut doesn't exist).
  17. // If the arguments are not specified on the new shortcut, keep the old
  18. // shortcut's arguments.
  19. kReplaceExisting,
  20. // Update specified properties only on an existing shortcut.
  21. kUpdateExisting,
  22. };
  23. // Properties for shortcuts. Properties set will be applied to the shortcut on
  24. // creation/update, others will be ignored.
  25. // Callers are encouraged to use the setters provided which take care of
  26. // setting |options| as desired.
  27. struct BASE_EXPORT ShortcutProperties {
  28. using IndividualProperties = uint32_t;
  29. static constexpr IndividualProperties PROPERTIES_TARGET = 1U << 0;
  30. static constexpr IndividualProperties PROPERTIES_WORKING_DIR = 1U << 1;
  31. static constexpr IndividualProperties PROPERTIES_ARGUMENTS = 1U << 2;
  32. static constexpr IndividualProperties PROPERTIES_DESCRIPTION = 1U << 3;
  33. static constexpr IndividualProperties PROPERTIES_ICON = 1U << 4;
  34. static constexpr IndividualProperties PROPERTIES_APP_ID = 1U << 5;
  35. static constexpr IndividualProperties PROPERTIES_DUAL_MODE = 1U << 6;
  36. static constexpr IndividualProperties PROPERTIES_TOAST_ACTIVATOR_CLSID = 1U
  37. << 7;
  38. // Be sure to update the values below when adding a new property.
  39. static constexpr IndividualProperties PROPERTIES_ALL =
  40. PROPERTIES_TARGET | PROPERTIES_WORKING_DIR | PROPERTIES_ARGUMENTS |
  41. PROPERTIES_DESCRIPTION | PROPERTIES_ICON | PROPERTIES_APP_ID |
  42. PROPERTIES_DUAL_MODE | PROPERTIES_TOAST_ACTIVATOR_CLSID;
  43. ShortcutProperties();
  44. ShortcutProperties(const ShortcutProperties& other);
  45. ~ShortcutProperties();
  46. void set_target(const FilePath& target_in) {
  47. target = target_in;
  48. options |= PROPERTIES_TARGET;
  49. }
  50. void set_working_dir(const FilePath& working_dir_in) {
  51. working_dir = working_dir_in;
  52. options |= PROPERTIES_WORKING_DIR;
  53. }
  54. void set_arguments(const std::wstring& arguments_in) {
  55. arguments = arguments_in;
  56. options |= PROPERTIES_ARGUMENTS;
  57. }
  58. void set_description(const std::wstring& description_in);
  59. void set_icon(const FilePath& icon_in, int icon_index_in) {
  60. icon = icon_in;
  61. icon_index = icon_index_in;
  62. options |= PROPERTIES_ICON;
  63. }
  64. void set_app_id(const std::wstring& app_id_in) {
  65. app_id = app_id_in;
  66. options |= PROPERTIES_APP_ID;
  67. }
  68. void set_dual_mode(bool dual_mode_in) {
  69. dual_mode = dual_mode_in;
  70. options |= PROPERTIES_DUAL_MODE;
  71. }
  72. void set_toast_activator_clsid(const CLSID& toast_activator_clsid_in) {
  73. toast_activator_clsid = toast_activator_clsid_in;
  74. options |= PROPERTIES_TOAST_ACTIVATOR_CLSID;
  75. }
  76. // The target to launch from this shortcut. This is mandatory when creating
  77. // a shortcut.
  78. FilePath target;
  79. // The name of the working directory when launching the shortcut.
  80. FilePath working_dir;
  81. // The arguments to be applied to |target| when launching from this shortcut.
  82. std::wstring arguments;
  83. // The localized description of the shortcut.
  84. // The length of this string must be no larger than INFOTIPSIZE.
  85. std::wstring description;
  86. // The path to the icon (can be a dll or exe, in which case |icon_index| is
  87. // the resource id).
  88. FilePath icon;
  89. int icon_index = -1;
  90. // The app model id for the shortcut.
  91. std::wstring app_id;
  92. // Whether this is a dual mode shortcut (Win8+).
  93. bool dual_mode = false;
  94. // The CLSID of the COM object registered with the OS via the shortcut. This
  95. // is for app activation via user interaction with a toast notification in the
  96. // Action Center. (Win10 version 1607, build 14393, and beyond).
  97. CLSID toast_activator_clsid;
  98. // Bitfield made of IndividualProperties. Properties set in |options| will be
  99. // set on the shortcut, others will be ignored.
  100. uint32_t options = 0U;
  101. };
  102. // This method creates (or updates) a shortcut link at `shortcut_path` using the
  103. // information given through `properties`.
  104. // Ensure you have initialized COM before calling into this function.
  105. // `operation`: a choice from the ShortcutOperation enum.
  106. // If `operation` is kReplaceExisting or kUpdateExisting and
  107. // `shortcut_path` does not exist, this method is a no-op and returns false.
  108. BASE_EXPORT bool CreateOrUpdateShortcutLink(
  109. const FilePath& shortcut_path,
  110. const ShortcutProperties& properties,
  111. ShortcutOperation operation);
  112. // Resolves Windows shortcut (.LNK file).
  113. // This methods tries to resolve selected properties of a shortcut .LNK file.
  114. // The path of the shortcut to resolve is in |shortcut_path|. |options| is a bit
  115. // field composed of ShortcutProperties::IndividualProperties, to specify which
  116. // properties to read. It should be non-0. The resulting data are read into
  117. // |properties|, which must not be NULL. Note: PROPERTIES_TARGET will retrieve
  118. // the target path as stored in the shortcut but won't attempt to resolve that
  119. // path so it may not be valid. The function returns true if all requested
  120. // properties are successfully read. Otherwise some reads have failed and
  121. // intermediate values written to |properties| should be ignored.
  122. BASE_EXPORT bool ResolveShortcutProperties(const FilePath& shortcut_path,
  123. uint32_t options,
  124. ShortcutProperties* properties);
  125. // Resolves Windows shortcut (.LNK file).
  126. // This is a wrapper to ResolveShortcutProperties() to handle the common use
  127. // case of resolving target and arguments. |target_path| and |args| are
  128. // optional output variables that are ignored if NULL (but at least one must be
  129. // non-NULL). The function returns true if all requested fields are found
  130. // successfully. Callers can safely use the same variable for both
  131. // |shortcut_path| and |target_path|.
  132. BASE_EXPORT bool ResolveShortcut(const FilePath& shortcut_path,
  133. FilePath* target_path,
  134. std::wstring* args);
  135. } // namespace win
  136. } // namespace base
  137. #endif // BASE_WIN_SHORTCUT_H_