xentara::utils::windows::RegistryKey Class Reference

A Windows registry key handle that closes itself on destruct. More...

#include <windows/RegistryKey.hpp>

Inheritance diagram for xentara::utils::windows::RegistryKey:

Classes
class	Setter
class	SubKeyEnumerator
class	ValueEnumerator

Public Types
using	HKEY = HKEY__ *
	A native Windows registry key handle.
using	REGSAM = unsigned long
	Access flags for registry keys.
using	DWORD = unsigned long
	Used for registry value types.

Public Member Functions
constexpr	RegistryKey () noexcept=default
	Default constructor.
constexpr	RegistryKey (HKEY nativeHandle) noexcept
	Conversion from a native registry key handle.
constexpr	RegistryKey (RegistryKey &&other) noexcept
	Move constructor.
	~RegistryKey ()
	Destructor. Silently closes the registry key.
auto	operator= (RegistryKey &&rhs) noexcept -> RegistryKey &
	Move assignment operator.
constexpr	operator HKEY () const noexcept
	Conversion to a native registry key handle.
constexpr	operator bool () const noexcept
	Checks whether the object contains a valid registry key.
auto	operator= (HKEY nativeHandle) noexcept -> RegistryKey &
	Assignment from a native registry key handle.
template<RegistryValue Value>
auto	value (DWORD flags=0) const -> eh::expected< Value, std::error_code >
	Reads the default value.
template<RegistryValue Value>
auto	value (const wchar_t *name, DWORD flags=0) const -> eh::expected< Value, std::error_code >
	Reads a named value.
template<RegistryValue Value>
auto	value (const wchar_t *subKey, const wchar_t *name, DWORD flags=0) const -> eh::expected< Value, std::error_code >
	Reads a named value from a sub key.
auto	subKey (const wchar_t *subKeyPath, REGSAM desiredAccess) const -> eh::expected< RegistryKey, std::error_code >
	Gets a named sub key.
auto	valueNames () const -> ValueEnumerator
	Returns an enumerator that can be used to iterate over the names of all named values.
auto	subKeyNames () const -> SubKeyEnumerator
	Returns an enumerator that can be used to iterate over the names of all sub keys.
constexpr auto	release () noexcept -> HKEY
	Removes the registry key and passes ownership to the caller.
auto	close () noexcept -> std::error_code
	Closes the registry key, if it is open.
auto	setter () noexcept -> Setter
	Gets a setter for use as an output parameter for C functions.

Static Public Member Functions
static auto	open (HKEY parent, const wchar_t *subKeyPath, REGSAM desiredAccess) -> eh::expected< RegistryKey, std::error_code >
	Opens a registry key.

Detailed Description

A Windows registry key handle that closes itself on destruct.

This class can be moved but not copied.

Note

This class is only available under Windows

Member Typedef Documentation

DWORD

using xentara::utils::windows::RegistryKey::DWORD = unsigned long

Used for registry value types.

HKEY

using xentara::utils::windows::RegistryKey::HKEY = HKEY__*

A native Windows registry key handle.

REGSAM

using xentara::utils::windows::RegistryKey::REGSAM = unsigned long

Access flags for registry keys.

Constructor & Destructor Documentation

RegistryKey() [1/3]

constexpr xentara::utils::windows::RegistryKey::RegistryKey ( )

constexprdefaultnoexcept

Default constructor.

RegistryKey() [2/3]

constexpr xentara::utils::windows::RegistryKey::RegistryKey ( HKEY  nativeHandle )

constexprnoexcept

Conversion from a native registry key handle.

Parameters

nativeHandle

The native handle

RegistryKey() [3/3]

constexpr xentara::utils::windows::RegistryKey::RegistryKey ( RegistryKey &&  other )

constexprnoexcept

Move constructor.

Takes ownership of the other handle's value.

Parameters

other

The handle to move. Will be turned into a null handle.

~RegistryKey()

xentara::utils::windows::RegistryKey::~RegistryKey

(

)

Destructor. Silently closes the registry key.

Member Function Documentation

close()

auto xentara::utils::windows::RegistryKey::close ( ) -> std::error_code

noexcept

Closes the registry key, if it is open.

Returns

Returns std::error_code() on success, or an appropriate error code on failure. The registry key handle will be closed in either case, though.

open()

static auto xentara::utils::windows::RegistryKey::open ( HKEY  parent, const wchar_t *  subKeyPath, REGSAM  desiredAccess  ) -> eh::expected< RegistryKey, std::error_code >

static

Opens a registry key.

Parameters

parent	The parent key
subKeyPath	The sub key path
desiredAccess	The desired access

Returns

The key, or an error code on failure

operator bool()

constexpr xentara::utils::windows::RegistryKey::operator bool ( ) const

explicitconstexprnoexcept

Checks whether the object contains a valid registry key.

operator HKEY()

constexpr xentara::utils::windows::RegistryKey::operator HKEY ( ) const

constexprnoexcept

Conversion to a native registry key handle.

operator=() [1/2]

auto xentara::utils::windows::RegistryKey::operator= ( HKEY  nativeHandle ) -> RegistryKey &

noexcept

Assignment from a native registry key handle.

Any existing handle is silently closed.

Parameters

nativeHandle

The native registry key handle

operator=() [2/2]

auto xentara::utils::windows::RegistryKey::operator= ( RegistryKey &&  rhs ) -> RegistryKey &

noexcept

Move assignment operator.

Takes ownership of the other handle's value. Any existing handle is silently closed.

Parameters

rhs	The handle to move. Will be turned into a null handle.

release()

constexpr auto xentara::utils::windows::RegistryKey::release ( ) -> HKEY

constexprnoexcept

Removes the registry key and passes ownership to the caller.

After this call, this object will no longer contain a registry key.

Returns

The native handle, or nullptr for none. The caller must assume ownership of the registry key and close it when it is no longer needed.

setter()

auto xentara::utils::windows::RegistryKey::setter ( ) -> Setter

noexcept

Gets a setter for use as an output parameter for C functions.

This function returns a helper object that can be passed to a function that takes a PHKEY as output parameter, like e.g. RegCreateKeyEx(). This provides a safe way of creating registry keys using such a function without running the risk of leaking the created key.

RegCreateKeyEx() can be called like this, for example:

xentara::utils::windows::RegistryKey key;
RegCreateKeyExW(HKEY_CURRENT_USER, myKeyName.c_str(), 0, nullptr, 0, KEY_ALL_ACCESS, nullptr, key.setter(), nullptr);

subKey()

auto xentara::utils::windows::RegistryKey::subKey	(	const wchar_t *	subKeyPath,
		REGSAM	desiredAccess
	)		const -> eh::expected<RegistryKey, std::error_code>

Gets a named sub key.

Parameters

subKeyPath	The sub key path
desiredAccess	The desired access

Returns

The key, or an error code on failure

subKeyNames()

auto xentara::utils::windows::RegistryKey::subKeyNames

(

)

const -> SubKeyEnumerator

Returns an enumerator that can be used to iterate over the names of all sub keys.

value() [1/3]

template<RegistryValue Value>

auto xentara::utils::windows::RegistryKey::value	(	const wchar_t *	name,
		DWORD	flags = 0
	)		const -> eh::expected<Value, std::error_code>

Reads a named value.

Parameters

name	The name of the value. If you pass nullprt or an empty string, the default value will be read.
flags	The flags for reading the value. If you do not specify any type restriction flags, suitable flags are added automatically.

Returns

the value and its type

value() [2/3]

template<RegistryValue Value>

auto xentara::utils::windows::RegistryKey::value	(	const wchar_t *	subKey,
		const wchar_t *	name,
		DWORD	flags = 0
	)		const -> eh::expected< Value, std::error_code >

Reads a named value from a sub key.

Parameters

subKey	The name of the sub key. If you pass nullprt or an empty string, the value will be read from the key directly.
name	The name of the value. If you pass nullprt or an empty string, the default value will be read.
flags	The flags for reading the value. If you do not specify any type restriction flags, suitable flags are added automatically.

Returns

the value and its type

value() [3/3]

template<RegistryValue Value>

auto xentara::utils::windows::RegistryKey::value

(

DWORD

flags = 0

)

const -> eh::expected<Value, std::error_code>

Reads the default value.

Parameters

flags

The flags for reading the value. If you do not specify any type restriction flags, suitable flags are added automatically.

Returns

the value and its type

valueNames()

auto xentara::utils::windows::RegistryKey::valueNames

(

)

const -> ValueEnumerator

Returns an enumerator that can be used to iterate over the names of all named values.