NAME

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

SYNOPSIS

  use Win32API::Registry 0.10 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 for use by Tie::Registry(3), which provides an extremely Perl-friendly method for using the Registry.

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 $dwError= Win32::GetLastError() to get the numeric error code and pass that to Win32::FormatMessage($dwError) to to get the descriptive string, or just Win32::FormatMessage(Win32::GetLastError()). Note that $! is not set by these routines except by Win32API::constant() when a constant is not defined.

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 allocated for it and pass in that buffer's allocated size. All of the calls should 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.

Positive 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, 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 currently treated as very large positive buffer sizes which usually cause malloc() to fail. This will probably change in a future version so that negative buffer sizes will disable automatic buffer growing.

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, 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 RegQueryValueExA() and RegEnumValueA() [and hence RegQueryValueEx() and RegEnumValue()] know how to trim the trailing '\0' from data values of type REG_SZ and REG_EXPAND_EZ. RegQueryValueA() and RegQueryValue() cannot realibly tell when to do this and so never do. This is just one more reason not to use these deprecated calls.

Exports

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

:Func

The basic function names.

:FuncA

The ASCI-specific function names.

:FuncW

The UNICODE-specific function names.

:HKEY_

All HKEY_* constants.

:KEY_

All KEY_* constants.

:REG_

All REG_* constants.

:ALL

All of the above.

BUGS

The ActiveState ports of Perl for Win32 do not support the tools for building extensions and so do not support this extension. Suggestions on how to build this extension for use with the ActiveState ports are welcome.

There is not yet any way to prevent buffers from being automatically enlarged [other than passing in [] for that buffer].

No routines are provided for using the data returned in the FILETIME buffers. Those will be in Win32API::File(3) 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. Tie::Registry(3) 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.

AUTHOR

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

SEE ALSO

Tie::Registry(3)

cpanm Win32API::Registry

perl -MCPAN -e shell
install Win32API::Registry