Class: Win32::Registry
- Inherits:
-
Object
- Object
- Win32::Registry
- Includes:
- Enumerable, Constants
- Defined in:
- lib/win32/registry.rb
Direct Known Subclasses
Defined Under Namespace
Modules: API, Constants Classes: Error, PredefinedKey
Constant Summary collapse
- @@type2name =
{ }
- @@final =
finalizer
proc { |hkey| proc { API.CloseKey(hkey[0]) if hkey[0] } }
Constants included from Constants
Constants::HKEY_CLASSES_ROOT, Constants::HKEY_CURRENT_CONFIG, Constants::HKEY_CURRENT_USER, Constants::HKEY_DYN_DATA, Constants::HKEY_LOCAL_MACHINE, Constants::HKEY_PERFORMANCE_DATA, Constants::HKEY_PERFORMANCE_NLSTEXT, Constants::HKEY_PERFORMANCE_TEXT, Constants::HKEY_USERS, Constants::KEY_ALL_ACCESS, Constants::KEY_CREATE_LINK, Constants::KEY_CREATE_SUB_KEY, Constants::KEY_ENUMERATE_SUB_KEYS, Constants::KEY_EXECUTE, Constants::KEY_NOTIFY, Constants::KEY_QUERY_VALUE, Constants::KEY_READ, Constants::KEY_SET_VALUE, Constants::KEY_WRITE, Constants::MAX_KEY_LENGTH, Constants::MAX_VALUE_LENGTH, Constants::REG_BINARY, Constants::REG_CREATED_NEW_KEY, Constants::REG_DWORD, Constants::REG_DWORD_BIG_ENDIAN, Constants::REG_DWORD_LITTLE_ENDIAN, Constants::REG_EXPAND_SZ, Constants::REG_FORCE_RESTORE, Constants::REG_FULL_RESOURCE_DESCRIPTOR, Constants::REG_LEGAL_OPTION, Constants::REG_LINK, Constants::REG_MULTI_SZ, Constants::REG_NONE, Constants::REG_NO_LAZY_FLUSH, Constants::REG_OPENED_EXISTING_KEY, Constants::REG_OPTION_BACKUP_RESTORE, Constants::REG_OPTION_CREATE_LINK, Constants::REG_OPTION_NON_VOLATILE, Constants::REG_OPTION_OPEN_LINK, Constants::REG_OPTION_RESERVED, Constants::REG_OPTION_VOLATILE, Constants::REG_QWORD, Constants::REG_QWORD_LITTLE_ENDIAN, Constants::REG_REFRESH_HIVE, Constants::REG_RESOURCE_LIST, Constants::REG_RESOURCE_REQUIREMENTS_LIST, Constants::REG_SZ, Constants::REG_WHOLE_HIVE_VOLATILE, Constants::STANDARD_RIGHTS_READ, Constants::STANDARD_RIGHTS_WRITE
Instance Attribute Summary collapse
-
#disposition ⇒ Object
readonly
Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
-
#hkey ⇒ Object
readonly
Returns key handle value.
-
#keyname ⇒ Object
readonly
Same as subkey value of Registry.open or Registry.create method.
-
#parent ⇒ Object
readonly
Win32::Registry object of parent key, or nil if predefeined key.
Class Method Summary collapse
-
.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) ⇒ Object
— Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED).
-
.expand_environ(str) ⇒ Object
Replace %w+% into the environment value of what is contained between the %‘s This method is used for REG_EXPAND_SZ.
-
.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) ⇒ Object
— Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED).
-
.time2wtime(time) ⇒ Object
Convert Time object or Integer object into 64-bit FILETIME.
-
.type2name(type) ⇒ Object
Convert registry type value to readable string.
-
.wtime2time(wtime) ⇒ Object
Convert 64-bit FILETIME integer into Time object.
Instance Method Summary collapse
-
#[](name, *rtype) ⇒ Object
Read a registry value named name and return its value data.
-
#[]=(name, rtype, value = nil) ⇒ Object
Write value to a registry value named name.
-
#_dump(depth) ⇒ Object
marshalling is not allowed.
-
#close ⇒ Object
Close key.
-
#create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) ⇒ Object
Same as Win32::Registry.create (self, subkey, desired, opt).
-
#created? ⇒ Boolean
Returns if key is created ((newly)).
-
#delete_key(name, recursive = false) ⇒ Object
Delete a subkey named name and all its values.
-
#delete_value(name) ⇒ Object
(also: #delete)
Delete a registry value named name.
-
#each_key ⇒ Object
Enumerate subkeys.
-
#each_value ⇒ Object
(also: #each)
Enumerate values.
-
#flush ⇒ Object
Write all the attributes into the registry file.
-
#info ⇒ Object
Returns key information as Array of: :num_keys The number of subkeys.
-
#initialize(hkey, parent, keyname, disposition) ⇒ Registry
constructor
initialize.
- #inspect ⇒ Object
-
#keys ⇒ Object
return keys as an array.
-
#name ⇒ Object
Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.
-
#open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) ⇒ Object
Same as Win32::Registry.open (self, subkey, desired, opt).
-
#open? ⇒ Boolean
Returns if key is not closed.
-
#read(name, *rtype) ⇒ Object
Read a registry value named name and return array of [ type, data ].
-
#read_bin(name) ⇒ Object
Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) registry value named name.
-
#read_i(name) ⇒ Object
Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) registry value named name.
-
#read_s(name) ⇒ Object
Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) registry value named name.
-
#read_s_expand(name) ⇒ Object
Read a REG_SZ or REG_EXPAND_SZ registry value named name.
-
#values ⇒ Object
return values as an array.
-
#write(name, type, data) ⇒ Object
Write data to a registry value named name.
-
#write_bin(name, value) ⇒ Object
Write value to a registry value named name.
-
#write_i(name, value) ⇒ Object
Write value to a registry value named name.
-
#write_s(name, value) ⇒ Object
Write value to a registry value named name.
Constructor Details
#initialize(hkey, parent, keyname, disposition) ⇒ Registry
initialize
466 467 468 469 470 471 472 473 |
# File 'lib/win32/registry.rb', line 466 def initialize(hkey, parent, keyname, disposition) @hkey = hkey @parent = parent @keyname = keyname @disposition = disposition @hkeyfinal = [ hkey ] ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal) end |
Instance Attribute Details
#disposition ⇒ Object (readonly)
Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
483 484 485 |
# File 'lib/win32/registry.rb', line 483 def disposition @disposition end |
#hkey ⇒ Object (readonly)
Returns key handle value.
476 477 478 |
# File 'lib/win32/registry.rb', line 476 def hkey @hkey end |
#keyname ⇒ Object (readonly)
Same as subkey value of Registry.open or Registry.create method.
481 482 483 |
# File 'lib/win32/registry.rb', line 481 def keyname @keyname end |
#parent ⇒ Object (readonly)
Win32::Registry object of parent key, or nil if predefeined key.
478 479 480 |
# File 'lib/win32/registry.rb', line 478 def parent @parent end |
Class Method Details
.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) ⇒ Object
— 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.
444 445 446 447 448 449 450 451 452 453 454 455 456 |
# File 'lib/win32/registry.rb', line 444 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) ⇒ Object
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.
361 362 363 364 365 366 367 |
# File 'lib/win32/registry.rb', line 361 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) ⇒ Object
— 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.
416 417 418 419 420 421 422 423 424 425 426 427 428 429 |
# File 'lib/win32/registry.rb', line 416 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) ⇒ Object
Convert Time object or Integer object into 64-bit FILETIME.
396 397 398 |
# File 'lib/win32/registry.rb', line 396 def self.time2wtime(time) time.to_i * 10000000 + 116444736000000000 end |
.type2name(type) ⇒ Object
Convert registry type value to readable string.
382 383 384 |
# File 'lib/win32/registry.rb', line 382 def self.type2name(type) @@type2name[type] || type.to_s end |
.wtime2time(wtime) ⇒ Object
Convert 64-bit FILETIME integer into Time object.
389 390 391 |
# File 'lib/win32/registry.rb', line 389 def self.wtime2time(wtime) Time.at((wtime - 116444736000000000) / 10000000) end |
Instance Method Details
#[](name, *rtype) ⇒ Object
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.
664 665 666 667 668 669 670 671 672 673 674 |
# File 'lib/win32/registry.rb', line 664 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 #{type} is not supported." end end |
#[]=(name, rtype, value = nil) ⇒ Object
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
762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 |
# File 'lib/win32/registry.rb', line 762 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) ⇒ Object
marshalling is not allowed
521 522 523 |
# File 'lib/win32/registry.rb', line 521 def _dump(depth) raise TypeError, "can't dump Win32::Registry" end |
#close ⇒ Object
Close key.
After close, most method raise an error.
544 545 546 547 548 |
# File 'lib/win32/registry.rb', line 544 def close API.CloseKey(@hkey) @hkey = @parent = @keyname = nil @hkeyfinal[0] = nil end |
#create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) ⇒ Object
Same as Win32::Registry.create (self, subkey, desired, opt)
535 536 537 |
# File 'lib/win32/registry.rb', line 535 def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) self.class.create(self, subkey, desired, opt, &blk) end |
#created? ⇒ Boolean
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
491 492 493 |
# File 'lib/win32/registry.rb', line 491 def created? @disposition == REG_CREATED_NEW_KEY end |
#delete_key(name, recursive = false) ⇒ Object
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.
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 |
# File 'lib/win32/registry.rb', line 825 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) ⇒ Object Also known as: delete
Delete a registry value named name. We can not delete the ‘default’ value.
814 815 816 |
# File 'lib/win32/registry.rb', line 814 def delete_value(name) API.DeleteValue(@hkey, name) end |
#each_key ⇒ Object
Enumerate subkeys.
subkey is String which contains name of subkey. wtime is last write time as FILETIME (64-bit integer). (see Registry.wtime2time)
590 591 592 593 594 595 596 597 598 599 600 601 602 603 |
# File 'lib/win32/registry.rb', line 590 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 ⇒ Object Also known as: each
Enumerate values.
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 |
# File 'lib/win32/registry.rb', line 553 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 ⇒ Object
Write all the attributes into the registry file.
850 851 852 |
# File 'lib/win32/registry.rb', line 850 def flush API.FlushKey @hkey end |
#info ⇒ Object
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.
873 874 875 |
# File 'lib/win32/registry.rb', line 873 def info API.QueryInfoKey(@hkey) end |
#inspect ⇒ Object
514 515 516 |
# File 'lib/win32/registry.rb', line 514 def inspect "\#<Win32::Registry key=#{name.inspect}>" end |
#keys ⇒ Object
return keys as an array
608 609 610 611 612 |
# File 'lib/win32/registry.rb', line 608 def keys keys_ary = [] each_key { |key,| keys_ary << key } keys_ary end |
#name ⇒ Object
Full path of key such as ‘HKEY_CURRENT_USERSOFTWAREfoobar’.
505 506 507 508 509 510 511 512 |
# File 'lib/win32/registry.rb', line 505 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) ⇒ Object
Same as Win32::Registry.open (self, subkey, desired, opt)
528 529 530 |
# File 'lib/win32/registry.rb', line 528 def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) self.class.open(self, subkey, desired, opt, &blk) end |
#open? ⇒ Boolean
Returns if key is not closed.
498 499 500 |
# File 'lib/win32/registry.rb', line 498 def open? !@hkey.nil? end |
#read(name, *rtype) ⇒ Object
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.
630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 |
# File 'lib/win32/registry.rb', line 630 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.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 #{type} is not supported." end end |
#read_bin(name) ⇒ Object
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.
715 716 717 |
# File 'lib/win32/registry.rb', line 715 def read_bin(name) read(name, REG_BINARY)[1] end |
#read_i(name) ⇒ Object
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.
705 706 707 |
# File 'lib/win32/registry.rb', line 705 def read_i(name) read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1] end |
#read_s(name) ⇒ Object
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.
680 681 682 |
# File 'lib/win32/registry.rb', line 680 def read_s(name) read(name, REG_SZ)[1] end |
#read_s_expand(name) ⇒ Object
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.
690 691 692 693 694 695 696 697 |
# File 'lib/win32/registry.rb', line 690 def (name) type, data = read(name, REG_SZ, REG_EXPAND_SZ) if type == REG_EXPAND_SZ Registry.(data) else data end end |
#values ⇒ Object
return values as an array
577 578 579 580 581 |
# File 'lib/win32/registry.rb', line 577 def values vals_ary = [] each_value { |*, val| vals_ary << val } vals_ary end |
#write(name, type, data) ⇒ Object
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.
727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 |
# File 'lib/win32/registry.rb', line 727 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 #{type}" end API.SetValue(@hkey, name, type, data, data.bytesize + termsize) end |
#write_bin(name, value) ⇒ Object
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).
806 807 808 |
# File 'lib/win32/registry.rb', line 806 def write_bin(name, value) write name, REG_BINARY, value.to_s end |
#write_i(name, value) ⇒ Object
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).
796 797 798 |
# File 'lib/win32/registry.rb', line 796 def write_i(name, value) write name, REG_DWORD, value.to_i end |
#write_s(name, value) ⇒ Object
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).
786 787 788 |
# File 'lib/win32/registry.rb', line 786 def write_s(name, value) write name, REG_SZ, value.to_s end |