# class Win32::Registry

### Attributes

disposition [R]

Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).

keyname [R]

Same as subkey value of `Registry.open` or `Registry.create` method.

parent [R]

`Win32::Registry` object of parent key, or nil if predefeined key.

### Public Class Methods

create (hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |obj| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 459
    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

— `Registry.create`(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

— `Registry.create`(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| … }

Create or open the registry key subkey under key. You can use predefined key HKEY_* (see `Constants`)

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

If block is given, the key is closed automatically.

expand_environ (str)
Source

    # File ext/win32/lib/win32/registry.rb, line 377
    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 %w+% 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.

new (hkey, parent, keyname, disposition)
Source

    # File ext/win32/lib/win32/registry.rb, line 481
    def initialize(hkey, parent, keyname, disposition)
      @hkey = Fiddle::Pointer.new(hkey)
      @parent = parent
      @keyname = keyname
      @disposition = disposition
      @hkeyfinal = [ hkey ]
      ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal)
    end

initialize

open (hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |obj| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 431
    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

— `Registry.open`(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

— `Registry.open`(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| … }

Open the registry key subkey under key. key is `Win32::Registry` object of parent key. You can use predefined key HKEY_* (see `Constants`) desired and opt is access mask and key option. For detail, see the MSDN. If block is given, the key is closed automatically.

time2wtime (time)
Source

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

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

type2name (type)
Source

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

Convert registry type value to readable string.

wtime2time (wtime)
Source

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

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

### Public Instance Methods

[] (name, *rtype)
Source

    # File ext/win32/lib/win32/registry.rb, line 694
    def [](name, *rtype)
      type, data = read(name, *rtype)
      case type
      when REG_SZ, REG_DWORD, REG_QWORD, REG_MULTI_SZ
        data
      when REG_EXPAND_SZ
        Registry.expand_environ(data)
      else
        raise TypeError, "Type #{Registry.type2name(type)} is not supported."
      end
    end

Read a registry value named name and return its value data. The class of the value is the same as the `read` method returns.

If the value type is REG_EXPAND_SZ, returns value data whose environment variables are replaced. If the value type is neither REG_SZ, REG_MULTI_SZ, REG_DWORD, REG_DWORD_BIG_ENDIAN, nor REG_QWORD, `TypeError` is raised.

The meaning of rtype is the same as for the `read` method.

[]= (name, rtype, value = nil)
Source

    # File ext/win32/lib/win32/registry.rb, line 789
    def []=(name, rtype, value = nil)
      if value
        write name, rtype, value
      else
        case value = rtype
        when Integer
          write name, REG_DWORD, value
        when String
          write name, REG_SZ, value
        when Array
          write name, REG_MULTI_SZ, value
        else
          raise TypeError, "Unexpected type #{value.class}"
        end
      end
      value
    end

Write value to a registry value named name.

If wtype is specified, the value type is it. Otherwise, the value type is depend on class of value: :Integer

    REG_DWORD

:String

    REG_SZ

:Array

    REG_MULTI_SZ

_dump (depth)
Source

    # File ext/win32/lib/win32/registry.rb, line 539
    def _dump(depth)
      raise TypeError, "can't dump Win32::Registry"
    end

marshalling is not allowed

close ()
Source

    # File ext/win32/lib/win32/registry.rb, line 562
    def close
      API.CloseKey(@hkey)
      @hkey = @parent = @keyname = nil
      @hkeyfinal[0] = nil
    end

Close key.

After close, most method raise an error.

create (subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)
Source

    # File ext/win32/lib/win32/registry.rb, line 553
    def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)
      self.class.create(self, subkey, desired, opt, &blk)
    end

Same as `Win32::Registry.create` (self, subkey, desired, opt)

created? ()
Source

    # File ext/win32/lib/win32/registry.rb, line 509
    def created?
      @disposition == REG_CREATED_NEW_KEY
    end

Returns if key is created ((newly)). (see `Registry.create`) – basically you call create then when you call created? on the instance returned it will tell if it was successful or not

delete (name)
Alias for: delete_value
delete_key (name, recursive = false)
Source

    # File ext/win32/lib/win32/registry.rb, line 852
    def delete_key(name, recursive = false)
      if recursive
        open(name, KEY_ALL_ACCESS) do |reg|
          reg.keys.each do |key|
            begin
              reg.delete_key(key, true)
            rescue Error
              #
            end
          end
        end
        API.DeleteKey(@hkey, name)
      else
        begin
          API.EnumKey @hkey, 0
        rescue Error
          return API.DeleteKey(@hkey, name)
        end
        raise Error.new(5) ## ERROR_ACCESS_DENIED
      end
    end

Delete a subkey named name and all its values.

If recursive is false, the subkey must not have subkeys. Otherwise, this method deletes all subkeys and values recursively.

delete_value (name)
Source

    # File ext/win32/lib/win32/registry.rb, line 841
    def delete_value(name)
      API.DeleteValue(@hkey, name)
    end

Delete a registry value named name. We can not delete the ‘default’ value.

Also aliased as: delete
each ()
Alias for: each_value
each_key () { |subkey, wtime| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 617
    def each_key
      return enum_for(:each_key) unless block_given?
      index = 0
      while true
        begin
          subkey, wtime = API.EnumKey(@hkey, index)
        rescue Error
          break
        end
        subkey = export_string(subkey)
        yield subkey, wtime
        index += 1
      end
      index
    end

Enumerate all subkeys.

For each subkey it yields subkey and wtime.

subkey is `String` which contains name of subkey. wtime is last write time as FILETIME (64-bit integer). (see `Registry.wtime2time`)

each_value () { |subkey, type, data| ... }
Source

    # File ext/win32/lib/win32/registry.rb, line 577
    def each_value
      return enum_for(:each_value) unless block_given?
      index = 0
      while true
        begin
          subkey = API.EnumValue(@hkey, index)
        rescue Error
          break
        end
        subkey = export_string(subkey)
        begin
          type, data = read(subkey)
        rescue Error
        else
          yield subkey, type, data
        end
        index += 1
      end
      index
    end

Enumerate all values in this registry path.

For each value it yields key, type and data.

key is a `String` which contains name of key. type is a type contant kind of Win32::Registry::REG_* data is the value of this key.

Also aliased as: each
flush ()
Source

    # File ext/win32/lib/win32/registry.rb, line 877
    def flush
      API.FlushKey @hkey
    end

Write all the attributes into the registry file.

hkey ()
Source

    # File ext/win32/lib/win32/registry.rb, line 499
    def hkey
      @hkey.to_i
    end

Returns key handle value.

info ()
Source

    # File ext/win32/lib/win32/registry.rb, line 900
    def info
      API.QueryInfoKey(@hkey)
    end

Returns key information as `Array` of: :num_keys

    The number of subkeys.

:max_key_length

    Maximum length of name of subkeys.

:num_values

    The number of values.

:max_value_name_length

    Maximum length of name of values.

:max_value_length

    Maximum length of value of values.

:descriptor_length

    Length of security descriptor.

:wtime

    Last write time as FILETIME(64-bit integer)

For detail, see RegQueryInfoKey `Win32` `API`.

inspect ()
Source

    # File ext/win32/lib/win32/registry.rb, line 532
    def inspect
      "\#<Win32::Registry key=#{name.inspect}>"
    end

keys ()
Source

    # File ext/win32/lib/win32/registry.rb, line 636
    def keys
      keys_ary = []
      each_key { |key,| keys_ary << key }
      keys_ary
    end

return keys as an array

name ()
Source

    # File ext/win32/lib/win32/registry.rb, line 523
    def name
      parent = self
      name = @keyname
      while parent = parent.parent
        name = parent.keyname + '\\' + name
      end
      name
    end

Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.

open (subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk)
Source

    # File ext/win32/lib/win32/registry.rb, line 546
    def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk)
      self.class.open(self, subkey, desired, opt, &blk)
    end

Same as `Win32::Registry.open` (self, subkey, desired, opt)

open? ()
Source

    # File ext/win32/lib/win32/registry.rb, line 516
    def open?
      !@hkey.nil?
    end

Returns if key is not closed.

read (name, *rtype)
Source

    # File ext/win32/lib/win32/registry.rb, line 658
    def read(name, *rtype)
      type, data = API.QueryValue(@hkey, name)
      unless rtype.empty? or rtype.include?(type)
        raise TypeError, "Type mismatch (expect [#{
          rtype.map{|t|Registry.type2name(t)}.join(', ')}] but #{
          Registry.type2name(type)} present)"
      end
      case type
      when REG_SZ, REG_EXPAND_SZ
        [ type, data.encode(name.encoding, WCHAR).chop ]
      when REG_MULTI_SZ
        [ type, data.encode(name.encoding, WCHAR).split(/\0/) ]
      when REG_BINARY, REG_NONE
        [ type, data ]
      when REG_DWORD
        [ type, API.unpackdw(data) ]
      when REG_DWORD_BIG_ENDIAN
        [ type, data.unpack1('N') ]
      when REG_QWORD
        [ type, API.unpackqw(data) ]
      else
        raise TypeError, "Type #{Registry.type2name(type)} is not supported."
      end
    end

Read a registry value named name and return array of [ type, data ]. When name is nil, the ‘default’ value is read. type is value type. (see `Win32::Registry::Constants` module) data is value data, its class is: :REG_SZ, REG_EXPAND_SZ

    String

:REG_MULTI_SZ

    Array of String

:REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD

    Integer

:REG_BINARY, REG_NONE

    String (contains binary data)

When rtype is specified, the value type must be included by rtype array, or `TypeError` is raised.

read_bin (name)
Source

    # File ext/win32/lib/win32/registry.rb, line 745
    def read_bin(name)
      read(name, REG_BINARY)[1]
    end

Read a REG_SZ(`read_s`), REG_DWORD(`read_i`), or REG_BINARY(`read_bin`) registry value named name.

If the values type does not match, `TypeError` is raised.

read_i (name)
Source

    # File ext/win32/lib/win32/registry.rb, line 735
    def read_i(name)
      read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1]
    end

Read a REG_SZ(`read_s`), REG_DWORD(`read_i`), or REG_BINARY(`read_bin`) registry value named name.

If the values type does not match, `TypeError` is raised.

read_s (name)
Source

    # File ext/win32/lib/win32/registry.rb, line 710
    def read_s(name)
      read(name, REG_SZ)[1]
    end

Read a REG_SZ(`read_s`), REG_DWORD(`read_i`), or REG_BINARY(`read_bin`) registry value named name.

If the values type does not match, `TypeError` is raised.

read_s_expand (name)
Source

    # File ext/win32/lib/win32/registry.rb, line 720
    def read_s_expand(name)
      type, data = read(name, REG_SZ, REG_EXPAND_SZ)
      if type == REG_EXPAND_SZ
        Registry.expand_environ(data)
      else
        data
      end
    end

Read a REG_SZ or REG_EXPAND_SZ registry value named name.

If the value type is REG_EXPAND_SZ, environment variables are replaced. Unless the value type is REG_SZ or REG_EXPAND_SZ, `TypeError` is raised.

values ()
Source

    # File ext/win32/lib/win32/registry.rb, line 602
    def values
      vals_ary = []
      each_value { |*, val| vals_ary << val }
      vals_ary
    end

return values as an array

write (name, type, data)
Source

    # File ext/win32/lib/win32/registry.rb, line 757
    def write(name, type, data)
      case type
      when REG_SZ, REG_EXPAND_SZ
        data = data.encode(WCHAR) << WCHAR_NUL
      when REG_MULTI_SZ
        data = data.to_a.map {|s| s.encode(WCHAR)}.join(WCHAR_NUL) << WCHAR_NUL
      when REG_BINARY, REG_NONE
        data = data.to_s
      when REG_DWORD
        data = API.packdw(data.to_i)
      when REG_DWORD_BIG_ENDIAN
        data = [data.to_i].pack('N')
      when REG_QWORD
        data = API.packqw(data.to_i)
      else
        raise TypeError, "Unsupported type #{Registry.type2name(type)}"
      end
      API.SetValue(@hkey, name, type, data, data.bytesize)
    end

Write data to a registry value named name. When name is nil, write to the ‘default’ value.

type is type value. (see `Registry::Constants` module) `Class` of data must be same as which `read` method returns.

write_bin (name, value)
Source

    # File ext/win32/lib/win32/registry.rb, line 833
    def write_bin(name, value)
      write name, REG_BINARY, value.to_s
    end

Write value to a registry value named name.

The value type is REG_SZ(`write_s`), REG_DWORD(`write_i`), or REG_BINARY(`write_bin`).

write_i (name, value)
Source

    # File ext/win32/lib/win32/registry.rb, line 823
    def write_i(name, value)
      write name, REG_DWORD, value.to_i
    end

Write value to a registry value named name.

The value type is REG_SZ(`write_s`), REG_DWORD(`write_i`), or REG_BINARY(`write_bin`).

write_s (name, value)
Source

    # File ext/win32/lib/win32/registry.rb, line 813
    def write_s(name, value)
      write name, REG_SZ, value.to_s
    end

Write value to a registry value named name.

The value type is REG_SZ(`write_s`), REG_DWORD(`write_i`), or REG_BINARY(`write_bin`).