base/win/registry.h

   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_REGISTRY_H_
   6 #define BASE_WIN_REGISTRY_H_
   7
   8 #include <windows.h>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/base_export.h"
  13 #include "base/basictypes.h"
  14 #include "base/stl_util.h"
  15 #include "base/win/object_watcher.h"
  16 #include "base/win/scoped_handle.h"
  17
  18 namespace base {
  19 namespace win {
  20
  21 // Utility class to read, write and manipulate the Windows Registry.
  22 // Registry vocabulary primer: a "key" is like a folder, in which there
  23 // are "values", which are <name, data> pairs, with an associated data type.
  24 //
  25 // Note:
  26 // ReadValue family of functions guarantee that the return arguments
  27 // are not touched in case of failure.
  28 class BASE_EXPORT RegKey {
  29  public:
  30   // Called from the MessageLoop when the key changes.
  31   typedef base::Callback<void()> ChangeCallback;
  32
  33   RegKey();
  34   explicit RegKey(HKEY key);
  35   RegKey(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  36   ~RegKey();
  37
  38   LONG Create(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  39
  40   LONG CreateWithDisposition(HKEY rootkey, const wchar_t* subkey,
  41                              DWORD* disposition, REGSAM access);
  42
  43   // Creates a subkey or open it if it already exists.
  44   LONG CreateKey(const wchar_t* name, REGSAM access);
  45
  46   // Opens an existing reg key.
  47   LONG Open(HKEY rootkey, const wchar_t* subkey, REGSAM access);
  48
  49   // Opens an existing reg key, given the relative key name.
  50   LONG OpenKey(const wchar_t* relative_key_name, REGSAM access);
  51
  52   // Closes this reg key.
  53   void Close();
  54
  55   // Replaces the handle of the registry key and takes ownership of the handle.
  56   void Set(HKEY key);
  57
  58   // Transfers ownership away from this object.
  59   HKEY Take();
  60
  61   // Returns false if this key does not have the specified value, or if an error
  62   // occurrs while attempting to access it.
  63   bool HasValue(const wchar_t* value_name) const;
  64
  65   // Returns the number of values for this key, or 0 if the number cannot be
  66   // determined.
  67   DWORD GetValueCount() const;
  68
  69   // Determine the nth value's name.
  70   LONG GetValueNameAt(int index, std::wstring* name) const;
  71
  72   // True while the key is valid.
  73   bool Valid() const { return key_ != NULL; }
  74
  75   // Kill a key and everything that live below it; please be careful when using
  76   // it.
  77   LONG DeleteKey(const wchar_t* name);
  78
  79   // Deletes an empty subkey.  If the subkey has subkeys or values then this
  80   // will fail.
  81   LONG DeleteEmptyKey(const wchar_t* name);
  82
  83   // Deletes a single value within the key.
  84   LONG DeleteValue(const wchar_t* name);
  85
  86   // Getters:
  87
  88   // Returns an int32 value. If |name| is NULL or empty, returns the default
  89   // value, if any.
  90   LONG ReadValueDW(const wchar_t* name, DWORD* out_value) const;
  91
  92   // Returns an int64 value. If |name| is NULL or empty, returns the default
  93   // value, if any.
  94   LONG ReadInt64(const wchar_t* name, int64* out_value) const;
  95
  96   // Returns a string value. If |name| is NULL or empty, returns the default
  97   // value, if any.
  98   LONG ReadValue(const wchar_t* name, std::wstring* out_value) const;
  99
 100   // Reads a REG_MULTI_SZ registry field into a vector of strings. Clears
 101   // |values| initially and adds further strings to the list. Returns
 102   // ERROR_CANTREAD if type is not REG_MULTI_SZ.
 103   LONG ReadValues(const wchar_t* name, std::vector<std::wstring>* values);
 104
 105   // Returns raw data. If |name| is NULL or empty, returns the default
 106   // value, if any.
 107   LONG ReadValue(const wchar_t* name,
 108                  void* data,
 109                  DWORD* dsize,
 110                  DWORD* dtype) const;
 111
 112   // Setters:
 113
 114   // Sets an int32 value.
 115   LONG WriteValue(const wchar_t* name, DWORD in_value);
 116
 117   // Sets a string value.
 118   LONG WriteValue(const wchar_t* name, const wchar_t* in_value);
 119
 120   // Sets raw data, including type.
 121   LONG WriteValue(const wchar_t* name,
 122                   const void* data,
 123                   DWORD dsize,
 124                   DWORD dtype);
 125
 126   // Starts watching the key to see if any of its values have changed.
 127   // The key must have been opened with the KEY_NOTIFY access privilege.
 128   // Returns true on success.
 129   // To stop watching, delete this RegKey object. To continue watching the
 130   // object after the callback is invoked, call StartWatching again.
 131   bool StartWatching(const ChangeCallback& callback);
 132
 133   HKEY Handle() const { return key_; }
 134
 135  private:
 136   class Watcher;
 137
 138   // Calls RegDeleteKeyEx on supported platforms, alternatively falls back to
 139   // RegDeleteKey.
 140   static LONG RegDeleteKeyExWrapper(HKEY hKey,
 141                                     const wchar_t* lpSubKey,
 142                                     REGSAM samDesired,
 143                                     DWORD Reserved);
 144
 145   // Recursively deletes a key and all of its subkeys.
 146   static LONG RegDelRecurse(HKEY root_key,
 147                             const std::wstring& name,
 148                             REGSAM access);
 149
 150   HKEY key_;  // The registry key being iterated.
 151   REGSAM wow64access_;
 152   scoped_ptr<Watcher> key_watcher_;
 153
 154   DISALLOW_COPY_AND_ASSIGN(RegKey);
 155 };
 156
 157 // Iterates the entries found in a particular folder on the registry.
 158 class BASE_EXPORT RegistryValueIterator {
 159  public:
 160   // Construct a Registry Value Iterator with default WOW64 access.
 161   RegistryValueIterator(HKEY root_key, const wchar_t* folder_key);
 162
 163   // Construct a Registry Key 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   RegistryValueIterator(HKEY root_key,
 169                         const wchar_t* folder_key,
 170                         REGSAM wow64access);
 171
 172   ~RegistryValueIterator();
 173
 174   DWORD ValueCount() const;
 175
 176   // True while the iterator is valid.
 177   bool Valid() const;
 178
 179   // Advances to the next registry entry.
 180   void operator++();
 181
 182   const wchar_t* Name() const { return name_.c_str(); }
 183   const wchar_t* Value() const { return vector_as_array(&value_); }
 184   // ValueSize() is in bytes.
 185   DWORD ValueSize() const { return value_size_; }
 186   DWORD Type() const { return type_; }
 187
 188   int Index() const { return index_; }
 189
 190  private:
 191   // Read in the current values.
 192   bool Read();
 193
 194   void Initialize(HKEY root_key, const wchar_t* folder_key, REGSAM wow64access);
 195
 196   // The registry key being iterated.
 197   HKEY key_;
 198
 199   // Current index of the iteration.
 200   int index_;
 201
 202   // Current values.
 203   std::wstring name_;
 204   std::vector<wchar_t> value_;
 205   DWORD value_size_;
 206   DWORD type_;
 207
 208   DISALLOW_COPY_AND_ASSIGN(RegistryValueIterator);
 209 };
 210
 211 class BASE_EXPORT RegistryKeyIterator {
 212  public:
 213   // Construct a Registry Key Iterator with default WOW64 access.
 214   RegistryKeyIterator(HKEY root_key, const wchar_t* folder_key);
 215
 216   // Construct a Registry Value Iterator with specific WOW64 access, one of
 217   // KEY_WOW64_32KEY or KEY_WOW64_64KEY, or 0.
 218   // Note: |wow64access| should be the same access used to open |root_key|
 219   // previously, or a predefined key (e.g. HKEY_LOCAL_MACHINE).
 220   // See http://msdn.microsoft.com/en-us/library/windows/desktop/aa384129.aspx.
 221   RegistryKeyIterator(HKEY root_key,
 222                       const wchar_t* folder_key,
 223                       REGSAM wow64access);
 224
 225   ~RegistryKeyIterator();
 226
 227   DWORD SubkeyCount() const;
 228
 229   // True while the iterator is valid.
 230   bool Valid() const;
 231
 232   // Advances to the next entry in the folder.
 233   void operator++();
 234
 235   const wchar_t* Name() const { return name_; }
 236
 237   int Index() const { return index_; }
 238
 239  private:
 240   // Read in the current values.
 241   bool Read();
 242
 243   void Initialize(HKEY root_key, const wchar_t* folder_key, REGSAM wow64access);
 244
 245   // The registry key being iterated.
 246   HKEY key_;
 247
 248   // Current index of the iteration.
 249   int index_;
 250
 251   wchar_t name_[MAX_PATH];
 252
 253   DISALLOW_COPY_AND_ASSIGN(RegistryKeyIterator);
 254 };
 255
 256 }  // namespace win
 257 }  // namespace base
 258
 259 #endif  // BASE_WIN_REGISTRY_H_