Closes the handle to a Registry key returned by <A HREF="#item_RegOpenKeyEx"><CODE>RegOpenKeyEx()</CODE></A>,
<A HREF="#item_RegConnectRegistry"><CODE>RegConnectRegistry()</CODE></A>, <A HREF="#item_RegCreateKeyEx"><CODE>RegCreateKeyEx()</CODE></A>, or a few other
<P>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:</P>
<DL>
<DT><STRONG><A NAME="item_Many_modules_can_be_written_by_people_that_don%27t">Many modules can be written by people that don't have a C compiler.</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_Encourages_more_module_code_to_be_written_in_Perl_">Encourages more module code to be written in Perl [not C].</A></STRONG><BR>
<DD>
Perl code is often much easier to inspect, debug, customize, and
enhance than XS code.
<P></P>
<DT><STRONG><A NAME="item_Allows_those_already_familiar_with_the_Win32_API_t">Allows those already familiar with the Win32 API to get
off to a quick start.</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_Provides_an_interactive_tool_%5BPerl%5D_for_explor">Provides an interactive tool [Perl] for exploring even
obscure details of the Win32 API.</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_Ensures_that_native_Win32_data_structures_can_be_u">Ensures that native Win32 data structures can be used.</A></STRONG><BR>
<DD>
This allows maximum efficiency. It also allows data from one
module [for example, time or security information from the
<CODE>Win32API::Registry</CODE> or <CODE>Win32API::File</CODE> modules] to be used
with other modules [for example, <CODE>Win32API::Time</CODE> and
<CODE>Win32API::Security</CODE>].
<P></P>
<DT><STRONG><A NAME="item_Provides_a_single_version_of_the_XS_interface_to_e">Provides a single version of the XS interface to each API
call where improvements can be collected.</A></STRONG><BR>
<DD>
</DL>
<P>
<H2><A NAME="buffer sizes">Buffer sizes</A></H2>
<P>For each argument that specifies a buffer size, a value of <CODE>0</CODE>
can be passed. For arguments that are pointers to buffer sizes,
you can also pass in <CODE>NULL</CODE> by specifying an empty list reference,
<CODE>[]</CODE>. 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 <CODE>ERROR_MORE_DATA</CODE>,
that the buffer size was not sufficient and the <EM>Registry.xs</EM>
code will automatically enlarge the buffer to the required size
and repeat the call.</P>
<P>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.</P>
<P>The underlying calls define buffer size arguments as unsigned, so
negative buffer sizes are treated as very large positive buffer
sizes which usually cause <CODE>malloc()</CODE> to fail.</P>
<P>To force the <EM>Registry.xs</EM> code to pass in a specific value for
a buffer size, preceed the size with <CODE>"="</CODE>. 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 <CODE>strtoul()</CODE> using only base 10] which will be
passed to the underlying routine [even if the allocated buffer is
actually larger]. The <EM>Registry.xs</EM> 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.</P>
<P>Some Reg*() calls may not currently set the buffer size when they
return <CODE>ERROR_MORE_DATA</CODE>. 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.</P>
<P>When you use <CODE>[]</CODE> for a buffer size, you can still find the
length of the data returned by using <A HREF="../../../lib/Pod/perlfunc.html#item_length"><CODE>length($buffer)</CODE></A>. Note
that this length will be in bytes while a few of the buffer
sizes would have been in units of wide characters.</P>
<P>Note that the RegQueryValueEx*() and RegEnumValue*() calls
will trim the trailing <CODE>'\0'</CODE> [if present] from the returned data
values of type <CODE>REG_SZ</CODE> or <CODE>REG_EXPAND_SZ</CODE> but only if the
value data length argument is omitted [or specified as <CODE>[]</CODE>].</P>
<P>The RegSetValueEx*() calls will add a trailing <CODE>'\0'</CODE> [if
missing] to the supplied data values of type <CODE>REG_SZ</CODE> and
<CODE>REG_EXPAND_SZ</CODE> but only if the value data length argument is
<P>Note that an explicit <CODE>L'\0'</CODE> must be added since Perl's implicit
<CODE>'\0'</CODE> that it puts after each of its strings is not wide enough to
terminate a UNICODE string.</P>
<P>If a UNICODE string contains no non-ASCII characters, then you
can convert it back into a normal string via:</P>
<PRE>
$string= pack( "C*", unpack("S*",$unicode) );
$string =~ s/\0$//;</PRE>
<P></P>
<DT><STRONG><A NAME="item_p">p</A></STRONG><BR>
<DD>
A pointer to some buffer [usually containing some <CODE>struct</CODE>]. In C,
a <CODE>void *</CODE>. In Perl, a string that is usually manipulated using
<A HREF="../../../lib/Pod/perlfunc.html#item_pack"><CODE>pack</CODE></A> and <A HREF="../../../lib/Pod/perlfunc.html#item_unpack"><CODE>unpack</CODE></A>. The ``p'' is usually followed by more prefix
<CODE>character(s)</CODE> to indicate what type of data is stored in the bufffer.
<P></P>
<DT><STRONG><A NAME="item_a">a</A></STRONG><BR>
<DD>
A packed array. In C, an array [usually of <CODE>struct</CODE>s]. In Perl, a
string containing the packed data. The ``a'' is usually followed by
more prefix <CODE>character(s)</CODE> to indicate the data type of the elements.
<P>These packed arrays are also called ``vectors'' in places to avoid
confusion with Perl arrays.</P>
<P></P>
<DT><STRONG><A NAME="item_n">n</A></STRONG><BR>
<DD>
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.
<P></P>
<DT><STRONG><A NAME="item_iv">iv</A></STRONG><BR>
<DD>
A signed integral value. In C, any of the signed integer data types.
In Perl, an integer [IV].
<P></P>
<DT><STRONG><A NAME="item_u">u</A></STRONG><BR>
<DD>
An unsigned integral value. In C, any of the unsigned integer data
types. In Perl, an unsigned integer [UV].
<P></P>
<DT><STRONG><A NAME="item_d">d</A></STRONG><BR>
<DD>
A floating-point number. In C, a <CODE>float</CODE> or <CODE>double</CODE> or, perhaps,
a <CODE>long double</CODE>. In Perl, a double-precision floating-point number
[NV].
<P></P>
<DT><STRONG><A NAME="item_b">b</A></STRONG><BR>
<DD>
A Boolean value. In C, any integer data type, though usually via
a type alias of <CODE>bool</CODE> or <CODE>BOOL</CODE>, containing either a 0 [false] or
non-zero [true] value. In Perl, a scalar containing a Boolean value
[<CODE>0</CODE>, <CODE>""</CODE>, or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> for ``false'' and anything else for ``true''].
<P></P>
<DT><STRONG><A NAME="item_c">c</A></STRONG><BR>
<DD>
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 HREF="#a">a</A> above] to indicate the number of elements.
<P></P>
<DT><STRONG><A NAME="item_l">l</A></STRONG><BR>
<DD>
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'' parameters [see <A HREF="#s">s</A> and <A HREF="#p">p</A> above] to indicate the
buffer size or the size of the value stored in the buffer.
<P>For strings, there is no general rule as to whether the trailing
<CODE>'\0'</CODE> is included in such sizes. For this reason, the <CODE>Win32API</CODE>
modules follows the Perl rule of always allocating one extra byte
and reporting buffer sizes as being one smaller than allocated in case
the <CODE>'\0'</CODE> is not included in the size.</P>
<P></P>
<DT><STRONG><A NAME="item_lw">lw</A></STRONG><BR>
<DD>
A length measured as number of UNICODE characters. In C, a count
of <CODE>WCHAR</CODE>s. In Perl, an unsigned integer [UV] counting ``shorts''
[see ``s'' and ``S'' in <A HREF="../../../lib/Pod/perlfunc.html#item_pack"><CODE>pack</CODE></A> and <A HREF="../../../lib/Pod/perlfunc.html#item_unpack"><CODE>unpack</CODE></A>].
<P>For UNICODE strings, the trailing <CODE>L'\0'</CODE> may or may not be included
in a length so, again, we always alllocate extra room for one and
don't report that extra space.</P>
<P></P>
<DT><STRONG><A NAME="item_h">h</A></STRONG><BR>
<DD>
A handle. In C, a <CODE>HANDLE</CODE> or more-specific handle data type. In
Perl, a signed integer [IV]. In C, these handles are often actually
some type of pointer, but Perl just treats them as opaque numbers,
as it should.
<P></P>
<DT><STRONG><A NAME="item_r">r</A></STRONG><BR>
<DD>
A record. In C, almost always a <CODE>struct</CODE> or perhaps <CODE>union</CODE>. Note
that C <CODE>struct</CODE>s are rarely passed by value so the ``r'' is almost
always preceeded by a ``p'' or `` ''a`` [see <A HREF="#p">p</A> and <A HREF="#a">a</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 <CODE>struct</CODE> rather than storing the
<CODE>struct</CODE> directly in a Perl string, the prefix ''pp`` or ''ppr`` or even
''par`` is used.
<P></P>
<DT><STRONG><A NAME="item_sv">sv</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_rv">rv</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_hv">hv</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_av">av</A></STRONG><BR>
<DD>
<DT><STRONG><A NAME="item_cv">cv</A></STRONG><BR>
<DD>
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].
<P></P>
<DT><STRONG><A NAME="item_Input_or_Output">Input or Output</A></STRONG><BR>
<DD>
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.
<DL>
<DT><STRONG><A NAME="item_i">i</A></STRONG><BR>
<DD>
An input parameter given to the API [usually omitted].
<P></P>
<DT><STRONG><A NAME="item_o">o</A></STRONG><BR>
<DD>
An output-only parameter taken from the API. You should not get a
warning if such a parameter is <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> when you pass it into the
function. You should get an error if such a parameter is read-only.
You can [usually] pass in <CODE>[]</CODE> for such a parameter to have the
parameter silently ignored.
<P>These parameters are written to directly, like the buffer argument to
Perl's <A HREF="../../../lib/Pod/perlfunc.html#item_sysread"><CODE>sysread()</CODE></A>. This method is often avoided because such calls
lack 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.</P>
<P></P>
<DT><STRONG><A NAME="item_io">io</A></STRONG><BR>
<DD>
Input given to the API then overwritten with output taken from the
API. You should get a warning [if <STRONG>-w</STRONG> is in effect] if such a
parameter is <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> when you pass it into the function. 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
