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

BUGS
AUTHOR
LICENSE
SEE ALSO

NAME

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

SYNOPSIS

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

  RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key )
    or  die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
            regLastError(),"\n";
  RegQueryValueEx( $key, "Information", [], $type, $data, [] )
    or  die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: ",
            regLastError(),"\n";
  [...]
  RegCloseKey( $key )
    or  die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
            regLastError(),"\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. However, current versions of Perl often overwrite $^E too quickly, so you can use regLastError() instead, which is only set by Win32API::Registry routines. regLastError() is also good if you have a really old version of Perl that does not connect $^E to GetLastError() on Win32.

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

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:

The Win32API:: hierarchy

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 for exploring even obscure details of the Win32 API.

It can be very useful to interactively explore ad-hoc calls into parts of the Win32 API using:

    perl -de 0

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::SecDesc].

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

Buffer sizes

For each parameter that specifies a buffer size, a value of 0 can be passed. For parameter 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 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 parameter 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, precede the size with an equals sign via "=".. Buffer sizes that are passed in as strings starting with an equals sign will have the equal sign stripped and the remainder of the string interpreted 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 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 parameter 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 parameter is omitted [or specified as 0].

Hungarian Notation

The following abbreviations are used at the start of each parameter name to hint at aspects of how the parameter is used. The prefix is always in lower case and followed by a capital letter that starts the descriptive part of the parameter name. Several of the following abbreviations can be combined into a single prefix.

Probably not all of these prefix notations are used by this module. This document section may be included in any Win32API module and so covers some notations not used by this specific module.

s

A string. In C, a '\0'-terminated char *. In Perl, just a string except that it will be truncated at the first "\0", if it contains one.

sw

A wide [UNICODE] string. In C, a L'\0'-terminated WCHAR *. In Perl, a string that contains UNICODE data. You can convert a string to UNICODE in Perl via:

    $string= "This is an example string";
    $unicode= pack( "S*", unpack("C*",$string), 0 );

Note how , 0 above causes an explicit L'\0' to be added since Perl's implicit '\0' that it puts after each of its strings is not wide enough to terminate a UNICODE string. So UNICODE strings are different than regular strings in that the Perl version of a regular string will not include the trailing '\0' while the Perl version of a UNICODE string must include the trailing L'\0'.

If a UNICODE string contains no non-ASCII characters, then you can convert it back into a normal string via:

    $string= pack( "C*", unpack("S*",$unicode) );
    $string =~ s/\0$//;

p

A pointer to some buffer [usually containing some struct]. In C, a void * or some other pointer type. In Perl, a string that is usually manipulated using pack and unpack. The ``p'' is usually followed by more prefix character(s) to indicate what type of data is stored in the buffer.

a

A packed array. In C, an array [usually of structs]. In Perl, a string containing the packed data. The ``a'' is usually followed by more prefix character(s) to indicate the data type of the elements.

These packed arrays are also called ``vectors'' in places to avoid confusion with Perl arrays.

n

A generic number. In C, any of the integer or floating point data types. In Perl, a number; either an integer, unsigned, or double [IV, UV, or NV, respectively]. Usually an integer.

iv

A signed integral value. In C, any of the signed integer data types. In Perl, an integer [IV].

u

An unsigned integral value. In C, any of the unsigned integer data types. In Perl, an unsigned integer [UV].

d

A floating-point number. In C, a float or double or, perhaps, a long double. In Perl, a double-precision floating-point number [NV].

b

A Boolean value. In C, any integer data type, though usually via a type alias of bool or BOOL, containing either a 0 [false] or non-zero [true] value. In Perl, a scalar containing a Boolean value [0, "", or undef for ``false'' and anything else for ``true''].

c

A count of items. In C, any integer data type. In Perl, an unsigned integer [UV]. Usually used in conjunction with a ``vector'' parameter [see a above] to indicate the number of elements.

l

A length [in bytes]. In C, any integer data type. In Perl, an unsigned integer [UV]. Usually used in conjunction with a ``string'' or ``pointer'' parameter [see s and p above] to indicate the buffer size or the size of the value stored in the buffer.

For strings, there is no general rule as to whether the trailing '\0' is included in such sizes. For this reason, the Win32API modules follow the Perl rule of always allocating one extra byte and reporting buffer sizes as being one smaller than allocated in case the '\0' is not included in the size.

lw

A length measured as number of UNICODE characters. In C, a count of WCHARs. In Perl, an unsigned integer [UV] counting ``shorts'' [see ``s'' and ``S'' in pack and unpack].

For UNICODE strings, the trailing L'\0' may or may not be included in a length so, again, we always allocate extra room for one and don't report that extra space.

h

A handle. In C, a HANDLE or more-specific handle data type. In Perl, an unsigned integer [UV]. In C, these handles are often actually some type of pointer, but Perl just treats them as opaque numbers, as it should. This prefix is also used for other pointers that are treated as integers in Perl code.

r

A record. In C, almost always a struct or perhaps union. Note that C structs are rarely passed by value so the ``r'' is almost always preceded by a ``p'' or ``a'' [see p and a above]. For the very rare unadorned ``r'', Perl stores the record in the same way as a ``pr'', that is, in a string. For the very rare case where Perl explicitly stores a pointer to the struct rather than storing the struct directly in a Perl string, the prefix ``pp'' or ``ppr'' or even ``par'' is used.

A Perl data type. Respectively, a scalar value [SV], a reference [RV] [usually to a scalar], a hash [HV], a Perl array [AV], or a Perl code reference [PVCV]. For the ``hv'', ``av'', and ``cv'' prefixes, a leading ``rv'' is usually assumed. For a parameter to an XS subroutine, a prefix of ``sv'' means the parameter is a scalar and so may be a string or a number [or undef] or even both at the same time. So ``sv'' doesn't imply a leading ``rv''.

Input or Output

Whether a parameter is for input data, output data, or both is usually not reflected by the data type prefix. In cases where this is not obvious nor reflected in the parameter name proper, we may use the following in front of the data type prefix.

i: An input parameter given to the API [usually omitted].
o: An output-only parameter taken from the API. You should not get a warning if such a parameter is undef when you pass it into the function. You should get an error if such a parameter is read-only. You can [usually] pass in [] for such a parameter to have the parameter silently ignored.; The output may be written directly into the Perl variable passed to the subroutine, the same way the buffer parameter to Perl's sysread(). This method is often avoided in Perl because the call then lacks any visual cue that some parameters are being overwritten. But this method closely matches the C API which is what we are trying to do.
io: Input given to the API then overwritten with output taken from the API. You should get a warning [if -w is in effect] if such a parameter is undef when you pass it into the function [unless it is a buffer or buffer length parameter]. If the value is read-only, then [for most parameters] the output is silently not written. This is because it is often convenient to pass in read-only constants for many such parameters. You can also usually pass in [] for such parameters.

pp

ppr

par

pap

These are just unusual combinations of prefix characters described above.

For each, a pointer is stored in a [4-byte] Perl string. You can usually use unpack "P" to access the real data from Perl.

For ``ppr'' [and often for ``pp''], the pointer points directly at a C struct. For ``par'', the pointer points to the first element of a C [packed] array of structs. For ``pap'', the pointer points to a C [packed] array of pointers to other things.

ap

Here we have a list of pointers packed into a single Perl string.

BUGS

The old ActiveState ports of Perl for Win32 [but not, ActivePerl, the ActiveState distributions 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 are in the Win32API::Time module.

No routines are provided for dealing with UNICODE data effectively. See :FuncW above for some simple-minded UNICODE methods.

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 Perl, it is not used in the stubs in Registry.pm.

AUTHOR

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

LICENSE

perl