Skip to content

Commit abea063

Browse files
emakoemako
committed
Add XML docs
1 parent e5afc31 commit abea063

File tree

2 files changed

+140
-0
lines changed

2 files changed

+140
-0
lines changed

‎src/SecondaryClick/WinApi/Advapi32.cs‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,50 @@ namespace SecondaryClick.WinApi;
77
/// </summary>
88
internal static class Advapi32
99
{
10+
/// <summary>
11+
/// Predefined handle to the HKEY_CURRENT_USER root key.
12+
/// </summary>
1013
public static readonly UIntPtr HKEY_CURRENT_USER = (UIntPtr)0x80000001u;
1114

15+
/// <summary>
16+
/// Access right for querying key value data.
17+
/// </summary>
1218
public const int KEY_QUERY_VALUE = 0x0001;
19+
20+
/// <summary>
21+
/// Access right for setting key value data.
22+
/// </summary>
1323
public const int KEY_SET_VALUE = 0x0002;
1424

25+
/// <summary>
26+
/// Registry value type for a null-terminated Unicode string.
27+
/// </summary>
1528
public const uint REG_SZ = 1;
29+
30+
/// <summary>
31+
/// Registry value type for an expandable null-terminated Unicode string.
32+
/// </summary>
1633
public const uint REG_EXPAND_SZ = 2;
34+
35+
/// <summary>
36+
/// Registry value type for a 32-bit number.
37+
/// </summary>
1738
public const uint REG_DWORD = 4;
39+
40+
/// <summary>
41+
/// Registry value type for a 64-bit number.
42+
/// </summary>
1843
public const uint REG_QWORD = 11;
1944

45+
/// <summary>
46+
/// Opens the specified registry key.
47+
/// </summary>
48+
/// <param name="hKey">A handle to an open registry key (for example, HKEY_CURRENT_USER).</param>
49+
/// <param name="lpSubKey">The name of the registry subkey to open.</param>
50+
/// <param name="ulOptions">Reserved; must be zero.</param>
51+
/// <param name="samDesired">The access rights requested for the key.</param>
52+
/// <param name="phkResult">When successful, receives a handle to the opened key.</param>
53+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
2054
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
2155
public static extern int RegOpenKeyEx(
2256
UIntPtr hKey,
@@ -25,6 +59,19 @@ public static extern int RegOpenKeyEx(
2559
int samDesired,
2660
out IntPtr phkResult);
2761

62+
/// <summary>
63+
/// Creates or opens the specified registry key.
64+
/// </summary>
65+
/// <param name="hKey">A handle to an open registry key (for example, HKEY_CURRENT_USER).</param>
66+
/// <param name="lpSubKey">The name of the registry subkey to create or open.</param>
67+
/// <param name="Reserved">Reserved; must be zero.</param>
68+
/// <param name="lpClass">The user-defined class type for this key. Typically null.</param>
69+
/// <param name="dwOptions">Special options for key creation. Typically zero.</param>
70+
/// <param name="samDesired">The access rights requested for the key.</param>
71+
/// <param name="lpSecurityAttributes">Security descriptor pointer. Typically IntPtr.Zero.</param>
72+
/// <param name="phkResult">When successful, receives a handle to the opened or created key.</param>
73+
/// <param name="lpdwDisposition">Receives status indicating whether key was created or opened.</param>
74+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
2875
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
2976
public static extern int RegCreateKeyEx(
3077
UIntPtr hKey,
@@ -37,6 +84,16 @@ public static extern int RegCreateKeyEx(
3784
out IntPtr phkResult,
3885
out uint lpdwDisposition);
3986

87+
/// <summary>
88+
/// Sets the data and type of a named value under an open registry key (string overload).
89+
/// </summary>
90+
/// <param name="hKey">A handle to an open registry key.</param>
91+
/// <param name="lpValueName">The name of the value to set.</param>
92+
/// <param name="Reserved">Reserved; must be zero.</param>
93+
/// <param name="dwType">The registry value type.</param>
94+
/// <param name="lpData">The string data to store.</param>
95+
/// <param name="cbData">The size of data in bytes, including null terminator for strings.</param>
96+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
4097
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
4198
public static extern int RegSetValueEx(
4299
IntPtr hKey,
@@ -46,6 +103,16 @@ public static extern int RegSetValueEx(
46103
string lpData,
47104
int cbData);
48105

106+
/// <summary>
107+
/// Sets the data and type of a named value under an open registry key (byte array overload).
108+
/// </summary>
109+
/// <param name="hKey">A handle to an open registry key.</param>
110+
/// <param name="lpValueName">The name of the value to set.</param>
111+
/// <param name="Reserved">Reserved; must be zero.</param>
112+
/// <param name="dwType">The registry value type.</param>
113+
/// <param name="lpData">The raw byte data to store.</param>
114+
/// <param name="cbData">The size of data in bytes.</param>
115+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
49116
[DllImport("advapi32.dll", SetLastError = true)]
50117
public static extern int RegSetValueEx(
51118
IntPtr hKey,
@@ -55,6 +122,16 @@ public static extern int RegSetValueEx(
55122
byte[] lpData,
56123
int cbData);
57124

125+
/// <summary>
126+
/// Retrieves the type and data for a specified registry value.
127+
/// </summary>
128+
/// <param name="hKey">A handle to an open registry key.</param>
129+
/// <param name="lpValueName">The name of the value to query.</param>
130+
/// <param name="lpReserved">Reserved; must be zero.</param>
131+
/// <param name="lpType">When successful, receives the registry value type.</param>
132+
/// <param name="lpData">A buffer that receives value data, or null to query required size.</param>
133+
/// <param name="lpcbData">On input, buffer size; on output, required or actual size in bytes.</param>
134+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
58135
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
59136
public static extern int RegQueryValueEx(
60137
IntPtr hKey,
@@ -64,11 +141,22 @@ public static extern int RegQueryValueEx(
64141
byte[]? lpData,
65142
ref uint lpcbData);
66143

144+
/// <summary>
145+
/// Removes a named value from the specified registry key.
146+
/// </summary>
147+
/// <param name="hKey">A handle to an open registry key.</param>
148+
/// <param name="lpValueName">The name of the value to delete.</param>
149+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
67150
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
68151
public static extern int RegDeleteValue(
69152
IntPtr hKey,
70153
string lpValueName);
71154

155+
/// <summary>
156+
/// Closes a handle to the specified registry key.
157+
/// </summary>
158+
/// <param name="hKey">A handle to an open registry key.</param>
159+
/// <returns>Win32 error code. ERROR_SUCCESS indicates success.</returns>
72160
[DllImport("advapi32.dll", SetLastError = true)]
73161
public static extern int RegCloseKey(IntPtr hKey);
74162
}

‎src/SecondaryClick/WinApi/RegistryApi.cs‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,22 @@ namespace SecondaryClick.WinApi;
77
/// </summary>
88
internal static class RegistryApi
99
{
10+
/// <summary>
11+
/// Determines whether a registry value type is DWORD.
12+
/// </summary>
13+
/// <param name="valueType">The registry value type code.</param>
14+
/// <returns>True if the value type is REG_DWORD; otherwise false.</returns>
1015
public static bool IsDwordType(uint valueType)
1116
=> valueType == Advapi32.REG_DWORD;
1217

18+
/// <summary>
19+
/// Reads raw registry value data from HKEY_CURRENT_USER.
20+
/// </summary>
21+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
22+
/// <param name="valueName">The value name to read.</param>
23+
/// <param name="valueType">When successful, receives the registry value type.</param>
24+
/// <param name="data">When successful, receives the raw value bytes.</param>
25+
/// <returns>True if the value is read successfully; otherwise false.</returns>
1326
public static bool TryReadRawCurrentUser(string subKeyPath, string valueName, out uint valueType, out byte[] data)
1427
{
1528
valueType = 0;
@@ -62,6 +75,13 @@ public static bool TryReadRawCurrentUser(string subKeyPath, string valueName, ou
6275
}
6376
}
6477

78+
/// <summary>
79+
/// Reads a DWORD registry value from HKEY_CURRENT_USER.
80+
/// </summary>
81+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
82+
/// <param name="valueName">The value name to read.</param>
83+
/// <param name="value">When successful, receives the DWORD value.</param>
84+
/// <returns>True if a valid DWORD value is read; otherwise false.</returns>
6585
public static bool TryReadDwordCurrentUser(string subKeyPath, string valueName, out int value)
6686
{
6787
value = 0;
@@ -75,6 +95,13 @@ public static bool TryReadDwordCurrentUser(string subKeyPath, string valueName,
7595
return true;
7696
}
7797

98+
/// <summary>
99+
/// Reads a string registry value (REG_SZ or REG_EXPAND_SZ) from HKEY_CURRENT_USER.
100+
/// </summary>
101+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
102+
/// <param name="valueName">The value name to read.</param>
103+
/// <param name="value">When successful, receives the decoded string value.</param>
104+
/// <returns>True if a supported string value is read; otherwise false.</returns>
78105
public static bool TryReadStringCurrentUser(string subKeyPath, string valueName, out string value)
79106
{
80107
value = string.Empty;
@@ -88,6 +115,13 @@ public static bool TryReadStringCurrentUser(string subKeyPath, string valueName,
88115
return true;
89116
}
90117

118+
/// <summary>
119+
/// Writes a DWORD registry value to HKEY_CURRENT_USER.
120+
/// </summary>
121+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
122+
/// <param name="valueName">The value name to write.</param>
123+
/// <param name="value">The DWORD value to write.</param>
124+
/// <returns>True if the value is written successfully; otherwise false.</returns>
91125
public static bool SetDwordCurrentUser(string subKeyPath, string valueName, int value)
92126
{
93127
int createResult = Advapi32.RegCreateKeyEx(
@@ -123,6 +157,13 @@ public static bool SetDwordCurrentUser(string subKeyPath, string valueName, int
123157
}
124158
}
125159

160+
/// <summary>
161+
/// Writes a string registry value (REG_SZ) to HKEY_CURRENT_USER.
162+
/// </summary>
163+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
164+
/// <param name="valueName">The value name to write.</param>
165+
/// <param name="value">The string value to write.</param>
166+
/// <returns>True if the value is written successfully; otherwise false.</returns>
126167
public static bool SetStringCurrentUser(string subKeyPath, string valueName, string value)
127168
{
128169
int createResult = Advapi32.RegCreateKeyEx(
@@ -158,6 +199,12 @@ public static bool SetStringCurrentUser(string subKeyPath, string valueName, str
158199
}
159200
}
160201

202+
/// <summary>
203+
/// Deletes a registry value from HKEY_CURRENT_USER.
204+
/// </summary>
205+
/// <param name="subKeyPath">The subkey path under HKEY_CURRENT_USER.</param>
206+
/// <param name="valueName">The value name to delete.</param>
207+
/// <returns>True if deletion succeeds or the value does not exist; otherwise false.</returns>
161208
public static bool DeleteValueCurrentUser(string subKeyPath, string valueName)
162209
{
163210
int openResult = Advapi32.RegOpenKeyEx(
@@ -185,6 +232,11 @@ public static bool DeleteValueCurrentUser(string subKeyPath, string valueName)
185232
}
186233
}
187234

235+
/// <summary>
236+
/// Decodes UTF-16 (Unicode) registry bytes to a managed string and trims trailing null terminators.
237+
/// </summary>
238+
/// <param name="data">The UTF-16 encoded byte array.</param>
239+
/// <returns>The decoded string value.</returns>
188240
public static string DecodeUnicodeString(byte[] data)
189241
=> Encoding.Unicode.GetString(data).TrimEnd('\0');
190242
}

0 commit comments

Comments
 (0)