class Poco::Util::WinRegistryKey

Overview

This class implements a convenient interface to the Windows Registry. More…

#include <WinRegistryKey.h>

class WinRegistryKey
{
public:
    // typedefs

    typedef std::vector<std::string> Keys;
    typedef std::vector<std::string> Values;

    // enums

    enum Type;

    // construction

    WinRegistryKey(
        const std::string& key,
        bool readOnly = false,
        REGSAM extraSam = 0
        );

    WinRegistryKey(
        HKEY hRootKey,
        const std::string& subKey,
        bool readOnly = false,
        REGSAM extraSam = 0
        );

    // methods

    void
    setString(
        const std::string& name,
        const std::string& value
        );

    std::string
    getString(const std::string& name);

    void
    setStringExpand(
        const std::string& name,
        const std::string& value
        );

    std::string
    getStringExpand(const std::string& name);

    void
    setBinary(
        const std::string& name,
        const std::vector<char>& value
        );

    std::vector<char>
    getBinary(const std::string& name);

    void
    setInt(
        const std::string& name,
        int value
        );

    int
    getInt(const std::string& name);

    void
    deleteValue(const std::string& name);

    void
    deleteKey();

    bool
    exists();

    Type
    type(const std::string& name);

    bool
    exists(const std::string& name);

    void
    subKeys(Keys& keys);

    void
    values(Values& vals);

    bool
    isReadOnly() const;

protected:
    // methods

    void
    open();

    void
    close();

    std::string
    key() const;

    std::string
    key(const std::string& valueName) const;

    HKEY
    handle();

    void
    handleSetError(const std::string& name);

    static
    HKEY
    handleFor(const std::string& rootKey);
};

Detailed Documentation

This class implements a convenient interface to the Windows Registry.

This class is only available on Windows platforms.

Construction

WinRegistryKey(
    const std::string& key,
    bool readOnly = false,
    REGSAM extraSam = 0
    )

Creates the WinRegistryKey.

The key must start with one of the root key names like HKEY_CLASSES_ROOT, e.g. HKEY_LOCAL_MACHINE.

If readOnly is true, then only read access to the registry is available and any attempt to write to the registry will result in an exception.

extraSam is used to pass extra flags (in addition to KEY_READ and KEY_WRITE) to the samDesired argument of RegOpenKeyEx() or RegCreateKeyEx().

WinRegistryKey(
    HKEY hRootKey,
    const std::string& subKey,
    bool readOnly = false,
    REGSAM extraSam = 0
    )

Creates the WinRegistryKey.

If readOnly is true, then only read access to the registry is available and any attempt to write to the registry will result in an exception.

extraSam is used to pass extra flags (in addition to KEY_READ and KEY_WRITE) to the samDesired argument of RegOpenKeyEx() or RegCreateKeyEx().

Methods

void
setString(
    const std::string& name,
    const std::string& value
    )

Sets the string value (REG_SZ) with the given name.

An empty name denotes the default value.

std::string
getString(const std::string& name)

Returns the string value (REG_SZ) with the given name.

An empty name denotes the default value.

Throws a NotFoundException if the value does not exist.

void
setStringExpand(
    const std::string& name,
    const std::string& value
    )

Sets the expandable string value (REG_EXPAND_SZ) with the given name.

An empty name denotes the default value.

std::string
getStringExpand(const std::string& name)

Returns the string value (REG_EXPAND_SZ) with the given name.

An empty name denotes the default value. All references to environment variables (VAR%) in the string are expanded.

Throws a NotFoundException if the value does not exist.

void
setBinary(
    const std::string& name,
    const std::vector<char>& value
    )

Sets the string value (REG_BINARY) with the given name.

An empty name denotes the default value.

std::vector<char>
getBinary(const std::string& name)

Returns the string value (REG_BINARY) with the given name.

An empty name denotes the default value.

Throws a NotFoundException if the value does not exist.

void
setInt(
    const std::string& name,
    int value
    )

Sets the numeric (REG_DWORD) value with the given name.

An empty name denotes the default value.

int
getInt(const std::string& name)

Returns the numeric value (REG_DWORD) with the given name.

An empty name denotes the default value.

Throws a NotFoundException if the value does not exist.

void
deleteValue(const std::string& name)

Deletes the value with the given name.

Throws a NotFoundException if the value does not exist.

void
deleteKey()

Recursively deletes the key and all subkeys.

bool
exists()

Returns true iff the key exists.

Type
type(const std::string& name)

Returns the type of the key value.

bool
exists(const std::string& name)

Returns true iff the given value exists under that key.

void
subKeys(Keys& keys)

Appends all subKey names to keys.

void
values(Values& vals)

Appends all value names to vals;.

bool
isReadOnly() const

Returns true iff the key has been opened for read-only access only.