DOCSEARCHbyAlgolia
Submit Docs

WinReg C++ Library

repository·master·Indexed 19 days ago

https://github.com/giovannidicanio/winreg

A high-level C++17 header-only wrapper for the Windows Registry C-interface API. WinReg simplifies registry manipulation by mapping Win32 types to STL containers and providing error handling via exceptions, result objects, or expected values. It features the RegKey class for opening keys, retrieving values, and enumerating registry entries.

Tokens
1K
Snippets
4
Records
6
Agent score
18%

What's inside WinReg

  1. Use RegKey for Registry Operations

    master

    The RegKey class is the primary interface for interacting with the Windows Registry. It wraps raw HKEY handles and provides methods for opening keys and retrieving values.

    Error Handling Patterns

    WinReg provides three ways to handle errors:

    1. Exceptions: Standard methods (e.g., Open, GetDwordValue) throw a RegException on failure.
    2. Return Codes: Try methods (e.g., TryOpen) return a RegResult object which can be checked for success.
    3. Expected Values: TryGet...Value methods return a RegExpected<T> object, which contains either the value or a RegResult on error.
    // 1. Exception-based usage
RegKey key{ HKEY_CURRENT_USER, L"SOFTWARE\SomeKey" };
DWORD dw = key.GetDwordValue(L"SomeDwordValue");

// 2. Return-code based usage (TryOpen)
RegKey key;
RegResult result = key.TryOpen(HKEY_CURRENT_USER, L"SOFTWARE\SomeKey");
if (!result) {
    // Handle error using result.Code or result.ErrorMessage
}

// 3. RegExpected based usage (TryGetDwordValue)
const auto res = key.TryGetDwordValue(L"SomeDwordValue");
if (res.IsValid()) {
    DWORD val = res.GetValue();
} else {
    // Handle error using res.GetError()
}

  2. Install and Setup WinReg

    master

    WinReg is a header-only C++ library. To use it, simply include the WinReg.hpp header in your project.

    Requirements

    • Compiler: Visual Studio 2022 is recommended.
    • C++ Standard: Requires C++17 (/std:c++17) or C++20 (/std:c++20).
    • Architecture: Supports both 32-bit and 64-bit builds.
    • Namespace: All library components reside under the winreg namespace.
    #include <WinReg/WinReg.hpp>
// Use the winreg namespace
using namespace winreg;

  3. Enumerate Registry Values

    master

    You can iterate over all values contained within a RegKey using the EnumValues() method. This returns a collection of pairs where the first element is the value name (std::wstring) and the second is the value type (DWORD).

    Using C++17 structured bindings makes this iteration concise.

    auto values = key.EnumValues();

for (const auto & [valueName, valueType] : values)
{
    // valueName is std::wstring
    // valueType is DWORD
}

  5. Check for Existence of Values or Subkeys

    master

    Use RegKey::ContainsValue and RegKey::ContainsSubKey to verify if a specific name exists under the current key without attempting to read or open it.

    if (key.ContainsValue(L"Connie"))
{
    // The key contains the value named "Connie"
}

  6. Map Win32 Registry Types to C++ Types

    master

    WinReg translates low-level Win32 registry types into high-level STL-based C++ types. Use the following mapping to determine which C++ type to use when reading values:

    Win32 Registry TypeC++ Type
    REG_DWORDDWORD
    REG_QWORDULONGLONG
    REG_SZstd::wstring
    REG_EXPAND_SZstd::wstring
    REG_MULTI_SZstd::vector<std::wstring>
    REG_BINARYstd::vector<BYTE>