Returns key handle value.
Win32::Registry object of parent key, or nil if predefeined key.
Same as subkey value of Registry.open or Registry.create method.
Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
# File tmp/rubies/ruby-3.4.0-preview1/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.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.
# File tmp/rubies/ruby-3.4.0-preview1/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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 481
def initialize(hkey, parent, keyname, disposition)
@hkey = hkey
@parent = parent
@keyname = keyname
@disposition = disposition
@hkeyfinal = [ hkey ]
ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal)
end
initialize
# File tmp/rubies/ruby-3.4.0-preview1/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.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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 411
def self.time2wtime(time)
time.to_i * 10000000 + 116444736000000000
end
# File tmp/rubies/ruby-3.4.0-preview1/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.
# File tmp/rubies/ruby-3.4.0-preview1/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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 681
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 776
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
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 536
def _dump(depth)
raise TypeError, "can't dump Win32::Registry"
end
marshalling is not allowed
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 559
def close
API.CloseKey(@hkey)
@hkey = @parent = @keyname = nil
@hkeyfinal[0] = nil
end
Close key.
After close, most method raise an error.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 550
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)
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 506
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
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 839
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 828
def delete_value(name)
API.DeleteValue(@hkey, name)
end
Delete a registry value named name. We can not delete the ‘default’ value.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 605
def each_key
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 subkeys.
subkey is String which contains name of subkey. wtime is last write time as FILETIME (64-bit integer). (see Registry.wtime2time)
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 568
def each_value
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 values.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 864
def flush
API.FlushKey @hkey
end
Write all the attributes into the registry file.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 887
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 529
def inspect
"\#<Win32::Registry key=#{name.inspect}>"
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 623
def keys
keys_ary = []
each_key { |key,| keys_ary << key }
keys_ary
end
return keys as an array
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 520
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’.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 543
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)
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 513
def open?
!@hkey.nil?
end
Returns if key is not closed.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 645
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 732
def read_bin(name)
read(name, REG_BINARY)[1]
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 722
def read_i(name)
read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1]
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 697
def read_s(name)
read(name, REG_SZ)[1]
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 707
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 592
def values
vals_ary = []
each_value { |*, val| vals_ary << val }
vals_ary
end
return values as an array
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 744
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.
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 820
def write_bin(name, value)
write name, REG_BINARY, value.to_s
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 810
def write_i(name, value)
write name, REG_DWORD, value.to_i
end
# File tmp/rubies/ruby-3.4.0-preview1/ext/win32/lib/win32/registry.rb, line 800
def write_s(name, value)
write name, REG_SZ, value.to_s
end