class Win32::Registry - Documentation for Ruby 4.0
Description: class Win32::Registry: registry is registry accessor library for Win32 platform. It uses importer to call Win32 Registry APIs.
Keywords: ruby,class,Win32::Registry

🔍

No recent searches

# class Win32::Registry

win32/registry is registry accessor library for `Win32` platform. It uses importer to call `Win32` `Registry` APIs.

## example

    Win32::Registry::HKEY_CURRENT_USER.open('SOFTWARE\foo') do |reg|
      value = reg['foo']                               # read a value
      value = reg['foo', Win32::Registry::REG_SZ]      # read a value with type
      type, value = reg.read('foo')                    # read a value
      reg['foo'] = 'bar'                               # write a value
      reg['foo', Win32::Registry::REG_SZ] = 'bar'      # write a value with type
      reg.write('foo', Win32::Registry::REG_SZ, 'bar') # write a value

      reg.each_value { |name, type, data| ... }        # Enumerate values
      reg.each_key { |key, wtime| ... }                # Enumerate subkeys

      reg.delete_value(name)                           # Delete a value
      reg.delete_key(name)                             # Delete a subkey
      reg.delete_key(name, true)                       # Delete a subkey recursively
    end

## Predefined keys

- `HKEY_CLASSES_ROOT`

- `HKEY_CURRENT_USER`

- `HKEY_LOCAL_MACHINE`

- `HKEY_PERFORMANCE_DATA`

- `HKEY_CURRENT_CONFIG`

- `HKEY_DYN_DATA`

  `Win32::Registry` object whose key is predefined key.

For detail, see the article.

## Value types

- `REG_NONE`

- `REG_SZ`

- `REG_EXPAND_SZ`

- `REG_BINARY`

- `REG_DWORD`

- `REG_DWORD_BIG_ENDIAN`

- `REG_LINK`

- `REG_MULTI_SZ`

- `REG_RESOURCE_LIST`

- `REG_FULL_RESOURCE_DESCRIPTOR`

- `REG_RESOURCE_REQUIREMENTS_LIST`

- `REG_QWORD`

For detail, see the article.

### Public Class Methods

create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 468
    def self.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
      newkey, disp = API.CreateKey(hkey.instance_variable_get(:@hkey), subkey, opt, desired)
      obj = new(newkey, hkey, subkey, disp)
      if block_given?
        begin
          yield obj
        ensure
          obj.close
        end
      else
        obj
      end
    end

Create or open the registry key `subkey` under `key`. You can use predefined key `HKEY_`*. `desired` and `opt` is access mask and key option.

If `subkey` is already exists, key is opened and Registry#created? method will return false.

If block is given, the key `reg` is yielded and closed automatically after the block exists.

expand_environ (str)
Source

    # File ext/win32/lib/win32/registry.rb, line 381
    def self.expand_environ(str)
      str.gsub(Regexp.compile("%([^%]+)%".encode(str.encoding))) {
        v = $1.encode(LOCALE)
        (ENV[v] || ENV[v.upcase])&.encode(str.encoding) || $&
      }
    end

Replace `%`-enclosed substrings in `str` into the environment value of what is contained between the `%`s. This method is used for REG_EXPAND_SZ.

For detail, see ExpandEnvironmentStrings Win32 API.

open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 438
    def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
      subkey = subkey.chomp('\\')
      newkey = API.OpenKey(hkey.instance_variable_get(:@hkey), subkey, opt, desired)
      obj = new(newkey, hkey, subkey, REG_OPENED_EXISTING_KEY)
      if block_given?
        begin
          yield obj
        ensure
          obj.close
        end
      else
        obj
      end
    end

Open the registry key `subkey` under `key`. `key` is `Win32::Registry` object of parent key. You can use predefined key `HKEY_`*. `desired` and `opt` is access mask and key option.

For detail, see the MSDN.

If block is given, the key `reg` is yielded and closed automatically after the block exists.

time2wtime (time)
Source

    # File ext/win32/lib/win32/registry.rb, line 415
    def self.time2wtime(time)
      time.to_i * 10000000 + 116444736000000000
    end

Convert `Time` object or `Integer` object `time` into 64-bit FILETIME.

type2name (type)
Source

    # File ext/win32/lib/win32/registry.rb, line 401
    def self.type2name(type)
      @@type2name[type] || type.to_s
    end

Convert registry type value `type` to readable string.

wtime2time (wtime)
Source

    # File ext/win32/lib/win32/registry.rb, line 408
    def self.wtime2time(wtime)
      Time.at((wtime - 116444736000000000) / 10000000)
    end

Convert 64-bit FILETIME integer `wtime` into `Time` object.