class Win32::Registry - win32: Ruby Standard Library Documentation

# 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| ... } click to toggle source

— `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.

    # File 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

expand_environ(str) click to toggle source

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.

    # File 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

new(hkey, parent, keyname, disposition) click to toggle source

initialize

    # File 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

open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |obj| ... } click to toggle source

— `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.

    # File 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

time2wtime(time) click to toggle source

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

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

type2name(type) click to toggle source

Convert registry type value to readable string.

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

wtime2time(wtime) click to toggle source

Convert 64-bit FILETIME integer into Time object.

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

### Public Instance Methods

[](name, *rtype) click to toggle source

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.

    # File 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

[]=(name, rtype, value = nil) click to toggle source

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

    # File 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

_dump(depth) click to toggle source

marshalling is not allowed

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

close() click to toggle source

Close key.

After close, most method raise an error.

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

create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) click to toggle source

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

    # File 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

created?() click to toggle source

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

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

delete(name)
Alias for: delete_value
delete_key(name, recursive = false) click to toggle source

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.

    # File 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_value(name) click to toggle source

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

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

Also aliased as: delete
each()
Alias for: each_value
each_key() { |subkey, wtime| ... } click to toggle source

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`)

    # File 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

each_value() { |subkey, type, data| ... } click to toggle source

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.

    # File 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

Also aliased as: each
flush() click to toggle source

Write all the attributes into the registry file.

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

hkey() click to toggle source

Returns key handle value.

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

info() click to toggle source

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`.

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

inspect() click to toggle source

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

keys() click to toggle source

return keys as an array

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

name() click to toggle source

Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.

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

open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) click to toggle source

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

    # File 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

open?() click to toggle source

Returns if key is not closed.

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

read(name, *rtype) click to toggle source

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.

    # File 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_bin(name) click to toggle source

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.

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

read_i(name) click to toggle source

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.

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

read_s(name) click to toggle source

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.

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

read_s_expand(name) click to toggle source

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.

    # File 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

values() click to toggle source

return values as an array

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

write(name, type, data) click to toggle source

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.

    # File 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_bin(name, value) click to toggle source

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`).

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

write_i(name, value) click to toggle source

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`).

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

write_s(name, value) click to toggle source

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`).

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