=head1 NAME

Win32::TieRegistry - Powerful and easy ways to manipulate a registry
[on Win32 for now].

=head1 SYNOPSIS

  use Win32::TieRegistry 0.20 ( UseOptionName=>UseOptionValue[,...] );

  $Registry->SomeMethodCall(arg1,...);

  $subKey= $Registry->{"Key\\SubKey\\"};
  $valueData= $Registry->{"Key\\SubKey\\\\ValueName"};
  $Registry->{"Key\\SubKey\\"}= { "NewSubKey" => {...} };
  $Registry->{"Key\\SubKey\\\\ValueName"}= "NewValueData";
  $Registry->{"\\ValueName"}= [ pack("fmt",$data), REG_DATATYPE ];

=head1 EXAMPLES

  use Win32::TieRegistry( Delimiter=>"#", ArrayValues=>0 );
  $pound= $Registry->Delimiter("/");
  $diskKey= $Registry->{"LMachine/System/Disk/"}
    or  die "Can't read LMachine/System/Disk key: $^E\n";
  $data= $key->{"/Information"}
    or  die "Can't read LMachine/System/Disk//Information value: $^E\n";
  $remoteKey= $Registry->{"//ServerA/LMachine/System/"}
    or  die "Can't read //ServerA/LMachine/System/ key: $^E\n";
  $remoteData= $remoteKey->{"Disk//Information"}
    or  die "Can't read ServerA's System/Disk//Information value: $^E\n";
  foreach $entry (  keys(%$diskKey)  ) {
      ...
  }
  foreach $subKey (  $diskKey->SubKeyNames  ) {
      ...
  }
  $diskKey->AllowSave( 1 );
  $diskKey->RegSaveKey( "C:/TEMP/DiskReg", [] );

=head1 DESCRIPTION

The I<Win32::TieRegistry> module lets you manipulate the Registry
via objects [as in "object oriented"] or via tied hashes.  But
you will probably mostly use a combination reference, that is, a
reference to a tied hash that has also been made an object so that
you can mix both access methods [as shown above].

If you did not get this module as part of libwin32, you might
want to get a recent version of libwin32 from CPAN which should
include this module and the C<Win32API::Registry> module that it
uses.

Skip to the L<SUMMARY> section if you just want to dive in and start
using the Registry from Perl.

Accessing and manipulating the registry is extremely simple using
I<Win32::TieRegistry>.  A single, simple expression can return
you almost any bit of information stored in the Registry.
I<Win32::TieRegistry> also gives you full access to the "raw"
underlying API calls so that you can do anything with the Registry
in Perl that you could do in C.  But the "simple" interface has
been carefully designed to handle almost all operations itself
without imposing arbitrary limits while providing sensible
defaults so you can list only the parameters you care about.

But first, an overview of the Registry itself.

=head2 The Registry

The Registry is a forest:  a collection of several tree structures.
The root of each tree is a key.  These root keys are identified by
predefined constants whose names start with "HKEY_".  Although all
keys have a few attributes associated with each [a class, a time
stamp, and security information], the most important aspect of keys
is that each can contain subkeys and can contain values.

Each subkey has a name:  a string which cannot be blank and cannot
contain the delimiter character [backslash: C<'\\'>] nor nul
[C<'\0'>].  Each subkey is also a key and so can contain subkeys
and values [and has a class, time stamp, and security information].

Each value has a name:  a string which E<can> be blank and E<can>
contain the delimiter character [backslash: C<'\\'>] and any
character except for null, C<'\0'>.  Each value also has data
associated with it.  Each value's data is a contiguous chunk of
bytes, which is exactly what a Perl string value is so Perl
strings will usually be used to represent value data.

Each value also has a data type which says how to interpret the
value data.  The primary data types are:

=over

=item REG_SZ

A null-terminated string.

=item REG_EXPAND_SZ

A null-terminated string which contains substrings consisting of a
percent sign [C<'%'>], an environment variable name, then a percent
sign, that should be replaced with the value associate with that
environment variable.  The system does I<not> automatically do this
substitution.

=item REG_BINARY

Some arbitrary binary value.  You can think of these as being
"packed" into a string.

If your system has the L<SetDualVar> module installed,
the C<DualBinVals()> option wasn't turned off, and you
fetch a C<REG_BINARY> value of 4 bytes or fewer, then
you can use the returned value in a numeric context to
get at the "unpacked" numeric value.  See C<GetValue()>
for more information.

=item REG_MULTI_SZ

Several null-terminated strings concatenated together with an
extra trailing C<'\0'> at the end of the list.  Note that the list
can include empty strings so use the value's length to determine
the end of the list, not the first occurrence of C<'\0\0'>.
It is best to set the C<SplitMultis()> option so I<Win32::TieRegistry>
will split these values into an array of strings for you.

=item REG_DWORD

A long [4-byte] integer value.  These values are expected either
packed into a 4-character string or as a hex string of E<more than>
4 characters [but I<not> as a numeric value, unfortunately, as there is
no sure way to tell a numeric value from a packed 4-byte string that
just happens to be a string containing a valid numeric value].

How such values are returned depends on the C<DualBinVals()> and
C<DWordsToHex()> options.  See C<GetValue()> for details.

=back

In the underlying Registry calls, most places which take a
subkey name also allow you to pass in a subkey "path" -- a
string of several subkey names separated by the delimiter
character, backslash [C<'\\'>].  For example, doing
C<RegOpenKeyEx(HKEY_LOCAL_MACHINE,"SYSTEM\\DISK",...)>
is much like opening the C<"SYSTEM"> subkey of C<HKEY_LOCAL_MACHINE>,
then opening its "DISK" subkey, then closing the C<"SYSTEM"> subkey.

All of the I<Win32::TieRegistry> features allow you to use your
own delimiter in place of the system's delimiter, [C<'\\'>].  In
most of our examples we will use a forward slash [C<'/'>] as our
delimiter as it is easier to read and less error prone to use when
writing Perl code since you have to type two backslashes for each
backslash you want in a string.  Note that this is true even when
using single quotes -- C<'\\HostName\LMachine\'> is an invalid
string and must be written as C<'\\\\HostName\\LMachine\\'>.

You can also connect to the registry of other computers on your
network.  This will be discussed more later.

Although the Registry does not have a single root key, the
I<Win32::TieRegistry> module creates a virtual root key for you
which has all of the I<HKEY_*> keys as subkeys.

=head2 Tied Hashes Documentation

Before you can use a tied hash, you must create one.  One way to
do that is via:

    use Win32::TieRegistry ( TiedHash => '%RegHash' );

which exports a C<%RegHash> variable into your package and ties it
to the virtual root key of the Registry.  An alternate method is:

    my %RegHash;
    use Win32::TieRegistry ( TiedHash => \%RegHash );

There are also several ways you can tie a hash variable to any
other key of the Registry, which are discussed later.

Note that you will most likely use C<$Registry> instead of using
a tied hash.  C<$Registry> is a reference to a hash that has
been tied to the virtual root of your computer's Registry [as if,
C<$Registry= \%RegHash>].  So you would use C<$Registry-E<gt>{Key}>
rather than C<$RegHash{Key}> and use C<keys %{$Registry}> rather
than C<keys %RegHash>, for example.

For each hash which has been tied to a Registry key, the Perl
C<keys> function will return a list containing the name of each
of the key's subkeys with a delimiter character appended to it and
containing the name of each of the key's values with a delimiter
prepended to it.  For example:

    keys( %{ $Registry->{"HKEY_CLASSES_ROOT\\batfile\\"} } )

might yield the following list value:

    ( "DefaultIcon\\",  # The subkey named "DefaultIcon"
      "shell\\",        # The subkey named "shell"
      "shellex\\",      # The subkey named "shellex"
      "\\",             # The default value [named ""]
      "\\EditFlags" )   # The value named "EditFlags"

For the virtual root key, short-hand subkey names are used as
shown below.  You can use the short-hand name, the regular
I<HKEY_*> name, or any numeric value to access these keys, but
the short-hand names are all that will be returned by the C<keys>
function.

=over

=item "Classes" for HKEY_CLASSES_ROOT

Contains mappings between file name extensions and the uses
for such files along with configuration information for COM
[MicroSoft's Common Object Model] objects.  Usually a link to
the C<"SOFTWARE\\Classes"> subkey of the C<HKEY_LOCAL_MACHINE>
key.

=item "CUser" for HKEY_CURRENT_USER

Contains information specific to the currently logged-in user.
Mostly software configuration information.  Usually a link to
a subkey of the C<HKEY_USERS> key.

=item "LMachine" for HKEY_LOCAL_MACHINE

Contains all manner of information about the computer.

=item "Users" for HKEY_USERS

Contains one subkey, C<".DEFAULT">, which gets copied to a new
subkey whenever a new user is added.  Also contains a subkey for
each user of the system, though only those for active users
[usually only one] are loaded at any given time.

=item "PerfData" for HKEY_PERFORMANCE_DATA

Used to access data about system performance.  Access via this key
is "special" and all but the most carefully constructed calls will
fail, usually with C<ERROR_INSUFFICIENT_BUFFER>.  For example, you
can't enumerate key names without also enumerating values which
require huge buffers but the exact buffer size required cannot be
determined beforehand because C<RegQueryInfoKey()> E<always> fails
with C<ERROR_INSUFFICIENT_BUFFER> for C<HKEY_PERFORMANCE_DATA> no
matter how it is called.  So it is currently not very useful to
tie a hash to this key.  You can use it to create an object to use
for making carefully constructed calls to the underlying Reg*()
routines.

=item "CConfig" for HKEY_CURRENT_CONFIG

Contains minimal information about the computer's current
configuration that is required very early in the boot process.
For example, setting for the display adapter such as screen
resolution and refresh rate are found in here.

=item "DynData" for HKEY_DYN_DATA

Dynamic data.  We have found no documentation for this key.

=back

A tied hash is much like a regular hash variable in Perl -- you give
it a key string inside braces, [C<{> and C<}>], and it gives you
back a value [or lets you set a value].  For I<Win32::TieRegistry>
hashes, there are two types of values that will be returned.

=over

=item SubKeys

If you give it a string which represents a subkey, then it will
give you back a reference to a hash which has been tied to that
subkey.  It can't return the hash itself, so it returns a
reference to it.  It also blesses that reference so that it is
also an object so you can use it to call method functions.

=item Values

If you give it a string which is a value name, then it will give
you back a string which is the data for that value.  Alternately,
you can request that it give you both the data value string and
the data value type [we discuss how to request this later].  In
this case, it would return a reference to an array where the value
data string is element C<[0]> and the value data type is element
C<[1]>.

=back

The key string which you use in the tied hash must be interpreted
to determine whether it is a value name or a key name or a path
that combines several of these or even other things.  There are
two simple rules that make this interpretation easy and
unambiguous:

    Put a delimiter after each key name.
    Put a delimiter in front of each value name.

Exactly how the key string will be intepreted is governed by the
following cases, in the order listed.  These cases are designed
to "do what you mean".  Most of the time you won't have to think
about them, especially if you follow the two simple rules above.
After the list of cases we give several examples which should be
clear enough so feel free to skip to them unless you are worried
about the details.

=over

=item Remote machines

If the hash is tied to the virtual root of the registry [or the
virtual root of a remote machine's registry], then we treat hash
key strings which start with the delimiter character specially.

If the hash key string starts with two delimiters in a row, then
those should be immediately followed by the name of a remote
machine whose registry we wish to connect to.  That can be
followed by a delimiter and more subkey names, etc.  If the
machine name is not following by anything, then a virtual root
for the remote machine's registry is created, a hash is tied to
it, and a reference to that hash it is returned.

=item Hash key string starts with the delimiter

If the hash is tied to a virtual root key, then the leading
delimiter is ignored.  It should be followed by a valid Registry
root key name [either a short-hand name like C<"LMachine">, an
I<HKEY_*> value, or a numeric value].   This alternate notation is
allowed in order to be more consistant with the C<Open()> method
function.

For all other Registry keys, the leading delimiter indicates
that the rest of the string is a value name.  The leading
delimiter is stripped and the rest of the string [which can
be empty and can contain more delimiters] is used as a value
name with no further parsing.

=item Exact match with direct subkey name followed by delimiter

If you have already called the Perl C<keys> function on the tied
hash [or have already called C<MemberNames> on the object] and the
hash key string exactly matches one of the strings returned, then
no further parsing is done.  In other words, if the key string
exactly matches the name of a direct subkey with a delimiter
appended, then a reference to a hash tied to that subkey is
returned [but only if C<keys> or C<MemberNames> has already
been called for that tied hash].

This is only important if you have selected a delimiter other than
the system default delimiter and one of the subkey names contains
the delimiter you have chosen.  This rule allows you to deal with
subkeys which contain your chosen delimiter in their name as long
as you only traverse subkeys one level at a time and always
enumerate the list of members before doing so.

The main advantage of this is that Perl code which recursively
traverses a hash will work on hashes tied to Registry keys even if
a non-default delimiter has been selected.

=item Hash key string contains two delimiters in a row

If the hash key string contains two [or more] delimiters in a row,
then the string is split between the first pair of delimiters.
The first part is interpreted as a subkey name or a path of subkey
names separated by delimiters and with a trailing delimiter.  The
second part is interpreted as a value name with one leading
delimiter [any extra delimiters are considered part of the value
name].

=item Hash key string ends with a delimiter

If the key string ends with a delimiter, then it is treated
as a subkey name or path of subkey names separated by delimiters.

=item Hash key string contains a delimiter

If the key string contains a delimiter, then it is split after
the last delimiter.  The first part is treated as a subkey name or
path of subkey names separated by delimiters.  The second part
is ambiguous and is treated as outlined in the next item.

=item Hash key string contains no delimiters

If the hash key string contains no delimiters, then it is ambiguous.

If you are reading from the hash [fetching], then we first use the
key string as a value name.  If there is a value with a matching
name in the Registry key which the hash is tied to, then the value
data string [and possibly the value data type] is returned.
Otherwise, we retry by using the hash key string as a subkey name.
If there is a subkey with a matching name, then we return a
reference to a hash tied to that subkey.  Otherwise we return
C<undef>.

If you are writing to the hash [storing], then we use the key
string as a subkey name only if the value you are storing is a
reference to a hash value.  Otherwise we use the key string as
a value name.

=back

=head3 Examples

Here are some examples showing different ways of accessing Registry
information using references to tied hashes:

=over

=item Canonical value fetch

    $tip18= $Registry->{"HKEY_LOCAL_MACHINE\\Software\\Microsoft\\"
               . 'Windows\\CurrentVersion\\Explorer\\Tips\\\\18'};

Should return the text of important tip number 18.  Note that two
backslashes, C<"\\">, are req