Ruby

=begin

= Win32 Registry I/F

=== 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'})).

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

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.

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

=end

require 'dl/import'

module Win32

# Fake class for Registry#open, Registry#create

#

# utility functions

# constructors

attr_reader :hkey, :parent, :keyname, :disposition

# attributes

# marshalling

# open/close

# iterator

# reader

#

# writer

# delete

# flush

# key information