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