In Files

  • fiddle/win32/lib/win32/registry.rb

Win32::Registry

Win32 Registry

win32/registry is registry accessor library for Win32 platform. It uses fiddle/import 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

Reference

Win32::Registry class

Attributes

disposition[R]

Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).

hkey[R]

Returns key handle value.

keyname[R]

Same as subkey value of ::open or ::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) click to toggle source

::create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

::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 #created? method will return false.

If block is given, the key is closed automatically.

 
               # File fiddle/win32/lib/win32/registry.rb, line 411
def self.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
  newkey, disp = API.CreateKey(hkey.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 fiddle/win32/lib/win32/registry.rb, line 332
def self.expand_environ(str)
  str.gsub(/%([^%]+)%/) { ENV[$1] || ENV[$1.upcase] || $& }
end
            
new(hkey, parent, keyname, disposition) click to toggle source

initialize

 
               # File fiddle/win32/lib/win32/registry.rb, line 433
def initialize(hkey, parent, keyname, disposition)
  @hkey = 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) click to toggle source

::open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

::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 fiddle/win32/lib/win32/registry.rb, line 383
def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
  subkey = subkey.chomp('\')
  newkey = API.OpenKey(hkey.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 fiddle/win32/lib/win32/registry.rb, line 363
def self.time2wtime(time)
  time.to_i * 10000000 + 116444736000000000
end
            
type2name(type) click to toggle source

Convert registry type value to readable string.

 
               # File fiddle/win32/lib/win32/registry.rb, line 349
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 fiddle/win32/lib/win32/registry.rb, line 356
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 value is same as 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 same as read method.

 
               # File fiddle/win32/lib/win32/registry.rb, line 620
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 #{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 fiddle/win32/lib/win32/registry.rb, line 715
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 fiddle/win32/lib/win32/registry.rb, line 488
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 fiddle/win32/lib/win32/registry.rb, line 511
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 ::create (self, subkey, desired, opt)

 
               # File fiddle/win32/lib/win32/registry.rb, line 502
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 ::create) – basically you call create then when you call created? on the instance returned it will tell if it was successful or not

 
               # File fiddle/win32/lib/win32/registry.rb, line 458
def created?
  @disposition == REG_CREATED_NEW_KEY
end
            
delete(name) click to toggle source
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 fiddle/win32/lib/win32/registry.rb, line 778
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 fiddle/win32/lib/win32/registry.rb, line 767
def delete_value(name)
  API.DeleteValue(@hkey, name)
end
            
Also aliased as: delete
each() click to toggle source
Alias for: each_value
each_key() click to toggle source

Enumerate subkeys.

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

 
               # File fiddle/win32/lib/win32/registry.rb, line 547
def each_key
  index = 0
  while true
    begin
      subkey, wtime = API.EnumKey(@hkey, index)
    rescue Error
      break
    end
    yield subkey, wtime
    index += 1
  end
  index
end
            
each_value() click to toggle source

Enumerate values.

 
               # File fiddle/win32/lib/win32/registry.rb, line 520
def each_value
  index = 0
  while true
    begin
      subkey = API.EnumValue(@hkey, index)
    rescue Error
      break
    end
    begin
      type, data = read(subkey)
    rescue Error
      next
    end
    yield subkey, type, data
    index += 1
  end
  index
end
            
Also aliased as: each
flush() click to toggle source

Write all the attributes into the registry file.

 
               # File fiddle/win32/lib/win32/registry.rb, line 803
def flush
  API.FlushKey @hkey
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 fiddle/win32/lib/win32/registry.rb, line 826
def info
  API.QueryInfoKey(@hkey)
end
            
inspect() click to toggle source
 
               # File fiddle/win32/lib/win32/registry.rb, line 481
def inspect
  "\#<Win32::Registry key=#{name.inspect}>"
end
            
keys() click to toggle source

return keys as an array

 
               # File fiddle/win32/lib/win32/registry.rb, line 564
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 fiddle/win32/lib/win32/registry.rb, line 472
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 ::open (self, subkey, desired, opt)

 
               # File fiddle/win32/lib/win32/registry.rb, line 495
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 fiddle/win32/lib/win32/registry.rb, line 465
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

String (contains binary data)

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

 
               # File fiddle/win32/lib/win32/registry.rb, line 586
def read(name, *rtype)
  type, data = API.QueryValue(@hkey, name)
  unless rtype.empty? or rtype.include?(type)
    raise TypeError, "Type mismatch (expect #{rtype.inspect} but #{type} present)"
  end
  case type
  when REG_SZ, REG_EXPAND_SZ
    [ type, data.chop ]
  when REG_MULTI_SZ
    [ type, data.split(/\0/) ]
  when REG_BINARY
    [ type, data ]
  when REG_DWORD
    [ type, API.unpackdw(data) ]
  when REG_DWORD_BIG_ENDIAN
    [ type, data.unpack('N')[0] ]
  when REG_QWORD
    [ type, API.unpackqw(data) ]
  else
    raise TypeError, "Type #{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 fiddle/win32/lib/win32/registry.rb, line 671
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 fiddle/win32/lib/win32/registry.rb, line 661
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 fiddle/win32/lib/win32/registry.rb, line 636
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 fiddle/win32/lib/win32/registry.rb, line 646
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
            
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 fiddle/win32/lib/win32/registry.rb, line 683
def write(name, type, data)
  case type
  when REG_SZ, REG_EXPAND_SZ
    data = data.to_s + "\0"
  when REG_MULTI_SZ
    data = data.to_a.join("\0") + "\0\0"
  when REG_BINARY
    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 #{type}"
  end
  API.SetValue(@hkey, name, type, data, data.length)
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 fiddle/win32/lib/win32/registry.rb, line 759
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 fiddle/win32/lib/win32/registry.rb, line 749
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 fiddle/win32/lib/win32/registry.rb, line 739
def write_s(name, value)
  write name, REG_SZ, value.to_s
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus