1 // Copyright 2015 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
7 // Package registry provides access to the Windows registry.
9 // Here is a simple example, opening a registry key and reading a string value from it.
11 // k, err := registry.OpenKey(registry.LOCAL_MACHINE, `SOFTWARE\Microsoft\Windows NT\CurrentVersion`, registry.QUERY_VALUE)
17 // s, _, err := k.GetStringValue("SystemRoot")
21 // fmt.Printf("Windows system root is %q\n", s)
32 // Registry key security and access rights.
33 // See https://msdn.microsoft.com/en-us/library/windows/desktop/ms724878.aspx
37 CREATE_SUB_KEY = 0x00004
38 ENUMERATE_SUB_KEYS = 0x00008
49 // Key is a handle to an open Windows registry key.
50 // Keys can be obtained by calling OpenKey; there are
51 // also some predefined root keys such as CURRENT_USER.
52 // Keys can be used directly in the Windows API.
53 type Key syscall.Handle
56 // Windows defines some predefined root keys that are always open.
57 // An application can use these keys as entry points to the registry.
58 // Normally these keys are used in OpenKey to open new keys,
59 // but they can also be used anywhere a Key is required.
60 CLASSES_ROOT = Key(syscall.HKEY_CLASSES_ROOT)
61 CURRENT_USER = Key(syscall.HKEY_CURRENT_USER)
62 LOCAL_MACHINE = Key(syscall.HKEY_LOCAL_MACHINE)
63 USERS = Key(syscall.HKEY_USERS)
64 CURRENT_CONFIG = Key(syscall.HKEY_CURRENT_CONFIG)
65 PERFORMANCE_DATA = Key(syscall.HKEY_PERFORMANCE_DATA)
68 // Close closes open key k.
69 func (k Key) Close() error {
70 return syscall.RegCloseKey(syscall.Handle(k))
73 // OpenKey opens a new key with path name relative to key k.
74 // It accepts any open key, including CURRENT_USER and others,
75 // and returns the new key and an error.
76 // The access parameter specifies desired access rights to the
78 func OpenKey(k Key, path string, access uint32) (Key, error) {
79 p, err := syscall.UTF16PtrFromString(path)
83 var subkey syscall.Handle
84 err = syscall.RegOpenKeyEx(syscall.Handle(k), p, 0, access, &subkey)
88 return Key(subkey), nil
91 // OpenRemoteKey opens a predefined registry key on another
92 // computer pcname. The key to be opened is specified by k, but
93 // can only be one of LOCAL_MACHINE, PERFORMANCE_DATA or USERS.
94 // If pcname is "", OpenRemoteKey returns local computer key.
95 func OpenRemoteKey(pcname string, k Key) (Key, error) {
99 p, err = syscall.UTF16PtrFromString(`\\` + pcname)
104 var remoteKey syscall.Handle
105 err = regConnectRegistry(p, syscall.Handle(k), &remoteKey)
109 return Key(remoteKey), nil
112 // ReadSubKeyNames returns the names of subkeys of key k.
113 // The parameter n controls the number of returned names,
114 // analogous to the way os.File.Readdirnames works.
115 func (k Key) ReadSubKeyNames(n int) ([]string, error) {
116 names := make([]string, 0)
117 // Registry key size limit is 255 bytes and described there:
118 // https://msdn.microsoft.com/library/windows/desktop/ms724872.aspx
119 buf := make([]uint16, 256) //plus extra room for terminating zero byte
121 for i := uint32(0); ; i++ {
127 l := uint32(len(buf))
129 err := syscall.RegEnumKeyEx(syscall.Handle(k), i, &buf[0], &l, nil, nil, nil, nil)
133 if err == syscall.ERROR_MORE_DATA {
134 // Double buffer size and try again.
135 l = uint32(2 * len(buf))
136 buf = make([]uint16, l)
139 if err == _ERROR_NO_MORE_ITEMS {
144 names = append(names, syscall.UTF16ToString(buf[:l]))
152 // CreateKey creates a key named path under open key k.
153 // CreateKey returns the new key and a boolean flag that reports
154 // whether the key already existed.
155 // The access parameter specifies the access rights for the key
157 func CreateKey(k Key, path string, access uint32) (newk Key, openedExisting bool, err error) {
160 err = regCreateKeyEx(syscall.Handle(k), syscall.StringToUTF16Ptr(path),
161 0, nil, _REG_OPTION_NON_VOLATILE, access, nil, &h, &d)
165 return Key(h), d == _REG_OPENED_EXISTING_KEY, nil
168 // DeleteKey deletes the subkey path of key k and its values.
169 func DeleteKey(k Key, path string) error {
170 return regDeleteKey(syscall.Handle(k), syscall.StringToUTF16Ptr(path))
173 // A KeyInfo describes the statistics of a key. It is returned by Stat.
174 type KeyInfo struct {
176 MaxSubKeyLen uint32 // size of the key's subkey with the longest name, in Unicode characters, not including the terminating zero byte
178 MaxValueNameLen uint32 // size of the key's longest value name, in Unicode characters, not including the terminating zero byte
179 MaxValueLen uint32 // longest data component among the key's values, in bytes
180 lastWriteTime syscall.Filetime
183 // ModTime returns the key's last write time.
184 func (ki *KeyInfo) ModTime() time.Time {
185 return time.Unix(0, ki.lastWriteTime.Nanoseconds())
188 // Stat retrieves information about the open key k.
189 func (k Key) Stat() (*KeyInfo, error) {
191 err := syscall.RegQueryInfoKey(syscall.Handle(k), nil, nil, nil,
192 &ki.SubKeyCount, &ki.MaxSubKeyLen, nil, &ki.ValueCount,
193 &ki.MaxValueNameLen, &ki.MaxValueLen, nil, &ki.lastWriteTime)