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.
4
5// +build windows
6
7// Package registry provides access to the Windows registry.
8//
9// Here is a simple example, opening a registry key and reading a string value from it.
10//
11//	k, err := registry.OpenKey(registry.LOCAL_MACHINE, `SOFTWARE\Microsoft\Windows NT\CurrentVersion`, registry.QUERY_VALUE)
12//	if err != nil {
13//		log.Fatal(err)
14//	}
15//	defer k.Close()
16//
17//	s, _, err := k.GetStringValue("SystemRoot")
18//	if err != nil {
19//		log.Fatal(err)
20//	}
21//	fmt.Printf("Windows system root is %q\n", s)
22//
23package registry
24
25import (
26	"io"
27	"syscall"
28	"time"
29)
30
31const (
32	// Registry key security and access rights.
33	// See https://msdn.microsoft.com/en-us/library/windows/desktop/ms724878.aspx
34	// for details.
35	ALL_ACCESS         = 0xf003f
36	CREATE_LINK        = 0x00020
37	CREATE_SUB_KEY     = 0x00004
38	ENUMERATE_SUB_KEYS = 0x00008
39	EXECUTE            = 0x20019
40	NOTIFY             = 0x00010
41	QUERY_VALUE        = 0x00001
42	READ               = 0x20019
43	SET_VALUE          = 0x00002
44	WOW64_32KEY        = 0x00200
45	WOW64_64KEY        = 0x00100
46	WRITE              = 0x20006
47)
48
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.
53type Key syscall.Handle
54
55const (
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)
66)
67
68// Close closes open key k.
69func (k Key) Close() error {
70	return syscall.RegCloseKey(syscall.Handle(k))
71}
72
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
77// key to be opened.
78func OpenKey(k Key, path string, access uint32) (Key, error) {
79	p, err := syscall.UTF16PtrFromString(path)
80	if err != nil {
81		return 0, err
82	}
83	var subkey syscall.Handle
84	err = syscall.RegOpenKeyEx(syscall.Handle(k), p, 0, access, &subkey)
85	if err != nil {
86		return 0, err
87	}
88	return Key(subkey), nil
89}
90
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.
95func OpenRemoteKey(pcname string, k Key) (Key, error) {
96	var err error
97	var p *uint16
98	if pcname != "" {
99		p, err = syscall.UTF16PtrFromString(`\\` + pcname)
100		if err != nil {
101			return 0, err
102		}
103	}
104	var remoteKey syscall.Handle
105	err = regConnectRegistry(p, syscall.Handle(k), &remoteKey)
106	if err != nil {
107		return 0, err
108	}
109	return Key(remoteKey), nil
110}
111
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.
115func (k Key) ReadSubKeyNames(n int) ([]string, error) {
116	ki, err := k.Stat()
117	if err != nil {
118		return nil, err
119	}
120	names := make([]string, 0, ki.SubKeyCount)
121	buf := make([]uint16, ki.MaxSubKeyLen+1) // extra room for terminating zero byte
122loopItems:
123	for i := uint32(0); ; i++ {
124		if n > 0 {
125			if len(names) == n {
126				return names, nil
127			}
128		}
129		l := uint32(len(buf))
130		for {
131			err := syscall.RegEnumKeyEx(syscall.Handle(k), i, &buf[0], &l, nil, nil, nil, nil)
132			if err == nil {
133				break
134			}
135			if err == syscall.ERROR_MORE_DATA {
136				// Double buffer size and try again.
137				l = uint32(2 * len(buf))
138				buf = make([]uint16, l)
139				continue
140			}
141			if err == _ERROR_NO_MORE_ITEMS {
142				break loopItems
143			}
144			return names, err
145		}
146		names = append(names, syscall.UTF16ToString(buf[:l]))
147	}
148	if n > len(names) {
149		return names, io.EOF
150	}
151	return names, nil
152}
153
154// CreateKey creates a key named path under open key k.
155// CreateKey returns the new key and a boolean flag that reports
156// whether the key already existed.
157// The access parameter specifies the access rights for the key
158// to be created.
159func CreateKey(k Key, path string, access uint32) (newk Key, openedExisting bool, err error) {
160	var h syscall.Handle
161	var d uint32
162	err = regCreateKeyEx(syscall.Handle(k), syscall.StringToUTF16Ptr(path),
163		0, nil, _REG_OPTION_NON_VOLATILE, access, nil, &h, &d)
164	if err != nil {
165		return 0, false, err
166	}
167	return Key(h), d == _REG_OPENED_EXISTING_KEY, nil
168}
169
170// DeleteKey deletes the subkey path of key k and its values.
171func DeleteKey(k Key, path string) error {
172	return regDeleteKey(syscall.Handle(k), syscall.StringToUTF16Ptr(path))
173}
174
175// A KeyInfo describes the statistics of a key. It is returned by Stat.
176type KeyInfo struct {
177	SubKeyCount     uint32
178	MaxSubKeyLen    uint32 // size of the key's subkey with the longest name, in Unicode characters, not including the terminating zero byte
179	ValueCount      uint32
180	MaxValueNameLen uint32 // size of the key's longest value name, in Unicode characters, not including the terminating zero byte
181	MaxValueLen     uint32 // longest data component among the key's values, in bytes
182	lastWriteTime   syscall.Filetime
183}
184
185// ModTime returns the key's last write time.
186func (ki *KeyInfo) ModTime() time.Time {
187	return time.Unix(0, ki.lastWriteTime.Nanoseconds())
188}
189
190// Stat retrieves information about the open key k.
191func (k Key) Stat() (*KeyInfo, error) {
192	var ki KeyInfo
193	err := syscall.RegQueryInfoKey(syscall.Handle(k), nil, nil, nil,
194		&ki.SubKeyCount, &ki.MaxSubKeyLen, nil, &ki.ValueCount,
195		&ki.MaxValueNameLen, &ki.MaxValueLen, nil, &ki.lastWriteTime)
196	if err != nil {
197		return nil, err
198	}
199	return &ki, nil
200}
201