Class: Win32::Registry
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Exceptions:
| |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
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)
—
Registry
.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)
—
Registry
.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).
-
#hkey
readonly
Returns key handle value.
- #keyname readonly
-
#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 subkeys.
-
#each_value
(also: #each)
Enumerate values.
-
#flush
Write all the attributes into the registry file.
-
#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.
Constructor Details
.new(hkey, parent, keyname, disposition) ⇒ Registry
initialize
# File 'ext/win32/lib/win32/registry.rb', line 479
def initialize(hkey, parent, keyname, disposition) @hkey = 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)
— 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 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.
# File 'ext/win32/lib/win32/registry.rb', line 457
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)
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 'ext/win32/lib/win32/registry.rb', line 373
def self. (str) str.gsub(Regexp.compile("%([^%]+)%".encode(str.encoding))) { v = $1.encode(LOCALE) (e = ENV[v] || ENV[v.upcase]; e.encode(str.encoding) if e) || $& } end
.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
— 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 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.
# File 'ext/win32/lib/win32/registry.rb', line 429
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)
Convert Time object or Integer object into 64-bit FILETIME.
# File 'ext/win32/lib/win32/registry.rb', line 409
def self.time2wtime(time) time.to_i * 10000000 + 116444736000000000 end
.type2name(type)
Convert registry type value to readable string.
# File 'ext/win32/lib/win32/registry.rb', line 395
def self.type2name(type) @@type2name[type] || type.to_s end
.wtime2time(wtime)
Convert 64-bit FILETIME integer into Time object.
# File 'ext/win32/lib/win32/registry.rb', line 402
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
# File 'ext/win32/lib/win32/registry.rb', line 504
def created? @disposition == REG_CREATED_NEW_KEY end
#disposition (readonly)
Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
# File 'ext/win32/lib/win32/registry.rb', line 496
attr_reader :disposition
#hkey (readonly)
Returns key handle value.
# File 'ext/win32/lib/win32/registry.rb', line 489
attr_reader :hkey
#keyname (readonly)
[ GitHub ]# File 'ext/win32/lib/win32/registry.rb', line 494
attr_reader :keyname
#open? ⇒ Boolean
(readonly)
Returns if key is not closed.
# File 'ext/win32/lib/win32/registry.rb', line 511
def open? !@hkey.nil? end
#parent (readonly)
Registry
object of parent key, or nil if predefeined key.
# 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 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 'ext/win32/lib/win32/registry.rb', line 679
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. (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
# File 'ext/win32/lib/win32/registry.rb', line 777
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
# File 'ext/win32/lib/win32/registry.rb', line 534
def _dump(depth) raise TypeError, "can't dump Win32::Registry" end
#close
Close key.
After close, most method raise an error.
# File 'ext/win32/lib/win32/registry.rb', line 557
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)
# File 'ext/win32/lib/win32/registry.rb', line 548
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.
# File 'ext/win32/lib/win32/registry.rb', line 832
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.
# File 'ext/win32/lib/win32/registry.rb', line 840
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.
#each
Alias for #each_value.
# File 'ext/win32/lib/win32/registry.rb', line 585
alias each each_value
#each_key
Enumerate subkeys.
subkey is String which contains name of subkey. wtime is last write time as FILETIME (64-bit integer). (see .wtime2time)
# File 'ext/win32/lib/win32/registry.rb', line 603
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
#each_value Also known as: #each
Enumerate values.
# File 'ext/win32/lib/win32/registry.rb', line 566
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 next end yield subkey, type, data index += 1 end index end
#flush
Write all the attributes into the registry file.
# File 'ext/win32/lib/win32/registry.rb', line 865
def flush API.FlushKey @hkey 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.
# File 'ext/win32/lib/win32/registry.rb', line 888
def info API.QueryInfoKey(@hkey) end
#inspect
[ GitHub ]# File 'ext/win32/lib/win32/registry.rb', line 527
def inspect "\#<Win32::Registry key=#{name.inspect}>" end
#keys
return keys as an array
# File 'ext/win32/lib/win32/registry.rb', line 621
def keys keys_ary = [] each_key { |key,| keys_ary << key } keys_ary end
#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)
# File 'ext/win32/lib/win32/registry.rb', line 541
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
String (contains binary data)
When rtype is specified, the value type must be included by rtype array, or TypeError is raised.
# File 'ext/win32/lib/win32/registry.rb', line 643
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 [ 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 #{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.
# File 'ext/win32/lib/win32/registry.rb', line 730
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.
#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.
#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.
# File 'ext/win32/lib/win32/registry.rb', line 705
def (name) type, data = read(name, REG_SZ, REG_EXPAND_SZ) if type == REG_EXPAND_SZ Registry. (data) else data end end
#values
return values as an array
# File 'ext/win32/lib/win32/registry.rb', line 590
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.
# File 'ext/win32/lib/win32/registry.rb', line 742
def write(name, type, data) termsize = 0 case type when REG_SZ, REG_EXPAND_SZ data = data.encode(WCHAR) termsize = WCHAR_SIZE when REG_MULTI_SZ data = data.to_a.map {|s| s.encode(WCHAR)}.join(WCHAR_NUL) << WCHAR_NUL termsize = WCHAR_SIZE 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 #{Registry.type2name(type)}" end API.SetValue(@hkey, name, type, data, data.bytesize + termsize) 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).
# File 'ext/win32/lib/win32/registry.rb', line 821
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).
#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).