Class: Win32::Registry

Relationships & Source Files
Namespace Children
Modules: `API`, `Constants`
Classes: `PredefinedKey`
Exceptions: `Error`
Extension / Inclusion / Inheritance Descendants
Subclasses: PredefinedKey
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, Enumerable, `Constants`
Inherits:	Object
Defined in:	ext/win32/lib/win32/registry.rb

Constant Summary

`Constants` - Included

HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_DYN_DATA, HKEY_LOCAL_MACHINE, HKEY_PERFORMANCE_DATA, HKEY_PERFORMANCE_NLSTEXT, HKEY_PERFORMANCE_TEXT, HKEY_USERS, KEY_ALL_ACCESS, KEY_CREATE_LINK, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_EXECUTE, KEY_NOTIFY, KEY_QUERY_VALUE, KEY_READ, KEY_SET_VALUE, KEY_WRITE, MAX_KEY_LENGTH, MAX_VALUE_LENGTH, REG_BINARY, REG_CREATED_NEW_KEY, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_DWORD_LITTLE_ENDIAN, REG_EXPAND_SZ, REG_FORCE_RESTORE, REG_FULL_RESOURCE_DESCRIPTOR, REG_LEGAL_OPTION, REG_LINK, REG_MULTI_SZ, REG_NONE, REG_NO_LAZY_FLUSH, REG_OPENED_EXISTING_KEY, REG_OPTION_BACKUP_RESTORE, REG_OPTION_CREATE_LINK, REG_OPTION_NON_VOLATILE, REG_OPTION_OPEN_LINK, REG_OPTION_RESERVED, REG_OPTION_VOLATILE, REG_QWORD, REG_QWORD_LITTLE_ENDIAN, REG_REFRESH_HIVE, REG_RESOURCE_LIST, REG_RESOURCE_REQUIREMENTS_LIST, REG_SZ, REG_WHOLE_HIVE_VOLATILE, STANDARD_RIGHTS_READ, STANDARD_RIGHTS_WRITE

Class Method Summary

.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

— .create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED).
.expand_environ(str)

Replace %w+% into the environment value of what is contained between the %‘s This method is used for REG_EXPAND_SZ.
.new(hkey, parent, keyname, disposition) ⇒ Registry constructor

initialize.
.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

— .open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED).
.time2wtime(time)

Convert Time object or Integer object into 64-bit FILETIME.
.type2name(type)

Convert registry type value to readable string.
.wtime2time(wtime)

Convert 64-bit FILETIME integer into Time object.

Instance Attribute Summary

#created? ⇒ Boolean readonly

Returns if key is created ((newly)).
#disposition readonly

Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
#keyname readonly

Same as subkey value of .open or .create method.
#open? ⇒ Boolean readonly

Returns if key is not closed.
#parent readonly

Registry object of parent key, or nil if predefeined key.

Instance Method Summary

#[](name, *rtype)

Read a registry value named name and return its value data.
#[]=(name, rtype, value = nil)

Write value to a registry value named name.
#_dump(depth)

marshalling is not allowed.
#close

Close key.
#create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)

Same as .create (self, subkey, desired, opt).
#delete(name)

Alias for #delete_value.
#delete_key(name, recursive = false)

Delete a subkey named name and all its values.
#delete_value(name) (also: #delete)

Delete a registry value named name.
#each

Alias for #each_value.
#each_key

Enumerate all subkeys.
#each_value (also: #each)

Enumerate all values in this registry path.
#flush

Write all the attributes into the registry file.
#hkey

Returns key handle value.
#info

Returns key information as Array of: :num_keys.
#inspect
#keys

return keys as an array.
#name

Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.
#open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) readonly

Same as .open (self, subkey, desired, opt).
#read(name, *rtype)

Read a registry value named name and return array of [ type, data ].
#read_bin(name)

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

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

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

Read a REG_SZ or REG_EXPAND_SZ registry value named name.
#values

return values as an array.
#write(name, type, data)

Write data to a registry value named name.
#write_bin(name, value)

Write value to a registry value named name.
#write_i(name, value)

Write value to a registry value named name.
#write_s(name, value)

Write value to a registry value named name.
#export_string(str, enc = Encoding.default_internal || LOCALE) private Internal use only

Constructor Details

.new(hkey, parent, keyname, disposition) ⇒ `Registry`

initialize

[ GitHub ]

# 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

Class Method Details

.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

— .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 Registry::Constants)

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

If block is given, the key is closed automatically.

[ GitHub ]

# 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

.expand_environ(str)

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.

[ GitHub ]

# 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

.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

— .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 Registry object of parent key. You can use predefined key HKEY_* (see Registry::Constants) desired and opt is access mask and key option. For detail, see the MSDN. If block is given, the key is closed automatically.

[ GitHub ]

# 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

.time2wtime(time)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 411


def self.time2wtime(time)
  time.to_i * 10000000 + 116444736000000000
end

.type2name(type)

Convert registry type value to readable string.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 397


def self.type2name(type)
  @@type2name[type] || type.to_s
end

.wtime2time(wtime)

Convert 64-bit FILETIME integer into Time object.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 404


def self.wtime2time(wtime)
  Time.at((wtime - 116444736000000000) / 10000000)
end

Instance Attribute Details

#created? ⇒ `Boolean` (readonly)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 509


def created?
  @disposition == REG_CREATED_NEW_KEY
end

#disposition (readonly)

Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 496


attr_reader :disposition

#keyname (readonly)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 494


attr_reader :keyname

#open? ⇒ `Boolean` (readonly)

Returns if key is not closed.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 516


def open?
  !@hkey.nil?
end

#parent (readonly)

Registry object of parent key, or nil if predefeined key.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 491


attr_reader :parent

Instance Method Details

#[](name, *rtype)

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.

[ GitHub ]

# 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

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

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

[ GitHub ]

# 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

#_dump(depth)

marshalling is not allowed

Raises:

(TypeError)

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 539


def _dump(depth)
  raise TypeError, "can't dump Win32::Registry"
end

#close

Close key.

After close, most method raise an error.

[ GitHub ]

# File 'ext/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)

Same as .create (self, subkey, desired, opt)

[ GitHub ]

# 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

#delete(name)

Alias for #delete_value.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 844


alias delete delete_value

#delete_key(name, recursive = false)

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.

[ GitHub ]

# 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_value(name) Also known as: #delete

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 841


def delete_value(name)
  API.DeleteValue(@hkey, name)
end

#each

Alias for #each_value.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 597


alias each each_value

#each_key

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

[ GitHub ]

# 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

#each_value Also known as: #each

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.

[ GitHub ]

# 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

#export_string(str, enc = Encoding.default_internal || LOCALE) (private)

This method is for internal use only.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 921


def export_string(str, enc = Encoding.default_internal || LOCALE) # :nodoc:
  str.encode(enc)
end

#flush

Write all the attributes into the registry file.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 877


def flush
  API.FlushKey @hkey
end

#hkey

Returns key handle value.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 499


def hkey
  @hkey.to_i
end

#info

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.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 900


def info
  API.QueryInfoKey(@hkey)
end

#inspect

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 532


def inspect
  "\#<Win32::Registry key=#{name.inspect}>"
end

#keys

return keys as an array

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 636


def keys
  keys_ary = []
  each_key { |key,| keys_ary << key }
  keys_ary
end

#name

Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.

[ GitHub ]

# 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

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

Same as .open (self, subkey, desired, opt)

[ GitHub ]

# 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

#read(name, *rtype)

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

[ GitHub ]

# 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_bin(name)

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.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 745


def read_bin(name)
  read(name, REG_BINARY)[1]
end

#read_i(name)

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.

[ GitHub ]

# 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_s(name)

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.

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 710


def read_s(name)
  read(name, REG_SZ)[1]
end

#read_s_expand(name)

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.

[ GitHub ]

# 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

#values

return values as an array

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 602


def values
  vals_ary = []
  each_value { |*, val| vals_ary << val }
  vals_ary
end

#write(name, type, data)

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.

[ GitHub ]

# 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_bin(name, value)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 833


def write_bin(name, value)
  write name, REG_BINARY, value.to_s
end

#write_i(name, value)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 823


def write_i(name, value)
  write name, REG_DWORD, value.to_i
end

#write_s(name, value)

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

[ GitHub ]

# File 'ext/win32/lib/win32/registry.rb', line 813


def write_s(name, value)
  write name, REG_SZ, value.to_s
end

Class: Win32::Registry

Constant Summary

Constants - Included

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(hkey, parent, keyname, disposition) ⇒ Registry

Class Method Details

.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

.expand_environ(str)

.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

.time2wtime(time)

.type2name(type)

.wtime2time(wtime)

Instance Attribute Details

#created? ⇒ Boolean (readonly)

#disposition (readonly)

#keyname (readonly)

#open? ⇒ Boolean (readonly)

#parent (readonly)

Instance Method Details

#[](name, *rtype)

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

#_dump(depth)

#close

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

#delete(name)

#delete_key(name, recursive = false)

#delete_value(name) Also known as: #delete

#each

#each_key

#each_value Also known as: #each

#export_string(str, enc = Encoding.default_internal || LOCALE) (private)

#flush

#hkey

#info

#inspect

#keys

#name

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

#read(name, *rtype)

#read_bin(name)

#read_i(name)

#read_s(name)

#read_s_expand(name)

#values

#write(name, type, data)

#write_bin(name, value)

#write_i(name, value)

#write_s(name, value)

`Constants` - Included

.new(hkey, parent, keyname, disposition) ⇒ `Registry`

#created? ⇒ `Boolean` (readonly)

#open? ⇒ `Boolean` (readonly)