Win32::Registry

This module provides access to the Windows Registry, the database that stores information about all parts of your system and software. Many operating-system and application behaviors are controlled by Registry data. The Win32::Registry module gives you a way to access and update registry information with Perl.

WARNING: Always be careful when making changes to the registry. If vital system information gets changed by mistake, your system could become inoperable. Always make certain you have a backup of your registry before you start making modifications.

The Registry module automatically creates objects for the top-level registry trees. These objects are created in the main:: namespace, and each key that you open or create is accessed via one of these root objects. The top-level objects are:

$HKEY_CLASSES_ROOT $HKEY_CURRENT_USER $HKEY_LOCAL_MACHINE $HKEY_USERS $HKEY_PERFORMANCE_DATA $HKEY_CURRENT_CONFIG $HKEY_DYN_DATA

If you are outside of the main (default) namespace, you should package declare the keys, e.g., $main::HKEY_USERS.

The Open method creates new key objects for subtrees or subkeys under another open key object. Initially, a new key is opened from one of the main key objects. For example:

use Win32::Registry; $p = "SOFTWARE\Microsoft\Windows\CurrentVersion"; $HKEY_LOCAL_MACHINE->Open($p, $CurrVer) || die "Open $!";

This example creates a key object $CurrVer for the CurrentVersion key for Windows. This key contains several values for the current version of the operating system. With the new key open, you can read or change the values it contains (every key has at least one unnamed, default value), or open and create subkeys. The Open method can create key objects only for existing keys.

Registry values are represented in Win32::Registry functions by three elements: the name of the value, the data type of the value, and the value itself. There are several different data types for the values. Win32::Registry defines the following constants for these types:

• REG_SZ
• String data
• REG_DWORD
• Unsigned four-byte integer
• REG_MULTI_SZ
• Multiple strings delimited with NULL
• REG_EXPAND_SZ
• Strings that expand (e.g., based on environment variables)
• REG_BINARY
• Binary data (no particular format is assumed)

Win32::Registry Methods

The following methods can be used on key objects, either on the preopened main keys or subkeys that you have already opened.

$key->Create($newkey, name)

Creates a new key identified by name and saves it as the object reference named by $newkey. If the key already exists, this function simply opens the key. New keys can only be created one level below the key on which Create is used.

$key->DeleteKey(subkey) 

Deletes a subkey of the current key. This function will delete all values in the subkey and the subkey itself. A key cannot be deleted if it contains any subkeys.

$key->DeleteValue(name) 

Deletes a value identified by name from the current key.

$key->GetKeys($listref) 

Returns the names of the subkeys of the current key to the list referenced by listref.

$key->GetValues($hashref) 

Returns the values contained in the current key to the hash referenced by hashref. Each registry value name is a hash key, while the hash value is a reference to a three-element list containing the name of the value, the data type, and the value.

$key->Load(subkey, filename) 

Loads a registry file to the named subkey from file filename.

$parent->Open(keyname, $key) 

Opens a registry key named in keyname and saves it as the object reference named by $key. keyname is the name of a key relative to the object on which Open is used ($parent).

$key->QueryKey($class, $subs, $vals) 

Retrieves information about the current key and returns it to the named scalar variables. The key class is saved in the class variable (it will be the null string "" on Win95 since it doesn't use key classes). The number of subkeys is saved in the $subs variable, and the number of values in the current key is saved in $vals.

$key->QueryValue(name, $var) 

Returns the value of the registry value specified by name and saves it in the scalar variable $var.

$key->Save(filename) 

Saves the registry tree root and the current key to a file, filename.

$key->SetValue(subkey, type, value)

Sets the default (unnamed) value for the specified subkey of the key object on which SetValue is used. The arguments are:

• subkey
• Name of the subkey
• type
• One of the type constants (listed above) describing the value
• value
• Value of the key

$key->SetValueEx(name, res, type, value) 

Sets a value specified by name in the current key (or creates the value if it doesn't already exist). The arguments are:

• res
• A reserved argument for future use (use as a placeholder)
• type
• The data type constant (listed above) describing the value
• value
• The value of the key