registry.h 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263
  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_REGISTRY_H_
  5. #define BASE_WIN_REGISTRY_H_
  6. #include <stdint.h>
  7. #include <memory>
  8. #include <string>
  9. #include <vector>
  10. #include "base/base_export.h"
  11. #include "base/callback_forward.h"
  12. #include "base/win/windows_types.h"
  13. namespace base {
  14. namespace win {
  15. // Utility class to read, write and manipulate the Windows Registry.
  16. // Registry vocabulary primer: a "key" is like a folder, in which there
  17. // are "values", which are <name, data> pairs, with an associated data type.
  18. //
  19. // Note:
  20. // * ReadValue family of functions guarantee that the out-parameter
  21. // is not touched in case of failure.
  22. // * Functions returning LONG indicate success as ERROR_SUCCESS or an
  23. // error as a (non-zero) win32 error code.
  24. class BASE_EXPORT RegKey {
  25. public:
  26. // Called from the MessageLoop when the key changes.
  27. using ChangeCallback = OnceCallback<void()>;
  28. RegKey();
  29. explicit RegKey(HKEY key);
  30. RegKey(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  31. RegKey(RegKey&& other) noexcept;
  32. RegKey& operator=(RegKey&& other);
  33. RegKey(const RegKey&) = delete;
  34. RegKey& operator=(const RegKey&) = delete;
  35. ~RegKey();
  36. LONG Create(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  37. LONG CreateWithDisposition(HKEY rootkey,
  38. const wchar_t* subkey,
  39. DWORD* disposition,
  40. REGSAM access);
  41. // Creates a subkey or open it if it already exists.
  42. LONG CreateKey(const wchar_t* name, REGSAM access);
  43. // Opens an existing reg key.
  44. LONG Open(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  45. // Opens an existing reg key, given the relative key name.
  46. LONG OpenKey(const wchar_t* relative_key_name, REGSAM access);
  47. // Closes this reg key.
  48. void Close();
  49. // Replaces the handle of the registry key and takes ownership of the handle.
  50. void Set(HKEY key);
  51. // Transfers ownership away from this object.
  52. HKEY Take();
  53. // Returns false if this key does not have the specified value, or if an error
  54. // occurrs while attempting to access it.
  55. bool HasValue(const wchar_t* value_name) const;
  56. // Returns the number of values for this key, or 0 if the number cannot be
  57. // determined.
  58. DWORD GetValueCount() const;
  59. // Returns the last write time or 0 on failure.
  60. FILETIME GetLastWriteTime() const;
  61. // Determines the nth value's name.
  62. LONG GetValueNameAt(DWORD index, std::wstring* name) const;
  63. // True while the key is valid.
  64. bool Valid() const { return key_ != nullptr; }
  65. // Kills a key and everything that lives below it; please be careful when
  66. // using it.
  67. LONG DeleteKey(const wchar_t* name);
  68. // Deletes an empty subkey. If the subkey has subkeys or values then this
  69. // will fail.
  70. LONG DeleteEmptyKey(const wchar_t* name);
  71. // Deletes a single value within the key.
  72. LONG DeleteValue(const wchar_t* name);
  73. // Getters:
  74. // Reads a REG_DWORD (uint32_t) into |out_value|. If |name| is null or empty,
  75. // reads the key's default value, if any.
  76. LONG ReadValueDW(const wchar_t* name, DWORD* out_value) const;
  77. // Reads a REG_QWORD (int64_t) into |out_value|. If |name| is null or empty,
  78. // reads the key's default value, if any.
  79. LONG ReadInt64(const wchar_t* name, int64_t* out_value) const;
  80. // Reads a string into |out_value|. If |name| is null or empty, reads
  81. // the key's default value, if any.
  82. LONG ReadValue(const wchar_t* name, std::wstring* out_value) const;
  83. // Reads a REG_MULTI_SZ registry field into a vector of strings. Clears
  84. // |values| initially and adds further strings to the list. Returns
  85. // ERROR_CANTREAD if type is not REG_MULTI_SZ.
  86. LONG ReadValues(const wchar_t* name, std::vector<std::wstring>* values);
  87. // Reads raw data into |data|. If |name| is null or empty, reads the key's
  88. // default value, if any.
  89. LONG ReadValue(const wchar_t* name,
  90. void* data,
  91. DWORD* dsize,
  92. DWORD* dtype) const;
  93. // Setters:
  94. // Sets an int32_t value.
  95. LONG WriteValue(const wchar_t* name, DWORD in_value);
  96. // Sets a string value.
  97. LONG WriteValue(const wchar_t* name, const wchar_t* in_value);
  98. // Sets raw data, including type.
  99. LONG WriteValue(const wchar_t* name,
  100. const void* data,
  101. DWORD dsize,
  102. DWORD dtype);
  103. // Starts watching the key to see if any of its values have changed.
  104. // The key must have been opened with the KEY_NOTIFY access privilege.
  105. // Returns true on success.
  106. // To stop watching, delete this RegKey object. To continue watching the
  107. // object after the callback is invoked, call StartWatching again.
  108. bool StartWatching(ChangeCallback callback);
  109. HKEY Handle() const { return key_; }
  110. private:
  111. class Watcher;
  112. // Recursively deletes a key and all of its subkeys.
  113. static LONG RegDelRecurse(HKEY root_key, const wchar_t* name, REGSAM access);
  114. HKEY key_ = nullptr; // The registry key being iterated.
  115. REGSAM wow64access_ = 0;
  116. std::unique_ptr<Watcher> key_watcher_;
  117. };
  118. // Iterates the entries found in a particular folder on the registry.
  119. class BASE_EXPORT RegistryValueIterator {
  120. public:
  121. // Constructs a Registry Value Iterator with default WOW64 access.
  122. RegistryValueIterator(HKEY root_key, const wchar_t* folder_key);
  123. // Constructs a Registry Key Iterator with specific WOW64 access, one of
  124. // KEY_WOW64_32KEY or KEY_WOW64_64KEY, or 0.
  125. // Note: |wow64access| should be the same access used to open |root_key|
  126. // previously, or a predefined key (e.g. HKEY_LOCAL_MACHINE).
  127. // See http://msdn.microsoft.com/en-us/library/windows/desktop/aa384129.aspx.
  128. RegistryValueIterator(HKEY root_key,
  129. const wchar_t* folder_key,
  130. REGSAM wow64access);
  131. RegistryValueIterator(const RegistryValueIterator&) = delete;
  132. RegistryValueIterator& operator=(const RegistryValueIterator&) = delete;
  133. ~RegistryValueIterator();
  134. DWORD ValueCount() const;
  135. // True while the iterator is valid.
  136. bool Valid() const;
  137. // Advances to the next registry entry.
  138. void operator++();
  139. const wchar_t* Name() const { return name_.c_str(); }
  140. const wchar_t* Value() const { return value_.data(); }
  141. // ValueSize() is in bytes.
  142. DWORD ValueSize() const { return value_size_; }
  143. DWORD Type() const { return type_; }
  144. DWORD Index() const { return index_; }
  145. private:
  146. // Reads in the current values.
  147. bool Read();
  148. void Initialize(HKEY root_key, const wchar_t* folder_key, REGSAM wow64access);
  149. // The registry key being iterated.
  150. HKEY key_;
  151. // Current index of the iteration.
  152. DWORD index_;
  153. // Current values.
  154. std::wstring name_;
  155. std::vector<wchar_t> value_;
  156. DWORD value_size_;
  157. DWORD type_;
  158. };
  159. class BASE_EXPORT RegistryKeyIterator {
  160. public:
  161. // Constructs a Registry Key Iterator with default WOW64 access.
  162. RegistryKeyIterator(HKEY root_key, const wchar_t* folder_key);
  163. // Constructs a Registry Value Iterator with specific WOW64 access, one of
  164. // KEY_WOW64_32KEY or KEY_WOW64_64KEY, or 0.
  165. // Note: |wow64access| should be the same access used to open |root_key|
  166. // previously, or a predefined key (e.g. HKEY_LOCAL_MACHINE).
  167. // See http://msdn.microsoft.com/en-us/library/windows/desktop/aa384129.aspx.
  168. RegistryKeyIterator(HKEY root_key,
  169. const wchar_t* folder_key,
  170. REGSAM wow64access);
  171. RegistryKeyIterator(const RegistryKeyIterator&) = delete;
  172. RegistryKeyIterator& operator=(const RegistryKeyIterator&) = delete;
  173. ~RegistryKeyIterator();
  174. DWORD SubkeyCount() const;
  175. // True while the iterator is valid.
  176. bool Valid() const;
  177. // Advances to the next entry in the folder.
  178. void operator++();
  179. const wchar_t* Name() const { return name_; }
  180. DWORD Index() const { return index_; }
  181. private:
  182. // Reads in the current values.
  183. bool Read();
  184. void Initialize(HKEY root_key, const wchar_t* folder_key, REGSAM wow64access);
  185. // The registry key being iterated.
  186. HKEY key_;
  187. // Current index of the iteration.
  188. DWORD index_;
  189. wchar_t name_[MAX_PATH];
  190. };
  191. } // namespace win
  192. } // namespace base
  193. #endif // BASE_WIN_REGISTRY_H_