summaryrefslogtreecommitdiff
path: root/ext/dl/win32
diff options
context:
space:
mode:
authornaruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2009-11-02 02:24:11 +0000
committernaruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2009-11-02 02:24:11 +0000
commit7539e11a7f742e11fdfe051798cf07b951384df9 (patch)
tree7bd5eef70fcc632554bde0064e8544f3603d7603 /ext/dl/win32
parent71f0685fe360a87af23bdeed92b0ebeea0d4690e (diff)
* ext/dl/win32/lib/win32/registry.rb: update rdoc. [ruby-core:26022]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@25626 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/dl/win32')
-rw-r--r--ext/dl/win32/lib/win32/registry.rb478
1 files changed, 242 insertions, 236 deletions
diff --git a/ext/dl/win32/lib/win32/registry.rb b/ext/dl/win32/lib/win32/registry.rb
index a2b69a08fe..5742d0f376 100644
--- a/ext/dl/win32/lib/win32/registry.rb
+++ b/ext/dl/win32/lib/win32/registry.rb
@@ -1,5 +1,9 @@
-=begin
-= Win32 Registry I/F
+require 'dl/import'
+module Win32
+
+=begin rdoc
+= Win32 Registry
+
win32/registry is registry accessor library for Win32 platform.
It uses dl/import to call Win32 Registry APIs.
@@ -24,247 +28,69 @@ It uses dl/import to call Win32 Registry APIs.
== Win32::Registry class
-=== including modules
-
-* Enumerable
-* Registry::Constants
-
-=== class methods
---- 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 ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp>)).
-
- If block is given, the key is closed automatically.
-
---- 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.
-
---- Registry.expand_environ(str)
- Replace (({%\w+%})) into the environment value of ((|str|)).
- This method is used for REG_EXPAND_SZ.
-
- For detail, see ((<ExpandEnvironmentStrings|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp>)) Win32 API.
-
---- Registry.type2name(type)
- Convert registry type value to readable string.
-
---- Registry.wtime2time(wtime)
- Convert 64-bit FILETIME integer into Time object.
-
---- Registry.time2wtime(time)
- Convert Time object or Integer object into 64-bit FILETIME.
-
-=== instance methods
---- open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
- Same as (({Win32::((<Registry.open>))(self, subkey, desired, opt)}))
-
---- create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
- Same as (({Win32::((<Registry.create>))(self, subkey, desired, opt)}))
-
---- close
- Close key.
-
- After closed, most method raises error.
-
---- 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 ((<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.
-
---- self[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.
-
---- read_s(name)
---- read_i(name)
---- 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.
-
---- 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.
-
---- 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.
-
---- self[name, wtype = nil] = value
- 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
-
---- write_s(name, value)
---- write_i(name, value)
---- 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).
-
---- each { |name, type, value| ... }
---- each_value { |name, type, value| ... }
- Enumerate values.
-
---- each_key { |subkey, wtime| ... }
- Enumerate subkeys.
-
- ((|subkey|)) is String which contains name of subkey.
- ((|wtime|)) is last write time as FILETIME (64-bit integer).
- (see ((<Registry.wtime2time>)))
-
---- delete(name)
---- delete_value(name)
- Delete a registry value named ((|name|)).
- We can not delete the `default' 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.
-
---- flush
- Write all the attributes into the registry file.
-
---- created?
- Returns if key is created ((*newly*)).
- (see ((<Registry.create>)))
-
---- open?
- Returns if key is not closed.
-
---- hkey
- Returns key handle value.
-
---- parent
- Win32::Registry object of parent key, or nil if predefeined key.
-
---- keyname
- Same as ((|subkey|)) value of ((<Registry.open>)) or
- ((<Registry.create>)) method.
-
---- disposition
- Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
-
---- name
---- to_s
- Full path of key such as (({'HKEY_CURRENT_USER\SOFTWARE\foo\bar'})).
-
--- 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|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp>)) Win32 API.
--- num_keys
+
--- max_key_length
+
--- num_values
+
--- max_value_name_length
+
--- max_value_length
+
--- descriptor_length
+
--- wtime
Returns an item of key information.
=== constants
--- HKEY_CLASSES_ROOT
---- HKEY_CURRENT_USER
---- HKEY_LOCAL_MACHINE
---- HKEY_PERFORMANCE_DATA
---- HKEY_CURRENT_CONFIG
---- HKEY_DYN_DATA
- Win32::Registry object whose key is predefined key.
- For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp>)).
-== Win32::Registry::Constants module
-
-For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp>)).
-
---- HKEY_*
- Predefined key ((*handle*)).
- These are Integer, not Win32::Registry.
+--- HKEY_CURRENT_USER
---- REG_*
- Registry value type.
+--- HKEY_LOCAL_MACHINE
---- KEY_*
- Security access mask.
+--- HKEY_PERFORMANCE_DATA
---- KEY_OPTIONS_*
- Key options.
+--- HKEY_CURRENT_CONFIG
---- REG_CREATED_NEW_KEY
---- REG_OPENED_EXISTING_KEY
- If the key is created newly or opened existing key.
- See also Registry#((<disposition>)) method.
+--- HKEY_DYN_DATA
-=end
+ Win32::Registry object whose key is predefined key.
+For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp] article.
-require 'dl/import'
+=end rdoc
-module Win32
class Registry
+
+ #
+ # For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp].
+ #
+ # --- HKEY_*
+ #
+ # Predefined key ((*handle*)).
+ # These are Integer, not Win32::Registry.
+ #
+ # --- REG_*
+ #
+ # Registry value type.
+ #
+ # --- KEY_*
+ #
+ # Security access mask.
+ #
+ # --- KEY_OPTIONS_*
+ #
+ # Key options.
+ #
+ # --- REG_CREATED_NEW_KEY
+ #
+ # --- REG_OPENED_EXISTING_KEY
+ #
+ # If the key is created newly or opened existing key.
+ # See also Registry#disposition method.
module Constants
HKEY_CLASSES_ROOT = 0x80000000
HKEY_CURRENT_USER = 0x80000001
@@ -365,7 +191,7 @@ module Win32
raise Error.new(5) ## ERROR_ACCESS_DENIED
end
- # Fake class for Registry#open, Registry#create
+ # Fake #class method for Registry#open, Registry#create
def class
Registry
end
@@ -498,7 +324,10 @@ module Win32
end
#
- # utility functions
+ # 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[http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp] \Win32 \API.
#
def self.expand_environ(str)
str.gsub(/%([^%]+)%/) { ENV[$1] || ENV[$1.upcase] || $& }
@@ -514,23 +343,43 @@ module Win32
@@type2name[Constants.const_get(type)] = type
end
+ #
+ # Convert registry type value to readable string.
+ #
def self.type2name(type)
@@type2name[type] || type.to_s
end
+ #
+ # Convert 64-bit FILETIME integer into Time object.
+ #
def self.wtime2time(wtime)
Time.at((wtime - 116444736000000000) / 10000000)
end
+ #
+ # Convert Time object or Integer object into 64-bit FILETIME.
+ #
def self.time2wtime(time)
time.to_i * 10000000 + 116444736000000000
end
#
- # constructors
+ # constructor
#
private_class_method :new
+ #
+ # --- 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[http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp].
+ # If block is given, the key is closed automatically.
def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
subkey = subkey.chomp('\\')
newkey = API.OpenKey(hkey.hkey, subkey, opt, desired)
@@ -546,6 +395,19 @@ module Win32
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.
+ #
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)
@@ -576,19 +438,37 @@ module Win32
@hkeyfinal = [ hkey ]
ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal)
end
- attr_reader :hkey, :parent, :keyname, :disposition
+
+ # Returns key handle value.
+ attr_reader :hkey
+ # Win32::Registry object of parent key, or nil if predefeined key.
+ attr_reader :parent
+ # Same as subkey value of Registry.open or
+ # Registry.create method.
+ attr_reader :keyname
+ # Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY).
+ attr_reader :disposition
#
- # attributes
+ # 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
#
def created?
@disposition == REG_CREATED_NEW_KEY
end
+ #
+ # Returns if key is not closed.
+ #
def open?
!@hkey.nil?
end
+ #
+ # Full path of key such as 'HKEY_CURRENT_USER\SOFTWARE\foo\bar'.
+ #
def name
parent = self
name = @keyname
@@ -603,23 +483,31 @@ module Win32
end
#
- # marshalling
+ # marshalling is not allowed
#
def _dump(depth)
raise TypeError, "can't dump Win32::Registry"
end
#
- # open/close
+ # Same as Win32::Registry.open (self, subkey, desired, opt)
#
def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk)
self.class.open(self, subkey, desired, opt, &blk)
end
+ #
+ # Same as Win32::Registry.create (self, subkey, desired, opt)
+ #
def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)
self.class.create(self, subkey, desired, opt, &blk)
end
+ #
+ # Close key.
+ #
+ # After close, most method raise an error.
+ #
def close
API.CloseKey(@hkey)
@hkey = @parent = @keyname = nil
@@ -627,7 +515,7 @@ module Win32
end
#
- # iterator
+ # Enumerate values.
#
def each_value
index = 0
@@ -649,6 +537,13 @@ module Win32
end
alias each each_value
+ #
+ # Enumerate subkeys.
+ #
+ # subkey is String which contains name of subkey.
+ # wtime is last write time as FILETIME (64-bit integer).
+ # (see Registry.wtime2time)
+ #
def each_key
index = 0
while true
@@ -663,15 +558,31 @@ module Win32
index
end
+ #
+ # return keys as an array
+ #
def keys
keys_ary = []
each_key { |key,| keys_ary << key }
keys_ary
end
- #
- # reader
- #
+ # 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.
def read(name, *rtype)
type, data = API.QueryValue(@hkey, name)
unless rtype.empty? or rtype.include?(type)
@@ -695,6 +606,17 @@ module Win32
end
end
+ #
+ # 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.
+ #
def [](name, *rtype)
type, data = read(name, *rtype)
case type
@@ -707,10 +629,20 @@ module Win32
end
end
+ # 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.
def read_s(name)
read(name, REG_SZ)[1]
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.
+ #
def read_s_expand(name)
type, data = read(name, REG_SZ, REG_EXPAND_SZ)
if type == REG_EXPAND_SZ
@@ -720,16 +652,33 @@ module Win32
end
end
+ #
+ # 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.
+ #
def read_i(name)
read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1]
end
+ #
+ # 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.
+ #
def read_bin(name)
read(name, REG_BINARY)[1]
end
#
- # writer
+ # 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.
#
def write(name, type, data)
case type
@@ -751,6 +700,18 @@ module Win32
API.SetValue(@hkey, name, type, data, data.length)
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
+ #
def []=(name, rtype, value = nil)
if value
write name, rtype, value
@@ -769,26 +730,51 @@ module Win32
value
end
+ #
+ # 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).
+ #
def write_s(name, value)
write name, REG_SZ, value.to_s
end
+ #
+ # 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).
+ #
def write_i(name, value)
write name, REG_DWORD, value.to_i
end
+ #
+ # 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).
+ #
def write_bin(name, value)
write name, REG_BINARY, value.to_s
end
#
- # delete
+ # Delete a registry value named name.
+ # We can not delete the `default' value.
#
def delete_value(name)
API.DeleteValue(@hkey, name)
end
alias delete delete_value
+ #
+ # 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.
+ #
def delete_key(name, recursive = false)
if recursive
open(name, KEY_ALL_ACCESS) do |reg|
@@ -812,18 +798,38 @@ module Win32
end
#
- # flush
+ # Write all the attributes into the registry file.
#
def flush
API.FlushKey @hkey
end
#
- # key information
+ # 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[http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp] Win32 API.
#
def info
API.QueryInfoKey(@hkey)
end
+
+ #
+ # Returns an item of key information.
+ #
%w[
num_keys max_key_length
num_values max_value_name_length max_value_length