The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
libwin32-0.13
River stage zero No dependents
1 ++
/ Win32API::Registry

NAME

Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H

SYNOPSIS

  use Win32API::Registry 0.13 qw( :ALL );

  RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key );
    or  die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: $^E\n";
  RegQueryValueEx( $key, "Information", [], $type, $data, [] );
    or  die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: $^E\n";
  [...]
  RegCloseKey( $key )
    and  die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: $^E\n";

DESCRIPTION

This provides fairly low-level access to the Win32 System API calls dealing with the Registry (mostly from WINREG.H). This is mostly intended to be used by other modules such as Win32::TieRegistry [which provides an extremely Perl-friendly method for using the Registry].

For a description of the logical structure of the Registry, see the documentation for the Win32::TieRegistry module.

To pass in NULL as the pointer to an optional buffer, pass in an empty list reference, [].

Beyond raw access to the API calls and related constants, this module handles smart buffer allocation and translation of return codes.

All calls return a true value for success and a false value for failure. After any failure, $^E should automatically be set to indicate the reason. If you have a version of Perl that does not yet connect $^E to GetLastError() under Win32, then you can use $iError= Win32::GetLastError() to get the numeric error code and pass that to Win32::FormatMessage($iError) to to get the descriptive string, or just Win32::FormatMessage(Win32::GetLastError()).

Note that $! is not set by these routines except by Win32API::Registry::constant() when a constant is not defined.

The Win32API:: heirarchy

This and the other Win32API:: modules are meant to expose the nearly raw API calls so they can be used from Perl code in any way they might be used from C code. This provides the following advantages:

Many modules can be written by people that don't have a C compiler.
Encourages more module code to be written in Perl [not C].

Perl code is often much easier to inspect, debug, customize, and enhance than XS code.

Allows those already familiar with the Win32 API to get off to a quick start.
Provides an interactive tool [Perl] for exploring even obscure details of the Win32 API.
Ensures that native Win32 data structures can be used.

This allows maximum efficiency. It also allows data from one module [for example, time or security information from the Win32API::Registry or Win32API::File modules] to be used with other modules [for example, Win32API::Time and Win32API::Security].

Provides a single version of the XS interface to each API call where improvements can be collected.

Buffer sizes

For each argument that specifies a buffer size, a value of 0 can be passed. For arguments that are pointers to buffer sizes, you can also pass in NULL by specifying an empty list reference, []. Both of these cases will ensure that the variable has E<some> buffer space allocated to it and pass in that buffer's allocated size. Many of the calls indicate, via ERROR_MORE_DATA, that the buffer size was not sufficient and the Registry.xs code will automatically enlarge the buffer to the required size and repeat the call.

Numeric buffer sizes are used as minimum initial sizes for the buffers. The larger of this size and the size of space already allocated to the scalar will be passed to the underlying routine. If that size was insufficient, and the underlying call provides an easy method for determining the needed buffer size, then the buffer will be enlarged and the call repeated as above.

The underlying calls define buffer size arguments as unsigned, so negative buffer sizes are treated as very large positive buffer sizes which usually cause malloc() to fail.

To force the Registry.xs code to pass in a specific value for a buffer size, preceed the size with "=". Buffer sizes that are passed in as strings starting with an equal sign will have the equal sign stripped and the remainder of the string interpretted as a number [via C's strtoul() using only base 10] which will be passed to the underlying routine [even if the allocated buffer is actually larger]. The Registry.xs code will enlarge the buffer to the specified size, if needed, but will not enlarge the buffer based on the underlying routine requesting more space.

Some Reg*() calls may not currently set the buffer size when they return ERROR_MORE_DATA. But some that are not documented as doing so, currently do so anyway. So the code assumes that any routine E<might> do this and resizes any buffers and repeats the call. We hope that eventually all routines will provide this feature.

When you use [] for a buffer size, you can still find the length of the data returned by using length($buffer). Note that this length will be in bytes while a few of the buffer sizes would have been in units of wide characters.

Note that the RegQueryValueEx*() and RegEnumValue*() calls will trim the trailing '\0' [if present] from the returned data values of type REG_SZ or REG_EXPAND_SZ but only if the value data length argument is omitted [or specified as []].

The RegSetValueEx*() calls will add a trailing '\0' [if missing] to the supplied data values of type REG_SZ and REG_EXPAND_SZ but only if the value data length argument is omitted [or specified as 0].

Exports

Nothing is exported by default. The following tags can be used to have sets of symbols exported.

[Note that much of the following documentation refers to the behavior of the underlying API calls which may vary in current and future versions of the Win32 API without any changes to this module. Therefore you should check the Win32 API documentation directly when needed.]

:Func

The basic function names:

AllowPriv( $sPrivName, $bEnable )

Not a Win32 API call. Enables or disables a specific privilege for the current process. Returns a true value if successful and a false value [and sets $^E] on failure. This routine does not provide a way to tell if a privilege is current enabled.

$sPrivname is a Win32 privilege name [see the SE_*_NAME macros of winnt.h]. For example, "SeBackupPrivilege" [a.k.a. SE_BACKUP_NAME] controls whether you can use RegSaveKey() and "SeRestorePrivilege" [a.k.a. SE_RESTORE_NAME] controls whether you can use RegLoadKey().

If $bEnable is true, then AllowPriv() tries to enable the privilege. Otherwise it tries to disable the privilege.

AbortSystemShutdown( $sComputerName )

Tries to abort a remote shutdown request previously made via InitiateSystemShutdown().

InitiateSystemShutdown( $sComputer, $sMessage, $iTimeoutSecs, $bForce, $bReboot )

Requests that a [remote] computer be shutdown or rebooted.

$sComputer is the name [or address] of the computer to be shutdown or rebooted. You can use [] [for NULL] or "" to indicate the local computer.

$sMessage is the message to be displayed in a pop-up window on the desktop of the computer to be shutdown or rebooted until the timeout expires or the shutdown is aborted via AbortSystemShutdown(). With $iTimeoutSecs == 0, the message will never be visible.

$iTimeoutSecs is the number of seconds to wait before starting the shutdown.

If $bForce is false, then any applications running on the remote computer get a chance to prompt the remote user whether they want to save changes. Also, for any applications that do not exit quickly enough, the operating system will prompt the user whether they wish to wait longer for the application to exit or force it to exit now. At any of these prompts the user can press CANCEL to abort the shutdown but if no applications have unsaved data, they will likely all exit quickly and the shutdown will progress with the remote user having no option to cancel the shutdown.

If $bForce is true, all applications are told to exit immediately and so will not prompt the user even if there is unsaved data. Any applications that take too long to exit will be forcibly killed after a short time. The only way to abort the shutdown is to call AbortSystemShutdown() before the timeout expires and there is no way to abort the shutdown once it has begun.

If $bReboot is true, the computer will automatically reboot once the shutdown is complete. If $bReboot is false, then when the shutdown is complete the computer will halt at a screen indicating that the shutdown is complete and offering a way for the user to start to boot the computer.

You must have the "SeRemoteShutdownPrivilege" privilege on the remote computer for this call to succeed. If shutting down the local computer, then the calling process must have the "SeShutdownPrivilege" privilege and have it enabled.

RegCloseKey( $hKey )

Closes the handle to a Registry key returned by RegOpenKeyEx(), RegConnectRegistry(), RegCreateKeyEx(), or a few other routines.

RegConnectRegistry( $sComputer, $hKey, $phKey )

Connects to one of the root Registry keys of a remote computer.

$sComputer is the name [or address] of a remote computer you whose Registry you wish to access.

$hKey must be either HKEY_LOCAL_MACHINE or HKEY_USERS and specifies which root Registry key on the remote computer you wish to have access to.

$phKey will be set to the handle to be used to access the remote Registry key.

RegCreateKey( $hKey, $sSubKey, $phKey )

This routine is meant only for compatibility with Windows version 3.1. Use RegCreateKeyEx() instead.

RegCreateKeyEx( $hKey, $sSubKey, $iZero, $sClass, $iOpts, $iAccess, $pSecAttr, $phKey, $piDisp )

Creates a new Registry subkey.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of the new subkey to be created.

$iZero is reserved for future use and should always be specified as 0.

$sClass is a string to be used as the class for the new subkey. We are not aware of any current use for Registry key class information so the empty string, "", should usually be used here.

$iOpts is a numeric value containing bits that control options used while creating the new subkey. REG_OPTION_NON_VOLATILE is the default. REG_OPTION_VOLATILE [which is ignored on Windows 95] means the data stored under this key is not kept in a file and will not be preserved when the system reboots. REG_OPTION_BACKUP_RESTORE [also ignored on Windows 95] means ignore the $iAccess parameter and try to open the new key with the access required to backup or restore the key.

$iAccess is a numeric mask of bits specifying what type of access is desired when opening the new subkey. See RegOpenKeyEx().

$pSecAttr is a SECURITY_ATTRIBUTES structure packed into a Perl string which controls whether the returned handle can be inherited by child processes. Normally you would pass [] for this argument to have NULL passed to the underlying API indicating that the handle cannot be inherited. If not under Windows95, then $pSecAttr also allows you to specify SECURITY_DESCRIPTOR that controls which users will have what type of access to the new key -- otherwise the new key inherits its security from its parent key.

$phKey will be set to the handle to be used to access the new subkey.

$piDisp will be set to either REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY to indicate for which reason the call succeeded. Can be specified as [] if you don't care.

If $phKey and $piDisp start out is integers, then they will probably remain unchanged if the call fails.

RegDeleteKey( $hKey, $sSubKey )

Deletes a subkey of an open Registry key provided that the subkey contains no subkeys of its own [but the subkey may contain values].

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of the subkey to be deleted.

RegDeleteValue( $hKey, $sValueName )

Deletes a values from an open Registry key provided.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sValueKey is the name of the value to be deleted.

RegEnumKey( $hKey, $iIndex, $sName, $lNameSize )

This routine is meant only for compatibility with Windows version 3.1. Use RegEnumKeyEx() instead.

RegEnumKeyEx( $hKey, $iIndex, $sName, $plName, $pNull, $sClass, $plClass, $pftLastWrite )

Lets you enumerate the names of all of the subkeys directly under an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iIndex is the sequence number of the immediate subkey that you want information on. Start with this value as 0 then repeat the call incrementing this value each time until the call fails with ERROR_NO_MORE_ITEMS.

$sName will be set to the name of the subkey. Can be [] if you don't care about the name.

$plName initially specifies the [minimum] buffer size to be allocated for $sName. Will be set to the length of the subkey name if the requested subkey exists even if $sName isn't successfully set to the subkey name. See "Buffer sizes" for more information.

$pNull is reserved for future used and should be passed as [].

$sClass will be set to the class name for the subkey. Can be [] if you don't care about the class.

$plClass initially specifies the [minimum] buffer size to be allocated for $sClass and will be set to the length of the subkey class name if the requested subkey exists. See "Buffer sizes" for more information.

$pftLastWrite will be set to a FILETIME structure packed into a Perl string and indicating when the subkey was last changed. Can be [].

You may omit both $plName and $plClass to get the same effect as passing in [] for each of them.

RegEnumValue( $hKey, $iIndex, $sValName, $plValName, $pNull, $piType, $pValData, $plValData )

Lets you enumerate the names of all of the values contained in an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iIndex is the sequence number of the value that you want information on. Start with this value as 0 then repeat the call incrementing this value each time until the call fails with ERROR_NO_MORE_ITEMS.

$sValName will be set to the name of the value. Can be [] if you don't care about the name.

$plValName initially specifies the [minimum] buffer size to be allocated for $sValName. Will be set to the length of the value name if the requested value exists even if $sValName isn't successfully set to the value name. See "Buffer sizes" for more information.

$pNull is reserved for future used and should be passed as [].

$piType will be set to the type of data stored in the value data. If the call succeeds, it will be set to a REG_* value unless passed in as [].

$pValData will be set to the data [packed into a Perl string] that is stored in the requested value. Can be [] if you don't care about the value data.

$plValData initially specifies the [minimum] buffer size to be allocated for $sValData and will be set to the length of the value data if the requested value exists. See "Buffer sizes" for more information.

You may omit both $plValName and $plValData to get the same effect as passing in [] for each of them.

RegFlushKey( $hKey )

Forces that data stored under an open Registry key to be flushed to the disk file where the data is preserved between reboots. Forced flushing is not guaranteed to be efficient so this routine should almost never be called.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

RegGetKeySecurity( $hKey, $iSecInfo, $pSecDesc, $plSecDesc )

Retrieves one of the SECURITY_DESCRIPTOR structures describing part of the security for an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iSecInfo is a numeric SECURITY_INFORMATION value that specifies which SECURITY_DESCRIPTOR structure to retrieve. Should be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION.

$pSecDesc will be set to the requested SECURITY_DESCRIPTOR structure [packed into a Perl string].

$plSecDesc initially specifies the [minimum] buffer size to be allocated for $sSecDesc and will be set to the length of the security descriptor. See "Buffer sizes" for more information. You may omit this parameter to get the same effect as passing in [] for it.

RegLoadKey( $hKey, $sSubKey, $sFileName )

Loads a hive file. That is, it creates a new subkey in the Registry and associates that subkey with a disk file that contains a Registry hive so that the new subkey can be used to access the keys and values stored in that hive. Hives are usually created via RegSaveKey().

$hKey is the handle to a Registry key that can have hives loaded to it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the new subkey to created and associated with the hive file.

$sFileName is the name of the hive file to be loaded. This file name is interpretted relative to the %SystemRoot%/System32/config directory on the computer where the $hKey key resides.

Loading of hive files located on network shares may fail or corrupt the hive and so should not be attempted.

RegNotifyChangeKeyValue( $hKey, $bWatchSubtree, $iNotifyFilter, $hEvent, $bAsync )

Arranges for your process to be notified when part of the Registry is changed.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call] for which you wish to be notified when any changes are made to it.

If $bWatchSubtree is true, then changes to any subkey or descendant of $hKey are also reported.

$iNotifyFilter controllers what types of changes are reported. It is a numeric value containing one or more of the following bit masks:

REG_NOTIFY_CHANGE_NAME

Notify if a subkey is added or deleted to a monitored key.

REG_NOTIFY_CHANGE_LAST_SET

Notify if a value in a monitored key is added, deleted, or modified.

REG_NOTIFY_CHANGE_SECURITY

Notify a security descriptor of a monitored key is changed.

REG_NOTIFY_CHANGE_ATTRIBUTES

Notify if any attributes of a monitored key are changed [class name or security descriptors].

$hEvent is ignored unless $bAsync is true. Otherwise, $hEvent is a handle to a Win32 event that will be signaled when changes are to be reported.

If $bAsync is true, then RegNotifyChangeKeyValue() returns immediately and uses $hEvent to notify your process of changes. If $bAsync is false, then RegNotifyChangeKeyValue() does not return until there is a change to be notified of.

This routine does not work with Registry keys on remote computers.

RegOpenKey( $hKey, $sSubKey, $phKey )

This routine is meant only for compatibility with Windows version 3.1. Use RegOpenKeyEx() instead.

RegOpenKeyEx( $hKey, $sSubKey, $iOptions, $iAccess, $phKey )

Opens an existing Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of an existing subkey to be opened. Can be "" or [] to open an additional handle to the key specified by $hKey.

$iOptions is a numeric value containing bits that control options used while open the subkey. There are currently no supported options so this parameters should be specified as 0.

$iAccess is a numeric mask of bits specifying what type of access is desired when opening the new subkey. Should be a combination of one or more of the following bit masks:

KEY_ALL_ACCESS
    KEY_READ | KEY_WRITE | KEY_CREATE_LINK
KEY_READ
    KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
KEY_WRITE
    KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
KEY_QUERY_VALUE
KEY_SET_VALUE
KEY_ENUMERATE_SUB_KEYS
KEY_CREATE_SUB_KEY
KEY_NOTIFY
KEY_EXECUTE

Same as KEY_READ.

Allows you to create a symbolic link like HKEY_CLASSES_ROOT and HKEY_CURRENT_USER if the method for doing so were documented.

$phKey will be set to the handle to be used to access the new subkey.

RegQueryInfoKey( $hKey, $sClass, $plClass, $pNull, $pcSubKeys, $plSubKey, $plSubClass, $pcValues, $plValName, $plValData, $plSecDesc, $pftTime )

Gets miscellaneous information about an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sClass will be set to the class name for the key. Can be [] if you don't care about the class.

$plClass initially specifies the [minimum] buffer size to be allocated for $sClass and will be set to the length of the key's class name. See "Buffer sizes" for more information. You may omit this parameter to get the same effect as passing in [] for it.

$pNull is reserved for future used and should be passed as [].

$pcSubKeys will be set to the count of the number of subkeys directly under this key. Can be [].

$plSubKey will be set to the length of the longest subkey name. Can be [].

$plSubClass will be set to the length of the longest class name used with an immediate subkey of this key. Can be [].

$pcValues will be set to the count of the number of values in this key. Can be [].

$plValName will be set to the length of the longest value name in this key. Can be [].

$plValData will be set to the length of the longest value data in this key. Can be [].

$plSecDesc will be set to the length of this key's [longest?] security descriptor.

$pftTime will be set to a FILETIME structure packed into a Perl string and indicating when this key was last changed. Can be [].

RegQueryMultipleValues( $hKey, $pValueEnts, $cValueEnts, $pBuffer, $plBuffer )

Allows you to use a single call to query several values from a single open Registry key to maximize efficiency.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$pValueEnts should contain a list of VALENT structures packed into a single Perl string. Each VALENT structure should have the ve_valuename entry pointing to a string containing the name of a value stored in this key. The remaining fields are set if the function succeeds.

$cValueEnts should contain the count of the number of VALENT structures contained in $pValueEnts.

$pBuffer will be set to the data from all of the requested values concatenated into a single Perl string.

$plBuffer initially specifies the [minimum] buffer size to be allocated for $sBuffer and will be set to the total length of the data to be written to $sBuffer. See "Buffer sizes" for more information. You may omit this parameter to get the same effect as passing in [] for it.

Here is sample code to populate $pValueEnts:

    $cValueEnts= @ValueNames;
    $pValueEnts= pack( " p x4 x4 x4 " x $cValueEnts, @ValueNames );

Here is sample code to retrieve the data type and data length returned in $pValueEnts:

    @Lengths= unpack( " x4 L x4 x4 " x $cValueEnts, $pValueEnts );
    @Types=   unpack( " x4 x4 x4 L " x $cValueEnts, $pValueEnts );

Given the above, and assuming you haven't modified $sBuffer since the call, you can also extract the value data strings from $sBuffer by using the pointers returned in $pValueEnts:

    @Data=    unpack(  join( "", map(" x4 x4 P$_ x4 ",@Lengths) ),
                $pValueEnts  );

Much better is to use the lengths and extract directly from $sBuffer using unpack() [or substr()]:

    @Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
RegQueryValue( $hKey, $sSubKey, $sValueData, $plValueData )

This routine is meant only for compatibility with Windows version 3.1. Use RegQueryValueEx() instead. This routine can only query unamed values (a.k.a. "default values").

RegQueryValueEx( $hKey, $sValueName, $pNull, $piType, $pValueData, $plValueData )

Lets you look up value data using the name of the value stored in an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sValueName is the name of the value whose data you wish to retrieve.

$pNull this parameter is reserved for future use and should be specified as [].

$piType will be set to indicate what type of data is stored in the named value. Will be set to a REG_* value if the function succeeds.

$pValueData will be set to the value data [packed into a Perl string] that is stored in the named value. Can be [] if you don't care about the value data.

$plValueData initially specifies the [minimum] buffer size to be allocated for $sValueData and will be set to the size [always in bytes] of the data to be written to $sValueData. See "Buffer sizes" for more information.

RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )

Lets you replace an entire hive when the system is next booted.

$hKey is the handle to a Registry key that has hives loaded in it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the subkey of $hKey whose hive you wish to have replaced on the next reboot.

$sNewFile is the name of a file that will replace the existing hive file when the system reboots.

$sOldFile is the file name to save the current hive file to when the system reboots.

RegRestoreKey( $hKey, $sFileName, $iFlags )

Reads in a hive file and copies its contents over an existing Registry tree.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sFileName is the name of the hive file to be read. For each value and subkey in this file, a value or subkey will be added or replaced in $hKey.

$iFlags is usally 0. It can also be REG_WHOLE_HIVE_VOLATILE which, rather than copying the hive over the existing key, replaces the existing key with a temporary, memory-only Registry key and then copies the hive contents into it. This option only works if $hKey is HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

RegSaveKey( $hKey, $sFileName, $pSecAttr )

Dumps any open Registry key and all of its subkeys and values into a new hive file.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sFileName is the name of the file that the Registry tree should be saved to. It is interpretted relative to the %SystemRoot%/System32/config directory on the computer where the $hKey key resides.

$pSecAttr contains a SECURITY_ATTRIBUTES structure that specifies the permissions to be set on the new file that is created. This can be [].

RegSetKeySecurity( $hKey, $iSecInfo, $pSecDesc )

Sets one of the SECURITY_DESCRIPTOR structures describing part of the security for an open Registry key.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iSecInfo is a numeric SECURITY_INFORMATION value that specifies which SECURITY_DESCRIPTOR structure to set. Should be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION.

$pSecDesc contains the new SECURITY_DESCRIPTOR structure packed into a Perl string.

RegSetValue( $hKey, $sSubKey, $iType, $sValueData, $lValueData )

This routine is meant only for compatibility with Windows version 3.1. Use RegSetValueEx() instead. This routine can only set unamed values (a.k.a. "default values").

RegSetValueEx( $hKey, $sValueName, $iZero, $iType, $pValueData, $lValueData )

Sets a value.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sValueName is the name of the value to be set.

$iZero is reserved for future use and should be specified as 0.

$iType is the type of data stored in $pValueData. It should be a REG_* value.

$pValueData is the value data packed into a Perl string.

$lValueData the length of the value data that is stored in $pValueData. You will usually omit this parameter or pass in 0 to have length($pValueData) used. In both of these cases, if $iType is REG_SZ or REG_EXPAND_SZ, RegSetValueEx() will append a trailing '\0' to the end of $pValueData [unless there is already one].

RegUnLoadKey( $hKey, $sSubKey )

Unloads a previously loaded hive file. That is, closes the hive file then deletes the subkey that was providing access to it.

$hKey is the handle to a Registry key that has hives loaded in it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the subkey whose hive you wish to have unloaded.

:FuncA

The ASCI-specific function names.

Each of these is identical to version listed above without the trailing "A":

        AbortSystemShutdownA    InitiateSystemShutdownA
        RegConnectRegistryA     RegCreateKeyA           RegCreateKeyExA
        RegDeleteKeyA           RegDeleteValueA         RegEnumKeyA
        RegEnumKeyExA           RegEnumValueA           RegLoadKeyA
        RegOpenKeyA             RegOpenKeyExA           RegQueryInfoKeyA
        RegQueryMultipleValuesA RegQueryValueA          RegQueryValueExA
        RegReplaceKeyA          RegRestoreKeyA          RegSaveKeyA
        RegSetValueA            RegSetValueExA          RegUnLoadKeyA
:FuncW

The UNICODE-specific function names. These are the same as the version listed above without the trailing "W" except that string parameters are UNICODE strings rather than ASCII strings, as indicated.

AbortSystemShutdownW( $sComputerName )

$sComputerName is UNICODE.

InitiateSystemShutdownW( $sComputer, $sMessage, $iTimeoutSecs, $bForce, $bReboot )

$sComputer is UNICODE.

RegConnectRegistryW( $sComputer, $hKey, $phKey )

$sComputer is UNICODE.

RegCreateKeyW( $hKey, $sSubKey, $phKey )

$sSubKey is UNICODE.

RegCreateKeyExW( $hKey, $sSubKey, $iZero, $sClass, $iOpts, $iAccess, $pSecAttr, $phKey, $piDisp )

$sSubKey and $sClass are UNICODE.

RegDeleteKeyW( $hKey, $sSubKey )

$sSubKey is UNICODE.

RegDeleteValueW( $hKey, $sValueName )

$sValueName is UNICODE.

RegEnumKeyW( $hKey, $iIndex, $sName, $lwNameSize )

$sName is UNICODE and $lwNameSize is measured as number of WCHARs.

RegEnumKeyExW( $hKey, $iIndex, $sName, $plwName, $pNull, $sClass, $plwClass, $pftLastWrite )

$sName and $sClass are UNICODE and $plwName and $plwClass are measured as number of WCHARs.

RegEnumValueW( $hKey, $iIndex, $sValName, $plwValName, $pNull, $piType, $pValData, $plValData )

$sValName is UNICODE and $plwValName is measured as number of WCHARs.

$sValData is UNICODE if $piType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $plValData is measured as number of bytes even in these cases.

RegLoadKeyW( $hKey, $sSubKey, $sFileName )

$sSubKey and $sFileName are UNICODE.

RegOpenKeyW( $hKey, $sSubKey, $phKey )

$sSubKey is UNICODE.

RegOpenKeyExW( $hKey, $sSubKey, $iOptions, $iAccess, $phKey )

$sSubKey is UNICODE.

RegQueryInfoKeyW( $hKey, $sClass, $plwClass, $pNull, $pcSubKeys, $plwSubKey, $plwSubClass, $pcValues, $plwValName, $plValData, $plSecDesc, $pftTime )

$sClass is UNICODE. $plwClass, $plwSubKey, $plwSubClass, and $plwValName are measured as number of WCHARs. Note that $plValData is measured as number of bytes.

RegQueryMultipleValuesW( $hKey, $pValueEnts, $cValueEnts, $pBuffer, $plBuffer )

The ve_valuename fields of the VALENT structures in $pValueEnts are UNICODE. Values of type REG_SZ, REG_EXPAND_SZ, and REG_MULTI_SZ are written to $pBuffer in UNICODE. Note that $plBuffer and the ve_valuelen fields of the VALENT structures are measured as number of bytes.

RegQueryValueW( $hKey, $sSubKey, $sValueData, $plValueData )

$sSubKey and $sValueData is UNICODE. Note that $plValueData is measured as number of bytes.

RegQueryValueExW( $hKey, $sValueName, $pNull, $piType, $pValueData, $plValueData )

$sValueName is UNICODE.

$sValueData is UNICODE if $piType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $plValueData is measured as number of bytes even in these cases.

RegReplaceKeyW( $hKey, $sSubKey, $sNewFile, $sOldFile )

$sSubKey, $sNewFile, and $sOldFile are UNICODE.

RegRestoreKeyW( $hKey, $sFileName, $iFlags )

$sFileName is UNICODE.

RegSaveKeyW( $hKey, $sFileName, $pSecAttr )

$sFileName is UNICODE.

RegSetValueW( $hKey, $sSubKey, $iType, $sValueData, $lValueData )

$sSubKey and $sValueData is UNICODE. Note that $lValueData is measured as number of bytes.

RegSetValueExW( $hKey, $sValueName, $iZero, $iType, $pValueData, $lValueData )

$sValueName is UNICODE.

$sValueData is UNICODE if $iType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $lValueData is measured as number of bytes even in these cases.

RegUnLoadKeyW( $hKey, $sSubKey )

$sSubKey is UNICODE.

:HKEY_

All HKEY_* constants:

        HKEY_CLASSES_ROOT       HKEY_CURRENT_CONFIG     HKEY_CURRENT_USER
        HKEY_DYN_DATA           HKEY_LOCAL_MACHINE      HKEY_PERFORMANCE_DATA
        HKEY_USERS
:KEY_

All KEY_* constants:

        KEY_QUERY_VALUE         KEY_SET_VALUE           KEY_CREATE_SUB_KEY
        KEY_ENUMERATE_SUB_KEYS  KEY_NOTIFY              KEY_CREATE_LINK
        KEY_READ                KEY_WRITE               KEY_EXECUTE
        KEY_ALL_ACCESS
:REG_

All REG_* constants:

        REG_OPTION_RESERVED     REG_OPTION_NON_VOLATILE REG_OPTION_VOLATILE
        REG_OPTION_CREATE_LINK  REG_OPTION_BACKUP_RESTORE
        REG_OPTION_OPEN_LINK    REG_LEGAL_OPTION        REG_CREATED_NEW_KEY
        REG_OPENED_EXISTING_KEY REG_WHOLE_HIVE_VOLATILE REG_REFRESH_HIVE
        REG_NO_LAZY_FLUSH       REG_NOTIFY_CHANGE_ATTRIBUTES
        REG_NOTIFY_CHANGE_NAME  REG_NOTIFY_CHANGE_LAST_SET
        REG_NOTIFY_CHANGE_SECURITY                      REG_LEGAL_CHANGE_FILTER
        REG_NONE                REG_SZ                  REG_EXPAND_SZ
        REG_BINARY              REG_DWORD               REG_DWORD_LITTLE_ENDIAN
        REG_DWORD_BIG_ENDIAN    REG_LINK                REG_MULTI_SZ
        REG_RESOURCE_LIST       REG_FULL_RESOURCE_DESCRIPTOR
        REG_RESOURCE_REQUIREMENTS_LIST
:ALL

All of the above.

BUGS

The ActiveState ports of Perl for Win32 [but not the ActiveState bundles of standard Perl 5.004 and beyond] do not support the tools for building extensions and so do not support this extension.

No routines are provided for using the data returned in the FILETIME buffers. Those will be in Win32API::Time when it becomes available.

No routines are provided for dealing with UNICODE data effectively. Such are available elsewhere.

Parts of the module test will fail if used on a version of Perl that does not yet set $^E based on GetLastError().

On NT 4.0 (at least), the RegEnum* calls do not set the required buffer sizes when returning ERROR_MORE_DATA so this module will not grow the buffers in such cases. Win32::TieRegistry overcomes this by using values from RegQueryInfoKey() for buffer sizes in RegEnum* calls.

On NT 4.0 (at least), RegQueryInfoKey() on HKEY_PERFORMANCE_DATA never succeeds. Also, RegQueryValueEx() on HKEY_PERFORMANCE_DATA never returns the required buffer size. To access HKEY_PERFORMANCE_DATA you will need to keep growing the data buffer until the call succeeds.

Because goto &subroutine seems to be buggy under Win32, it is not used in the stubs in Registry.pm.

Using undef as an argument to any of the stubs in Registry.pm may cause warnings when the undef is then passed to the function from Registry.xs that does the real work.

AUTHOR

Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.

SEE ALSO

Win32::TieRegistry
Win32::Registry

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 302:

Unknown E content in E<some>

Around line 333:

Unknown E content in E<might>

Around line 1196:

You forgot a '=back' before '=head1'