"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/site/lib/Win32API/Registry.pm" (5 Apr 2016, 60771 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 # Registry.pm -- Low-level access to functions/constants from WINREG.h
    2 
    3 package Win32API::Registry;
    4 
    5 use strict;
    6 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); #@EXPORT_FAIL);
    7 $VERSION= '0.33';
    8 
    9 require Exporter;
   10 require DynaLoader;
   11 @ISA= qw(Exporter DynaLoader);
   12 
   13 @EXPORT= qw();
   14 %EXPORT_TAGS= (
   15     Func => [qw(        regConstant     regLastError
   16     AllowPriv       AbortSystemShutdown InitiateSystemShutdown
   17     RegCloseKey     RegConnectRegistry  RegCreateKey
   18     RegCreateKeyEx      RegDeleteKey        RegDeleteValue
   19     RegEnumKey      RegEnumKeyEx        RegEnumValue
   20     RegFlushKey     RegGetKeySecurity   RegLoadKey
   21     RegNotifyChangeKeyValue RegOpenKey      RegOpenKeyEx
   22     RegQueryInfoKey     RegQueryMultipleValues  RegQueryValue
   23     RegQueryValueEx     RegReplaceKey       RegRestoreKey
   24     RegSaveKey      RegSetKeySecurity   RegSetValue
   25     RegSetValueEx       RegUnLoadKey )],
   26     FuncA =>    [qw(
   27     AbortSystemShutdownA    InitiateSystemShutdownA
   28     RegConnectRegistryA RegCreateKeyA       RegCreateKeyExA
   29     RegDeleteKeyA       RegDeleteValueA     RegEnumKeyA
   30     RegEnumKeyExA       RegEnumValueA       RegLoadKeyA
   31     RegOpenKeyA     RegOpenKeyExA       RegQueryInfoKeyA
   32     RegQueryMultipleValuesA RegQueryValueA      RegQueryValueExA
   33     RegReplaceKeyA      RegRestoreKeyA      RegSaveKeyA
   34     RegSetValueA        RegSetValueExA      RegUnLoadKeyA )],
   35     FuncW =>    [qw(
   36     AbortSystemShutdownW    InitiateSystemShutdownW
   37     RegConnectRegistryW RegCreateKeyW       RegCreateKeyExW
   38     RegDeleteKeyW       RegDeleteValueW     RegEnumKeyW
   39     RegEnumKeyExW       RegEnumValueW       RegLoadKeyW
   40     RegOpenKeyW     RegOpenKeyExW       RegQueryInfoKeyW
   41     RegQueryMultipleValuesW RegQueryValueW      RegQueryValueExW
   42     RegReplaceKeyW      RegRestoreKeyW      RegSaveKeyW
   43     RegSetValueW        RegSetValueExW      RegUnLoadKeyW )],
   44     HKEY_ =>    [qw(
   45     HKEY_CLASSES_ROOT   HKEY_CURRENT_CONFIG HKEY_CURRENT_USER
   46     HKEY_DYN_DATA       HKEY_LOCAL_MACHINE  HKEY_PERFORMANCE_DATA
   47     HKEY_USERS )],
   48     KEY_ => [qw(
   49     KEY_QUERY_VALUE     KEY_SET_VALUE       KEY_CREATE_SUB_KEY
   50     KEY_ENUMERATE_SUB_KEYS  KEY_NOTIFY      KEY_CREATE_LINK
   51     KEY_READ        KEY_WRITE       KEY_EXECUTE
   52     KEY_ALL_ACCESS),
   53     'KEY_DELETE',       # DELETE          (0x00010000L)
   54     'KEY_READ_CONTROL', # READ_CONTROL    (0x00020000L)
   55     'KEY_WRITE_DAC',    # WRITE_DAC       (0x00040000L)
   56     'KEY_WRITE_OWNER',  # WRITE_OWNER     (0x00080000L)
   57     'KEY_SYNCHRONIZE',  # SYNCHRONIZE     (0x00100000L) (not used)
   58     ],
   59     REG_ => [qw(
   60     REG_OPTION_RESERVED REG_OPTION_NON_VOLATILE REG_OPTION_VOLATILE
   61     REG_OPTION_CREATE_LINK  REG_OPTION_BACKUP_RESTORE
   62     REG_OPTION_OPEN_LINK    REG_LEGAL_OPTION    REG_CREATED_NEW_KEY
   63     REG_OPENED_EXISTING_KEY REG_WHOLE_HIVE_VOLATILE REG_REFRESH_HIVE
   64     REG_NO_LAZY_FLUSH   REG_NOTIFY_CHANGE_ATTRIBUTES
   65     REG_NOTIFY_CHANGE_NAME  REG_NOTIFY_CHANGE_LAST_SET
   66     REG_NOTIFY_CHANGE_SECURITY          REG_LEGAL_CHANGE_FILTER
   67     REG_NONE        REG_SZ          REG_EXPAND_SZ
   68     REG_BINARY      REG_DWORD       REG_DWORD_LITTLE_ENDIAN
   69     REG_DWORD_BIG_ENDIAN    REG_LINK        REG_MULTI_SZ
   70     REG_RESOURCE_LIST   REG_FULL_RESOURCE_DESCRIPTOR
   71     REG_RESOURCE_REQUIREMENTS_LIST )],
   72     SE_ =>  [qw(
   73     SE_ASSIGNPRIMARYTOKEN_NAME  SE_AUDIT_NAME
   74     SE_BACKUP_NAME          SE_CHANGE_NOTIFY_NAME
   75     SE_CREATE_PAGEFILE_NAME     SE_CREATE_PERMANENT_NAME
   76     SE_CREATE_TOKEN_NAME        SE_DEBUG_NAME
   77     SE_INCREASE_QUOTA_NAME      SE_INC_BASE_PRIORITY_NAME
   78     SE_LOAD_DRIVER_NAME     SE_LOCK_MEMORY_NAME
   79     SE_MACHINE_ACCOUNT_NAME     SE_PROF_SINGLE_PROCESS_NAME
   80     SE_REMOTE_SHUTDOWN_NAME     SE_RESTORE_NAME
   81     SE_SECURITY_NAME        SE_SHUTDOWN_NAME
   82     SE_SYSTEMTIME_NAME      SE_SYSTEM_ENVIRONMENT_NAME
   83     SE_SYSTEM_PROFILE_NAME      SE_TAKE_OWNERSHIP_NAME
   84     SE_TCB_NAME         SE_UNSOLICITED_INPUT_NAME )],
   85 );
   86 @EXPORT_OK= ();
   87 { my $ref;
   88     foreach $ref (  values(%EXPORT_TAGS)  ) {
   89     push( @EXPORT_OK, @$ref )   unless  $ref->[0] =~ /^SE_/;
   90     }
   91 }
   92 $EXPORT_TAGS{ALL}= [ @EXPORT_OK ];  # \@EXPORT_OK once SE_* settles down.
   93 # push( @EXPORT_OK, "JHEREG_TACOSALAD" );   # Used to test Mkconst2perl
   94 push( @EXPORT_OK, @{$EXPORT_TAGS{SE_}} );
   95 
   96 bootstrap Win32API::Registry $VERSION;
   97 
   98 # Preloaded methods go here.
   99 
  100 # To convert C constants to Perl code in cRegistry.pc
  101 # [instead of C or C++ code in cRegistry.h]:
  102 #    * Modify F<Makefile.PL> to add WriteMakeFile() =>
  103 #      CONST2PERL/postamble => [[ "Win32API::Registry" => ]] WRITE_PERL => 1.
  104 #    * Either comment out C<#include "cRegistry.h"> from F<Registry.xs>
  105 #      or make F<cRegistry.h> an empty file.
  106 #    * Make sure the following C<if> block is not commented out.
  107 #    * "nmake clean", "perl Makefile.PL", "nmake"
  108 
  109 if(  ! defined &REG_NONE  ) {
  110     require "Win32API/Registry/cRegistry.pc";
  111 }
  112 
  113 # This would be convenient but inconsistent and hard to explain:
  114 #push( @{$EXPORT_TAGS{ALL}}, @{$EXPORT_TAGS{SE_}} )
  115 #  if  defined &SE_TCB_NAME;
  116 
  117 sub regConstant
  118 {
  119     my( $name )= @_;
  120     if(  1 != @_  ||  ! $name  ||  $name =~ /\W/  ) {
  121     require Carp;
  122     Carp::croak( 'Usage: ',__PACKAGE__,'::regConstant("CONST_NAME")' );
  123     }
  124     my $proto= prototype $name;
  125     if(  defined \&$name
  126      &&  defined $proto
  127      &&  "" eq $proto  ) {
  128     no strict 'refs';
  129     return &$name;
  130     }
  131     return undef;
  132 }
  133 
  134 # We provide this for backwards compatibility:
  135 sub constant
  136 {
  137     my( $name )= @_;
  138     my $value= regConstant( $name );
  139     if(  defined $value  ) {
  140     $!= 0;
  141     return $value;
  142     }
  143     $!= 11; # EINVAL
  144     return 0;
  145 }
  146 
  147 BEGIN {
  148     my $code= 'return _regLastError(@_)';
  149     local( $!, $^E )= ( 1, 1 );
  150     if(  $! ne $^E  ) {
  151     $code= '
  152         local( $^E )= _regLastError(@_);
  153         my $ret= $^E;
  154         return $ret;
  155     ';
  156     }
  157     eval "sub regLastError { $code }";
  158     die "$@"   if  $@;
  159 }
  160 
  161 # Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we
  162 # need this next chunk to prevent Win32API::Registry->nonesuch() from
  163 # looking for "nonesuch.al" and producing confusing error messages:
  164 use vars qw($AUTOLOAD);
  165 sub AUTOLOAD {
  166     require Carp;
  167     Carp::croak(
  168       "Can't locate method $AUTOLOAD via package Win32API::Registry" );
  169 }
  170 
  171 # Replace "&rout;" with "goto &rout;" when that is supported on Win32.
  172 
  173 # Let user omit all buffer sizes:
  174 sub RegEnumKeyExA {
  175     if(  6 == @_  ) {   splice(@_,4,0,[]);  splice(@_,2,0,[]);  }
  176     &_RegEnumKeyExA;
  177 }
  178 sub RegEnumKeyExW {
  179     if(  6 == @_  ) {   splice(@_,4,0,[]);  splice(@_,2,0,[]);  }
  180     &_RegEnumKeyExW;
  181 }
  182 sub RegEnumValueA {
  183     if(  6 == @_  ) {   splice(@_,2,0,[]);  push(@_,[]);  }
  184     &_RegEnumValueA;
  185 }
  186 sub RegEnumValueW {
  187     if(  6 == @_  ) {   splice(@_,2,0,[]);  push(@_,[]);  }
  188     &_RegEnumValueW;
  189 }
  190 sub RegQueryInfoKeyA {
  191     if(  11 == @_  ) {  splice(@_,2,0,[]);  }
  192     &_RegQueryInfoKeyA;
  193 }
  194 sub RegQueryInfoKeyW {
  195     if(  11 == @_  ) {  splice(@_,2,0,[]);  }
  196     &_RegQueryInfoKeyW;
  197 }
  198 
  199 sub RegEnumKeyA {
  200     push(@_,[])   if  3 == @_;
  201     &_RegEnumKeyA;
  202 }
  203 sub RegEnumKeyW {
  204     push(@_,[])   if  3 == @_;
  205     &_RegEnumKeyW;
  206 }
  207 sub RegGetKeySecurity {
  208     push(@_,[])   if  3 == @_;
  209     &_RegGetKeySecurity;
  210 }
  211 sub RegQueryMultipleValuesA {
  212     push(@_,[])   if  4 == @_;
  213     &_RegQueryMultipleValuesA;
  214 }
  215 sub RegQueryMultipleValuesW {
  216     push(@_,[])   if  4 == @_;
  217     &_RegQueryMultipleValuesW;
  218 }
  219 sub RegQueryValueA {
  220     push(@_,[])   if  3 == @_;
  221     &_RegQueryValueA;
  222 }
  223 sub RegQueryValueW {
  224     push(@_,[])   if  3 == @_;
  225     &_RegQueryValueW;
  226 }
  227 sub RegQueryValueExA {
  228     push(@_,[])   if  5 == @_;
  229     &_RegQueryValueExA;
  230 }
  231 sub RegQueryValueExW {
  232     push(@_,[])   if  5 == @_;
  233     &_RegQueryValueExW;
  234 }
  235 sub RegSetValueA {
  236     push(@_,0)   if  4 == @_;
  237     &_RegSetValueA;
  238 }
  239 sub RegSetValueW {
  240     push(@_,0)   if  4 == @_;
  241     &_RegSetValueW;
  242 }
  243 sub RegSetValueExA {
  244     push(@_,0)   if  5 == @_;
  245     &_RegSetValueExA;
  246 }
  247 sub RegSetValueExW {
  248     push(@_,0)   if  5 == @_;
  249     &_RegSetValueExW;
  250 }
  251 
  252 # Aliases for non-Unicode functions:
  253 sub AbortSystemShutdown     { &AbortSystemShutdownA; }
  254 sub InitiateSystemShutdown  { &InitiateSystemShutdownA; }
  255 sub RegConnectRegistry      { &RegConnectRegistryA; }
  256 sub RegCreateKey        { &RegCreateKeyA; }
  257 sub RegCreateKeyEx      { &RegCreateKeyExA; }
  258 sub RegDeleteKey        { &RegDeleteKeyA; }
  259 sub RegDeleteValue      { &RegDeleteValueA; }
  260 sub RegEnumKey          { &RegEnumKeyA; }
  261 sub RegEnumKeyEx        { &RegEnumKeyExA; }
  262 sub RegEnumValue        { &RegEnumValueA; }
  263 sub RegLoadKey          { &RegLoadKeyA; }
  264 sub RegOpenKey          { &RegOpenKeyA; }
  265 sub RegOpenKeyEx        { &RegOpenKeyExA; }
  266 sub RegQueryInfoKey     { &RegQueryInfoKeyA; }
  267 sub RegQueryMultipleValues  { &RegQueryMultipleValuesA; }
  268 sub RegQueryValue       { &RegQueryValueA; }
  269 sub RegQueryValueEx     { &RegQueryValueExA; }
  270 sub RegReplaceKey       { &RegReplaceKeyA; }
  271 sub RegRestoreKey       { &RegRestoreKeyA; }
  272 sub RegSaveKey          { &RegSaveKeyA; }
  273 sub RegSetValue         { &RegSetValueA; }
  274 sub RegSetValueEx       { &RegSetValueExA; }
  275 sub RegUnLoadKey        { &RegUnLoadKeyA; }
  276 
  277 1;
  278 __END__
  279 
  280 =head1 NAME
  281 
  282 Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H
  283 
  284 =head1 SYNOPSIS
  285 
  286   use Win32API::Registry 0.21 qw( :ALL );
  287 
  288   RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key )
  289     or  die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
  290         regLastError(),"\n";
  291   RegQueryValueEx( $key, "Information", [], $type, $data, [] )
  292     or  die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: ",
  293         regLastError(),"\n";
  294   [...]
  295   RegCloseKey( $key )
  296     or  die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
  297         regLastError(),"\n";
  298 
  299 =head1 DESCRIPTION
  300 
  301 This provides fairly low-level access to the Win32 System API
  302 calls dealing with the Registry [mostly from WINREG.H].  This
  303 is mostly intended to be used by other modules such as
  304 C<Win32::TieRegistry> [which provides an extremely Perl-friendly
  305 method for using the Registry].
  306 
  307 For a description of the logical structure of the Registry, see
  308 the documentation for the C<Win32::TieRegistry> module.
  309 
  310 To pass in C<NULL> as the pointer to an optional buffer, pass in
  311 an empty list reference, C<[]>.
  312 
  313 Beyond raw access to the API calls and related constants, this module
  314 handles smart buffer allocation and translation of return codes.
  315 
  316 All calls return a true value for success and a false value for
  317 failure.  After any failure, C<$^E> should automatically be set
  318 to indicate the reason.  However, current versions of Perl often
  319 overwrite C<$^E> too quickly, so you can use C<regLastError()>
  320 instead, which is only set by Win32API::Registry routines. 
  321 C<regLastError()> is also good if you have a really old version
  322 of Perl that does not connect C<$^E> to C<GetLastError()> on
  323 Win32.
  324 
  325 Note that C<$!> is not set by these routines except by
  326 C<Win32API::Registry::constant()> when a constant is not defined.
  327 
  328 =head2 Exports
  329 
  330 Nothing is exported by default.  The following tags can be used to
  331 have sets of symbols exported.
  332 
  333 [Note that much of the following documentation refers to the
  334 behavior of the underlying API calls which may vary in current
  335 and future versions of the Win32 API without any changes to this
  336 module.  Therefore you should check the Win32 API documentation
  337 directly when needed.]
  338 
  339 =over
  340 
  341 =item :Func
  342 
  343 The basic function names:
  344 
  345 =over
  346 
  347 =item AllowPriv
  348 
  349 =item C<AllowPriv( $sPrivName, $bEnable )>
  350 
  351 Not a Win32 API call.  Enables or disables a specific privilege for
  352 the current process.  Returns a true value if successful and a false
  353 value [and sets C<$^E>/C<regLastError()>] on failure.  This routine
  354 does not provide a way to tell if a privilege is currently enabled.
  355 
  356 C<$sPrivname> is a Win32 privilege name [see L</:SE_>].  For example,
  357 C<"SeBackupPrivilege"> [a.k.a. C<SE_BACKUP_NAME>] controls whether
  358 you can use C<RegSaveKey()> and C<"SeRestorePrivilege"> [a.k.a.
  359 C<SE_RESTORE_NAME>] controls whether you can use C<RegLoadKey()>.
  360 
  361 If C<$bEnable> is true, then C<AllowPriv()> tries to enable the
  362 privilege.  Otherwise it tries to disable the privilege.
  363 
  364 =item AbortSystemShutdown
  365 
  366 =item C<AbortSystemShutdown( $sComputerName )>
  367 
  368 Tries to abort a remote shutdown request previously made via
  369 C<InitiateSystemShutdown()>.  Returns a true value if successful
  370 and a false value [and sets C<$^E>/C<regLastError()>] on failure.
  371 
  372 =item InitiateSystemShutdown
  373 
  374 =item C<InitiateSystemShutdown( $sComputer, $sMessage, $uTimeoutSecs, $bForce, $bReboot )>
  375 
  376 Requests that a [remote] computer be shutdown or rebooted.
  377 Returns a true value if successful and a false value [and
  378 sets C<$^E>/C<regLastError()>] on failure.
  379 
  380 C<$sComputer> is the name [or address] of the computer to be
  381 shutdown or rebooted.  You can use C<[]> [for C<NULL>] or C<"">
  382 to indicate the local computer.
  383 
  384 C<$sMessage> is the message to be displayed in a pop-up window
  385 on the desktop of the computer to be shutdown or rebooted until
  386 the timeout expires or the shutdown is aborted via
  387 C<AbortSystemShutdown()>.  With C<$iTimeoutSecs == 0>, the
  388 message will never be visible.
  389 
  390 C<$iTimeoutSecs> is the number of seconds to wait before starting
  391 the shutdown.
  392 
  393 If C<$bForce> is false, then any applications running on the remote
  394 computer get a chance to prompt the remote user whether they want
  395 to save changes.  Also, for any applications that do not exit quickly
  396 enough, the operating system will prompt the user whether they wish
  397 to wait longer for the application to exit or force it to exit now.
  398 At any of these prompts the user can press B<CANCEL> to abort the
  399 shutdown but if no applications have unsaved data, they will likely
  400 all exit quickly and the shutdown will progress with the remote user
  401 having no option to cancel the shutdown.
  402 
  403 If C<$bForce> is true, all applications are told to exit immediately
  404 and so will not prompt the user even if there is unsaved data.  Any
  405 applications that take too long to exit will be forcibly killed after
  406 a short time.  The only way to abort the shutdown is to call
  407 C<AbortSystemShutdown()> before the timeout expires and there is no
  408 way to abort the shutdown once it has begun.
  409 
  410 If C<$bReboot> is true, the computer will automatically reboot once
  411 the shutdown is complete.  If C<$bReboot> is false, then when the
  412 shutdown is complete the computer will halt at a screen indicating
  413 that the shutdown is complete and offering a way for the user to
  414 start to boot the computer.
  415 
  416 You must have the C<"SeRemoteShutdownPrivilege"> privilege
  417 on the remote computer for this call to succeed.  If shutting
  418 down the local computer, then the calling process must have
  419 the C<"SeShutdownPrivilege"> privilege and have it enabled.
  420 
  421 =item RegCloseKey
  422 
  423 =item C<RegCloseKey( $hKey )>
  424 
  425 Closes the handle to a Registry key returned by C<RegOpenKeyEx()>,
  426 C<RegConnectRegistry()>, C<RegCreateKeyEx()>, or a few other
  427 routines.  Returns a true value if successful and a false value
  428 [and sets C<$^E>/C<regLastError()>] on failure.
  429 
  430 =item RegConnectRegistry
  431 
  432 =item C<RegConnectRegistry( $sComputer, $hRootKey, $ohKey )>
  433 
  434 Connects to one of the root Registry keys of a remote computer.
  435 Returns a true value if successful and a false value [and
  436 sets C<$^E>/C<regLastError()>] on failure.
  437 
  438 C<$sComputer> is the name [or address] of a remote computer
  439 whose Registry you wish to access.
  440 
  441 C<$hKey> must be either C<HKEY_LOCAL_MACHINE> or C<HKEY_USERS>
  442 and specifies which root Registry key on the remote computer
  443 you wish to have access to.
  444 
  445 C<$phKey> will be set to the handle to be used to access the
  446 remote Registry key if the call succeeds.
  447 
  448 =item regConstant
  449 
  450 =item C<$value= regConstant( $sConstantName )>
  451 
  452 Fetch the value of a constant.  Returns C<undef> if C<$sConstantName>
  453 is not the name of a constant supported by this module.  Never sets
  454 C<$!> nor C<$^E>.
  455 
  456 This function is rarely used since you will usually get the value of a
  457 constant by having that constant imported into your package by listing
  458 the constant name in the C<use Win32API::Registry> statement and then
  459 simply using the constant name in your code [perhaps followed by
  460 C<()>].  This function is useful for verifying constant names not in
  461 Perl code, for example, after prompting a user to type in a constant
  462 name.
  463 
  464 =item RegCreateKey
  465 
  466 =item C<RegCreateKey( $hKey, $sSubKey, $ohSubKey )>
  467 
  468 This routine is meant only for compatibility with Windows version
  469 3.1.  Use C<RegCreateKeyEx()> instead.
  470 
  471 =item RegCreateKeyEx
  472 
  473 =item C<RegCreateKeyEx( $hKey, $sSubKey, $uZero, $sClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>
  474 
  475 Creates a new Registry subkey.  Returns a true value if successful and
  476 a false value [and sets C<$^E>/C<regLastError()>] on failure.
  477 
  478 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  479 a previous call].
  480 
  481 C<$sSubKey> is the name of the new subkey to be created.
  482 
  483 C<$iZero> is reserved for future use and should always be specified
  484 as C<0>.
  485 
  486 C<$sClass> is a string to be used as the class for the new
  487 subkey.  We are not aware of any current use for Registry key
  488 class information so the empty string, C<"">, should usually
  489 be used here.
  490 
  491 C<$iOpts> is a numeric value containing bits that control options
  492 used while creating the new subkey.  C<REG_OPTION_NON_VOLATILE>
  493 is the default.  C<REG_OPTION_VOLATILE> [which is ignored on
  494 Windows 95] means the data stored under this key is not kept
  495 in a file and will not be preserved when the system reboots.
  496 C<REG_OPTION_BACKUP_RESTORE> [also ignored on Windows 95] means
  497 ignore the C<$iAccess> parameter and try to open the new key with
  498 the access required to backup or restore the key.
  499 
  500 C<$iAccess> is a numeric mask of bits specifying what type of
  501 access is desired when opening the new subkey.  See C<RegOpenKeyEx()>.
  502 
  503 C<$pSecAttr> is a C<SECURITY_ATTRIBUTES> structure packed into
  504 a Perl string which controls whether the returned handle can be
  505 inherited by child processes.  Normally you would pass C<[]> for
  506 this parameter to have C<NULL> passed to the underlying API
  507 indicating that the handle cannot be inherited.  If not under
  508 Windows95, then C<$pSecAttr> also allows you to specify
  509 C<SECURITY_DESCRIPTOR> that controls which users will have
  510 what type of access to the new key -- otherwise the new key
  511 inherits its security from its parent key.
  512 
  513 C<$phKey> will be set to the handle to be used to access the new
  514 subkey if the call succeeds.
  515 
  516 C<$piDisp> will be set to either C<REG_CREATED_NEW_KEY> or
  517 C<REG_OPENED_EXISTING_KEY> to indicate for which reason the
  518 call succeeded.  Can be specified as C<[]> if you don't care.
  519 
  520 If C<$phKey> and C<$piDisp> start out as integers, then they will
  521 probably remain unchanged if the call fails.
  522 
  523 =item RegDeleteKey
  524 
  525 =item C<RegDeleteKey( $hKey, $sSubKey )>
  526 
  527 Deletes a subkey of an open Registry key provided that the subkey
  528 contains no subkeys of its own [but the subkey may contain values].
  529 Returns a true value if successful and a false value [and sets
  530 C<$^E>/C<regLastError()>] on failure.
  531 
  532 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  533 a previous call].
  534 
  535 C<$sSubKey> is the name of the subkey to be deleted.
  536 
  537 =item RegDeleteValue
  538 
  539 =item C<RegDeleteValue( $hKey, $sValueName )>
  540 
  541 Deletes a value from an open Registry key.  Returns a true value if
  542 successful and a false value [and sets C<$^E>/C<regLastError()>] on
  543 failure.
  544 
  545 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  546 a previous call].
  547 
  548 C<$sValueKey> is the name of the value to be deleted.
  549 
  550 =item RegEnumKey
  551 
  552 =item C<RegEnumKey( $hKey, $uIndex, $osName, $ilNameSize )>
  553 
  554 This routine is meant only for compatibility with Windows version
  555 3.1.  Use C<RegEnumKeyEx()> instead.
  556 
  557 =item RegEnumKeyEx
  558 
  559 =item C<RegEnumKeyEx( $hKey, $uIndex, $osName, $iolName, $pNull, $osClass, $iolClass, $opftLastWrite )>
  560 
  561 Lets you enumerate the names of all of the subkeys directly under
  562 an open Registry key.  Returns a true value if successful and a false
  563 value [and sets C<$^E>/C<regLastError()>] on failure.
  564 
  565 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  566 a previous call].
  567 
  568 C<$iIndex> is the sequence number of the immediate subkey that
  569 you want information on.  Start with this value as C<0> then
  570 repeat the call incrementing this value each time until the
  571 call fails with C<$^E>/C<regLastError()> numerically equal to
  572 C<ERROR_NO_MORE_ITEMS>.
  573 
  574 C<$sName> will be set to the name of the subkey.  Can be C<[]> if
  575 you don't care about the name.
  576 
  577 C<$plName> initially specifies the [minimum] buffer size to be
  578 allocated for C<$sName>.  Will be set to the length of the subkey
  579 name if the requested subkey exists even if C<$sName> isn't
  580 successfully set to the subkey name.  See L<Buffer sizes> for
  581 more information.
  582 
  583 C<$pNull> is reserved for future used and should be passed as C<[]>.
  584 
  585 C<$sClass> will be set to the class name for the subkey.  Can be
  586 C<[]> if you don't care about the class.
  587 
  588 C<$plClass> initially specifies the [minimum] buffer size to be
  589 allocated for C<$sClass> and will be set to the length of the
  590 subkey class name if the requested subkey exists.  See L<Buffer
  591 sizes> for more information.
  592 
  593 C<$pftLastWrite> will be set to a C<FILETIME> structure packed
  594 into a Perl string and indicating when the subkey was last changed.
  595 Can be C<[]>.
  596 
  597 You may omit both C<$plName> and C<$plClass> to get the same effect
  598 as passing in C<[]> for each of them.
  599 
  600 =item RegEnumValue
  601 
  602 =item C<RegEnumValue( $hKey, $uIndex, $osValName, $iolValName, $pNull, $ouType, $opValData, $iolValData )>
  603 
  604 Lets you enumerate the names of all of the values contained in an
  605 open Registry key.  Returns a true value if successful and a false
  606 value [and sets C<$^E>/C<regLastError()>] on failure.
  607 
  608 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  609 a previous call].
  610 
  611 C<$iIndex> is the sequence number of the value that you want
  612 information on.  Start with this value as C<0> then repeat the
  613 call incrementing this value each time until the call fails with
  614 C<ERROR_NO_MORE_ITEMS>.
  615 
  616 C<$sValName> will be set to the name of the value.  Can be C<[]>
  617 if you don't care about the name.
  618 
  619 C<$plValName> initially specifies the [minimum] buffer size to be
  620 allocated for C<$sValName>.  Will be set to the length of the value
  621 name if the requested value exists even if C<$sValName> isn't
  622 successfully set to the value name.  See L<Buffer sizes> for
  623 more information.
  624 
  625 C<$pNull> is reserved for future used and should be passed as C<[]>.
  626 
  627 C<$piType> will be set to the type of data stored in the value data.
  628 If the call succeeds, it will be set to a C<REG_*> value unless
  629 passed in as C<[]>.
  630 
  631 C<$pValData> will be set to the data [packed into a Perl string]
  632 that is stored in the requested value.  Can be C<[]> if you don't
  633 care about the value data.
  634 
  635 C<$plValData> initially specifies the [minimum] buffer size to be
  636 allocated for C<$sValData> and will be set to the length of the
  637 value data if the requested value exists.  See L<Buffer sizes> for
  638 more information.
  639 
  640 You may omit both C<$plValName> and C<$plValData> to get the same
  641 effect as passing in C<[]> for each of them.
  642 
  643 =item RegFlushKey
  644 
  645 =item C<RegFlushKey( $hKey )>
  646 
  647 Forces the data stored under an open Registry key to be flushed
  648 to the disk file where the data is preserved between reboots.
  649 Forced flushing is not guaranteed to be efficient so this routine
  650 should almost never be called.  Returns a true value if successful
  651 and a false value [and sets C<$^E>/C<regLastError()>] on failure.
  652 
  653 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  654 a previous call].
  655 
  656 =item RegGetKeySecurity
  657 
  658 =item C<RegGetKeySecurity( $hKey, $uSecInfo, $opSecDesc, $iolSecDesc )>
  659 
  660 Retrieves one of the C<SECURITY_DESCRIPTOR> structures describing
  661 part of the security for an open Registry key.  Returns a true value
  662 if successful and a false value [and sets C<$^E>/C<regLastError()>]
  663 on failure.
  664 
  665 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  666 a previous call].
  667 
  668 C<$iSecInfo> is a numeric C<SECURITY_INFORMATION> value that
  669 specifies which parts of the C<SECURITY_DESCRIPTOR> structure
  670 to retrieve.  Should be C<OWNER_SECURITY_INFORMATION>,
  671 C<GROUP_SECURITY_INFORMATION>, C<DACL_SECURITY_INFORMATION>, or
  672 or C<SACL_SECURITY_INFORMATION> or two or more of these bits
  673 combined using C<|>.
  674 
  675 C<$pSecDesc> will be set to the requested C<SECURITY_DESCRIPTOR>
  676 structure [packed into a Perl string].
  677 
  678 C<$plSecDesc> initially specifies the [minimum] buffer size to be
  679 allocated for C<$sSecDesc> and will be set to the length of the
  680 security descriptor.  See L<Buffer sizes> for more information.
  681 You may omit this parameter to get the same effect as passing in
  682 C<[]> for it.
  683 
  684 =item regLastError
  685 
  686 =item C<$svError= regLastError();>
  687 
  688 =item C<regLastError( $uError );>
  689 
  690 Returns the last error encountered by a routine from this module. 
  691 It is just like C<$^E> except it isn't changed by anything except
  692 routines from this module.  Ideally you could just use C<$^E>, but
  693 current versions of Perl often overwrite C<$^E> before you get a
  694 chance to check it and really old versions of Perl don't really
  695 support C<$^E> under Win32.
  696 
  697 Just like C<$^E>, in a numeric context C<regLastError()> returns
  698 the numeric error value while in a string context it returns a
  699 text description of the error [actually it returns a Perl scalar
  700 that contains both values so C<$x= regLastError()> causes C<$x>
  701 to give different values in string vs. numeric contexts].  On old
  702 versions of Perl where C<$^E> isn't tied to C<GetLastError()>,
  703 C<regLastError> simply returns the number of the error and you'll
  704 need to use <Win32::FormatMessage> to get the error string.
  705 
  706 The last form sets the error returned by future calls to
  707 C<regLastError()> and should not be used often.  C<$uError> must
  708 be a numeric error code.  Also returns the dual-valued version
  709 of C<$uError>.
  710 
  711 =item RegLoadKey
  712 
  713 =item C<RegLoadKey( $hKey, $sSubKey, $sFileName )>
  714 
  715 Loads a hive file.  That is, it creates a new subkey in the
  716 Registry and associates that subkey with a disk file that contains
  717 a Registry hive so that the new subkey can be used to access the
  718 keys and values stored in that hive.  Hives are usually created
  719 via C<RegSaveKey()>.  Returns a true value if successful and a
  720 false value [and sets C<$^E>/C<regLastError()>] on failure.
  721 
  722 C<$hKey> is the handle to a Registry key that can have hives
  723 loaded to it.  This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
  724 or a remote version of one of these from a call to
  725 C<RegConnectRegistry()>.
  726 
  727 C<$sSubKey> is the name of the new subkey to created and associated
  728 with the hive file.
  729 
  730 C<$sFileName> is the name of the hive file to be loaded.  This
  731 file name is interpreted relative to the
  732 C<%SystemRoot%/System32/config> directory on the computer where
  733 the C<$hKey> key resides.  If C<$sFileName> is on a FAT file
  734 system, then its name must not have an extension.
  735 
  736 You must have the C<SE_RESTORE_NAME> privilege to use this routine.
  737 
  738 WARNING:  Loading of hive files via a network share may silently
  739 corrupt the hive and so should not be attempted [this is a problem
  740 in at least some versions of the underlying API which this module
  741 does not try to fix or avoid].  To access a hive file located on a
  742 remote computer, connect to the remote computer's Registry and load
  743 the hive via that.
  744 
  745 =item RegNotifyChangeKeyValue
  746 
  747 =item C<RegNotifyChangeKeyValue( $hKey, $bWatchSubtree, $uNotifyFilter, $hEvent, $bAsync )>
  748 
  749 Arranges for your process to be notified when part of the Registry
  750 is changed.  Returns a true value if successful and a false value
  751 [and sets C<$^E>/C<regLastError()>] on failure.
  752 
  753 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  754 a previous call] for which you wish to be notified when any changes
  755 are made to it.
  756 
  757 If C<$bWatchSubtree> is true, then changes to any subkey or
  758 descendant of C<$hKey> are also reported.
  759 
  760 C<$iNotifyFilter> controllers what types of changes are reported.  It
  761 is a numeric value containing one or more of the following bit masks:
  762 
  763 =over
  764 
  765 =item C<REG_NOTIFY_CHANGE_NAME>
  766 
  767 Notify if a subkey is added or deleted to a monitored key.
  768 
  769 =item C<REG_NOTIFY_CHANGE_LAST_SET>
  770 
  771 Notify if a value in a monitored key is added, deleted, or modified.
  772 
  773 =item C<REG_NOTIFY_CHANGE_SECURITY>
  774 
  775 Notify if a security descriptor of a monitored key is changed.
  776 
  777 =item C<REG_NOTIFY_CHANGE_ATTRIBUTES>
  778 
  779 Notify if any attributes of a monitored key are changed [class
  780 name or security descriptors].
  781 
  782 =back
  783 
  784 C<$hEvent> is ignored unless C<$bAsync> is true.  Otherwise, C<$hEvent>
  785 is a handle to a Win32 I<event> that will be signaled when changes are
  786 to be reported.
  787 
  788 If C<$bAsync> is true, then C<RegNotifyChangeKeyValue()> returns
  789 immediately and uses C<$hEvent> to notify your process of changes.
  790 If C<$bAsync> is false, then C<RegNotifyChangeKeyValue()> does
  791 not return until there is a change to be notified of.
  792 
  793 This routine does not work with Registry keys on remote computers.
  794 
  795 =item RegOpenKey
  796 
  797 =item C<RegOpenKey( $hKey, $sSubKey, $ohSubKey )>
  798 
  799 This routine is meant only for compatibility with Windows version
  800 3.1.  Use C<RegOpenKeyEx()> instead.
  801 
  802 =item RegOpenKeyEx
  803 
  804 =item C<RegOpenKeyEx( $hKey, $sSubKey, $uOptions, $uAccess, $ohSubKey )>
  805 
  806 Opens an existing Registry key.  Returns a true value if successful
  807 and a false value [and sets C<$^E>/C<regLastError()>] on failure.
  808 
  809 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  810 a previous call].
  811 
  812 C<$sSubKey> is the name of an existing subkey to be opened.
  813 Can be C<""> or C<[]> to open an additional handle to the
  814 key specified by C<$hKey>.
  815 
  816 C<$iOptions> is a numeric value containing bits that control options
  817 used while opening the subkey.  There are currently no supported
  818 options so this parameter should be specified as C<0>.
  819 
  820 C<$iAccess> is a numeric mask of bits specifying what type of
  821 access is desired when opening the new subkey.  Should be a
  822 combination of one or more of the following bit masks:
  823 
  824 =over
  825 
  826 =item C<KEY_ALL_ACCESS>
  827 
  828     KEY_READ | KEY_WRITE | KEY_CREATE_LINK
  829 
  830 =item C<KEY_READ>
  831 
  832     KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
  833 
  834 =item C<KEY_WRITE>
  835 
  836     KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
  837 
  838 =item C<KEY_QUERY_VALUE>
  839 
  840 =item C<KEY_SET_VALUE>
  841 
  842 =item C<KEY_ENUMERATE_SUB_KEYS>
  843 
  844 =item C<KEY_CREATE_SUB_KEY>
  845 
  846 =item C<KEY_NOTIFY>
  847 
  848 Allows you to use C<RegNotifyChangeKeyValue()> on the opened key.
  849 
  850 =item C<KEY_EXECUTE>
  851 
  852 Same as C<KEY_READ>.
  853 
  854 =item C<KEY_CREATE_LINK>
  855 
  856 Gives you permission to create a symbolic link like
  857 C<HKEY_CLASSES_ROOT> and C<HKEY_CURRENT_USER>, though the method for
  858 doing so is not documented [and probably requires use of the mostly
  859 undocumented "native" routines, C<Nt*()> a.k.a. C<Zw*()>].
  860 
  861 =back
  862 
  863 C<$phKey> will be set to the handle to be used to access the new subkey
  864 if the call succeeds.
  865 
  866 =item RegQueryInfoKey
  867 
  868 =item C<RegQueryInfoKey( $hKey, $osClass, $iolClass, $pNull, $ocSubKeys, $olSubKey, $olSubClass, $ocValues, $olValName, $olValData, $olSecDesc, $opftTime )>
  869 
  870 Gets miscellaneous information about an open Registry key.
  871 Returns a true value if successful and a false value [and
  872 sets C<$^E>/C<regLastError()>] on failure.
  873 
  874 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  875 a previous call].
  876 
  877 C<$sClass> will be set to the class name for the key.  Can be
  878 C<[]> if you don't care about the class.
  879 
  880 C<$plClass> initially specifies the [minimum] buffer size to be
  881 allocated for C<$sClass> and will be set to the length of the
  882 key's class name.  See L<Buffer sizes> for more information.
  883 You may omit this parameter to get the same effect as passing in
  884 C<[]> for it.
  885 
  886 C<$pNull> is reserved for future use and should be passed as C<[]>.
  887 
  888 C<$pcSubKeys> will be set to the count of the number of subkeys
  889 directly under this key.  Can be C<[]>.
  890 
  891 C<$plSubKey> will be set to the length of the longest subkey name.
  892 Can be C<[]>.
  893 
  894 C<$plSubClass> will be set to the length of the longest class name
  895 used with an immediate subkey of this key.  Can be C<[]>.
  896 
  897 C<$pcValues> will be set to the count of the number of values in
  898 this key.  Can be C<[]>.
  899 
  900 C<$plValName> will be set to the length of the longest value name
  901 in this key.  Can be C<[]>.
  902 
  903 C<$plValData> will be set to the length of the longest value data
  904 in this key.  Can be C<[]>.
  905 
  906 C<$plSecDesc> will be set to the length of this key's full security
  907 descriptor.
  908 
  909 C<$pftTime> will be set to a C<FILETIME> structure packed
  910 into a Perl string and indicating when this key was last changed.
  911 Can be C<[]>.
  912 
  913 =item RegQueryMultipleValues
  914 
  915 =item C<RegQueryMultipleValues( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>
  916 
  917 Allows you to use a single call to query several values from a single
  918 open Registry key to maximize efficiency.  Returns a true value if
  919 successful and a false value [and sets C<$^E>/C<regLastError()>] on
  920 failure.
  921 
  922 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  923 a previous call].
  924 
  925 C<$pValueEnts> should contain a list of C<VALENT> structures packed
  926 into a single Perl string.  Each C<VALENT> structure should have
  927 the C<ve_valuename> entry [the first 4 bytes] pointing to a string
  928 containing the name of a value stored in this key.  The remaining
  929 fields are set if the function succeeds.
  930 
  931 C<$cValueEnts> should contain the count of the number of C<VALENT>
  932 structures contained in C<$pValueEnts>.
  933 
  934 C<$pBuffer> will be set to the data from all of the requested values
  935 concatenated into a single Perl string.
  936 
  937 C<$plBuffer> initially specifies the [minimum] buffer size to be
  938 allocated for C<$sBuffer> and will be set to the total length of
  939 the data to be written to C<$sBuffer>.  See L<Buffer sizes> for
  940 more information.  You may omit this parameter to get the same
  941 effect as passing in C<[]> for it.
  942 
  943 Here is sample code to populate C<$pValueEnts>:
  944 
  945     # @ValueNames= ...list of value name strings...;
  946     $cValueEnts= @ValueNames;
  947     $pValueEnts= pack( " p x4 x4 x4 " x $cValueEnts, @ValueNames );
  948 
  949 Here is sample code to retrieve the data type and data length
  950 returned in C<$pValueEnts>:
  951 
  952     @Lengths= unpack( " x4 L x4 x4 " x $cValueEnts, $pValueEnts );
  953     @Types=   unpack( " x4 x4 x4 L " x $cValueEnts, $pValueEnts );
  954 
  955 Given the above, and assuming you haven't modified C<$sBuffer> since
  956 the call, you can also extract the value data strings from C<$sBuffer>
  957 by using the pointers returned in C<$pValueEnts>:
  958 
  959     @Data=    unpack(  join( "", map {" x4 x4 P$_ x4 "} @Lengths ),
  960             $pValueEnts  );
  961 
  962 Much better is to use the lengths and extract directly from
  963 C<$sBuffer> using C<unpack()> [or C<substr()>]:
  964 
  965     @Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
  966 
  967 =item RegQueryValue
  968 
  969 =item C<RegQueryValue( $hKey, $sSubKey, $osValueData, $iolValueData )>
  970 
  971 This routine is meant only for compatibility with Windows version
  972 3.1.  Use C<RegQueryValueEx()> instead.  This routine can only
  973 query unnamed values [a.k.a. "default values"], that is, values with
  974 a name of C<"">.
  975 
  976 =item RegQueryValueEx
  977 
  978 =item C<RegQueryValueEx( $hKey, $sValueName, $pNull, $ouType, $opValueData, $iolValueData )>
  979 
  980 Lets you look up value data stored in an open Registry key by
  981 specifying the value name.  Returns a true value if successful
  982 and a false value [and sets C<$^E>/C<regLastError()>] on failure.
  983 
  984 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
  985 a previous call].
  986 
  987 C<$sValueName> is the name of the value whose data you wish to
  988 retrieve.
  989 
  990 C<$pNull> this parameter is reserved for future use and should be
  991 specified as C<[]>.
  992 
  993 C<$piType> will be set to indicate what type of data is stored in
  994 the named value.  Will be set to a C<REG_*> value if the function
  995 succeeds.
  996 
  997 C<$pValueData> will be set to the value data [packed into a Perl
  998 string] that is stored in the named value.  Can be C<[]> if you
  999 don't care about the value data.
 1000 
 1001 C<$plValueData> initially specifies the [minimum] buffer size to be
 1002 allocated for C<$sValueData> and will be set to the size [always
 1003 in bytes] of the data to be written to C<$sValueData>, even if
 1004 C<$sValueData> is not successfully written to.  See L<Buffer sizes>
 1005 for more information.
 1006 
 1007 =item RegReplaceKey
 1008 
 1009 =item C<RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )>
 1010 
 1011 Lets you replace an entire hive when the system is next booted. 
 1012 Returns a true value if successful and a false value [and sets
 1013 C<$^E>/C<regLastError()>] on failure.
 1014 
 1015 C<$hKey> is the handle to a Registry key that has hive(s)
 1016 loaded in it.  This must be C<HKEY_LOCAL_MACHINE>,
 1017 C<HKEY_USERS>, or a remote version of one of these from
 1018 a call to C<RegConnectRegistry()>.
 1019 
 1020 C<$sSubKey> is the name of the subkey of C<$hKey> whose hive
 1021 you wish to have replaced on the next reboot.
 1022 
 1023 C<$sNewFile> is the name of a file that will replace the existing
 1024 hive file when the system reboots.
 1025 
 1026 C<$sOldFile> is the file name to save the current hive file to
 1027 when the system reboots.
 1028 
 1029 C<$sNewFile> and C<$sOldFile> are interpreted relative to the
 1030 C<%SystemRoot%/System32/config> directory on the computer where
 1031 the C<$hKey> key resides [I think].  If either file is [would be]
 1032 on a FAT file system, then its name must not have an extension.
 1033 
 1034 You must have the C<SE_RESTORE_NAME> privilege to use this routine.
 1035 
 1036 =item RegRestoreKey
 1037 
 1038 =item C<RegRestoreKey( $hKey, $sFileName, $uFlags )>
 1039 
 1040 Reads in a hive file and copies its contents over an existing
 1041 Registry tree.  Returns a true value if successful and a false
 1042 value [and sets C<$^E>/C<regLastError()>] on failure.
 1043 
 1044 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
 1045 a previous call].
 1046 
 1047 C<$sFileName> is the name of the hive file to be read.  For each
 1048 value and subkey in this file, a value or subkey will be added
 1049 or replaced in C<$hKey>.
 1050 
 1051 C<$uFlags> is usually C<0>.  It can also be C<REG_WHOLE_HIVE_VOLATILE>
 1052 which, rather than copying the hive over the existing key,
 1053 replaces the existing key with a temporary, memory-only Registry
 1054 key and then copies the hive contents into it.  This option only
 1055 works if C<$hKey> is C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>, or a
 1056 remote version of one of these from a call to C<RegConnectRegistry()>.
 1057 
 1058 C<RegRestoreKey> does I<not> delete values nor keys from the
 1059 existing Registry tree when there is no corresponding value/key
 1060 in the hive file.
 1061 
 1062 =item RegSaveKey
 1063 
 1064 =item C<RegSaveKey( $hKey, $sFileName, $pSecAttr )>
 1065 
 1066 Dumps any open Registry key and all of its subkeys and values into
 1067 a new hive file.  Returns a true value if successful and a false
 1068 value [and sets C<$^E>/C<regLastError()>] on failure.
 1069 
 1070 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
 1071 a previous call].
 1072 
 1073 C<$sFileName> is the name of the file that the Registry tree
 1074 should be saved to.  It is interpreted relative to the
 1075 C<%SystemRoot%/System32/config> directory on the computer where
 1076 the C<$hKey> key resides.  If C<$sFileName> is on a FAT file system,
 1077 then it must not have an extension.
 1078 
 1079 C<$pSecAttr> contains a C<SECURITY_ATTRIBUTES> structure that specifies
 1080 the permissions to be set on the new file that is created.  This can
 1081 be C<[]>.
 1082 
 1083 You must have the C<SE_RESTORE_NAME> privilege to use this routine.
 1084 
 1085 =item RegSetKeySecurity
 1086 
 1087 =item C<RegSetKeySecurity( $hKey, $uSecInfo, $pSecDesc )>
 1088 
 1089 Sets [part of] the C<SECURITY_DESCRIPTOR> structure describing part
 1090 of the security for an open Registry key.  Returns a true value if
 1091 successful and a false value [and sets C<$^E>/C<regLastError()>] on
 1092 failure.
 1093 
 1094 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
 1095 a previous call].
 1096 
 1097 C<$uSecInfo> is a numeric C<SECURITY_INFORMATION> value that
 1098 specifies which C<SECURITY_DESCRIPTOR> structure to set.  Should
 1099 be C<OWNER_SECURITY_INFORMATION>, C<GROUP_SECURITY_INFORMATION>,
 1100 C<DACL_SECURITY_INFORMATION>, or C<SACL_SECURITY_INFORMATION>
 1101 or two or more of these bits combined using C<|>.
 1102 
 1103 C<$pSecDesc> contains the new C<SECURITY_DESCRIPTOR> structure
 1104 packed into a Perl string.
 1105 
 1106 =item RegSetValue
 1107 
 1108 =item C<RegSetValue( $hKey, $sSubKey, $uType, $sValueData, $lValueData )>
 1109 
 1110 This routine is meant only for compatibility with Windows version
 1111 3.1.  Use C<RegSetValueEx()> instead.  This routine can only
 1112 set unnamed values [a.k.a. "default values"].
 1113 
 1114 =item RegSetValueEx
 1115 
 1116 =item C<RegSetValueEx( $hKey, $sName, $uZero, $uType, $pData, $lData )>
 1117 
 1118 Adds or replaces a value in an open Registry key.  Returns
 1119 a true value if successful and a false value [and sets
 1120 C<$^E>/C<regLastError()>] on failure.
 1121 
 1122 C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
 1123 a previous call].
 1124 
 1125 C<$sName> is the name of the value to be set.
 1126 
 1127 C<$uZero> is reserved for future use and should be specified as C<0>.
 1128 
 1129 C<$uType> is the type of data stored in C<$pData>.  It should
 1130 be a C<REG_*> value.
 1131 
 1132 C<$pData> is the value data packed into a Perl string.
 1133 
 1134 C<$lData> is the length of the value data that is stored in C<$pData>.
 1135 You will usually omit this parameter or pass in C<0> to have
 1136 C<length($pData)> used.  In both of these cases, if C<$iType> is
 1137 C<REG_SZ> or C<REG_EXPAND_SZ>, C<RegSetValueEx()> will append a
 1138 trailing C<'\0'> to the end of C<$pData> [unless there is already
 1139 one].
 1140 
 1141 =item RegUnLoadKey
 1142 
 1143 =item C<RegUnLoadKey( $hKey, $sSubKey )>
 1144 
 1145 Unloads a previously loaded hive file.  That is, closes the
 1146 hive file then deletes the subkey that was providing access
 1147 to it.  Returns a true value if successful and a false value
 1148 [and sets C<$^E>/C<regLastError()>] on failure.
 1149 
 1150 C<$hKey> is the handle to a Registry key that has hives
 1151 loaded in it.  This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
 1152 or a remote version of one of these from a call to
 1153 C<RegConnectRegistry()>.
 1154 
 1155 C<$sSubKey> is the name of the subkey whose hive you wish to
 1156 have unloaded.
 1157 
 1158 =item :FuncA
 1159 
 1160 The ASCII-specific function names.
 1161 
 1162 Each of these is identical to the version listed above without the
 1163 trailing "A":
 1164 
 1165     AbortSystemShutdownA    InitiateSystemShutdownA
 1166     RegConnectRegistryA RegCreateKeyA       RegCreateKeyExA
 1167     RegDeleteKeyA       RegDeleteValueA     RegEnumKeyA
 1168     RegEnumKeyExA       RegEnumValueA       RegLoadKeyA
 1169     RegOpenKeyA     RegOpenKeyExA       RegQueryInfoKeyA
 1170     RegQueryMultipleValuesA RegQueryValueA      RegQueryValueExA
 1171     RegReplaceKeyA      RegRestoreKeyA      RegSaveKeyA
 1172     RegSetValueA        RegSetValueExA      RegUnLoadKeyA
 1173 
 1174 =item :FuncW
 1175 
 1176 The UNICODE-specific function names.  These are the same as the
 1177 versions listed above without the trailing "W" except that string
 1178 parameters are UNICODE strings rather than ASCII strings, as
 1179 indicated.
 1180 
 1181 =item AbortSystemShutdownW
 1182 
 1183 =item C<AbortSystemShutdownW( $swComputerName )>
 1184 
 1185 C<$swComputerName> is UNICODE.
 1186 
 1187 =item InitiateSystemShutdownW
 1188 
 1189 =item C<InitiateSystemShutdownW( $swComputer, $swMessage, $uTimeoutSecs, $bForce, $bReboot )>
 1190 
 1191 C<$swComputer> and C<$swMessage> are UNICODE.
 1192 
 1193 =item RegConnectRegistryW
 1194 
 1195 =item C<RegConnectRegistryW( $swComputer, $hRootKey, $ohKey )>
 1196 
 1197 C<$swComputer> is UNICODE.
 1198 
 1199 =item RegCreateKeyW
 1200 
 1201 =item C<RegCreateKeyW( $hKey, $swSubKey, $ohSubKey )>
 1202 
 1203 C<$swSubKey> is UNICODE.
 1204 
 1205 =item RegCreateKeyExW
 1206 
 1207 =item C<RegCreateKeyExW( $hKey, $swSubKey, $uZero, $swClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>
 1208 
 1209 C<$swSubKey> and C<$swClass> are UNICODE.
 1210 
 1211 =item RegDeleteKeyW
 1212 
 1213 =item C<RegDeleteKeyW( $hKey, $swSubKey )>
 1214 
 1215 C<$swSubKey> is UNICODE.
 1216 
 1217 =item RegDeleteValueW
 1218 
 1219 =item C<RegDeleteValueW( $hKey, $swValueName )>
 1220 
 1221 C<$swValueName> is UNICODE.
 1222 
 1223 =item RegEnumKeyW
 1224 
 1225 =item C<RegEnumKeyW( $hKey, $uIndex, $oswName, $ilwNameSize )>
 1226 
 1227 C<$oswName> is UNICODE and C<$ilwNameSize> is measured as number of
 1228 C<WCHAR>s.
 1229 
 1230 =item RegEnumKeyExW
 1231 
 1232 =item C<RegEnumKeyExW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $oswClass, $iolwClass, $opftLastWrite )>
 1233 
 1234 C<$swName> and C<$swClass> are UNICODE and C<$iolwName> and C<$iolwClass>
 1235 are measured as number of C<WCHAR>s.
 1236 
 1237 =item RegEnumValueW
 1238 
 1239 =item C<RegEnumValueW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $ouType, $opData, $iolData )>
 1240 
 1241 C<$oswName> is UNICODE and C<$iolwName> is measured as number
 1242 of C<WCHAR>s.
 1243 
 1244 C<$opData> is UNICODE if C<$piType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
 1245 or C<REG_MULTI_SZ>.  Note that C<$iolData> is measured as number
 1246 of bytes even in these cases.
 1247 
 1248 =item RegLoadKeyW
 1249 
 1250 =item C<RegLoadKeyW( $hKey, $swSubKey, $swFileName )>
 1251 
 1252 C<$swSubKey> and C<$swFileName> are UNICODE.
 1253 
 1254 =item RegOpenKeyW
 1255 
 1256 =item C<RegOpenKeyW( $hKey, $swSubKey, $ohSubKey )>
 1257 
 1258 C<$swSubKey> is UNICODE.
 1259 
 1260 =item RegOpenKeyExW
 1261 
 1262 =item C<RegOpenKeyExW( $hKey, $swSubKey, $uOptions, $uAccess, $ohSubKey )>
 1263 
 1264 C<$swSubKey> is UNICODE.
 1265 
 1266 =item RegQueryInfoKeyW
 1267 
 1268 =item C<RegQueryInfoKeyW( $hKey, $oswClass, $iolwClass, $pNull, $ocSubKeys, $olwSubKey, $olwSubClass, $ocValues, $olwValName, $olValData, $olSecDesc, $opftTime )>
 1269 
 1270 C<$swClass> is UNICODE.  C<$iolwClass>, C<$olwSubKey>, C<$olwSubClass>,
 1271 and C<$olwValName> are measured as number of C<WCHAR>s.  Note that
 1272 C<$olValData> is measured as number of bytes.
 1273 
 1274 =item RegQueryMultipleValuesW
 1275 
 1276 =item C<RegQueryMultipleValuesW( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>
 1277 
 1278 The C<ve_valuename> fields of the C<VALENT> [actually C<VALENTW>]
 1279 structures in C<$ioarValueEnts> are UNICODE.  Values of type C<REG_SZ>,
 1280 C<REG_EXPAND_SZ>, and C<REG_MULTI_SZ> are written to C<$opBuffer>
 1281 in UNICODE.  Note that C<$iolBuffer> and the C<ve_valuelen> fields
 1282 of the C<VALENT> [C<VALENTW>] structures are measured as number of
 1283 bytes.
 1284 
 1285 =item RegQueryValueW
 1286 
 1287 =item C<RegQueryValueW( $hKey, $swSubKey, $oswValueData, $iolValueData )>
 1288 
 1289 C<$swSubKey> and C<$oswValueData> are UNICODE.  Note that
 1290 C<$iolValueData> is measured as number of bytes.
 1291 
 1292 =item RegQueryValueExW
 1293 
 1294 =item C<RegQueryValueExW( $hKey, $swName, $pNull, $ouType, $opData, $iolData )>
 1295 
 1296 C<$swName> is UNICODE.
 1297 
 1298 C<$opData> is UNICODE if C<$ouType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
 1299 or C<REG_MULTI_SZ>.  Note that C<$iolData> is measured as number of
 1300 bytes even in these cases.
 1301 
 1302 =item RegReplaceKeyW
 1303 
 1304 =item C<RegReplaceKeyW( $hKey, $swSubKey, $swNewFile, $swOldFile )>
 1305 
 1306 C<$swSubKey>, C<$swNewFile>, and C<$swOldFile> are UNICODE.
 1307 
 1308 =item RegRestoreKeyW
 1309 
 1310 =item C<RegRestoreKeyW( $hKey, $swFileName, $uFlags )>
 1311 
 1312 C<$swFileName> is UNICODE.
 1313 
 1314 =item RegSaveKeyW
 1315 
 1316 =item C<RegSaveKeyW( $hKey, $swFileName, $pSecAttr )>
 1317 
 1318 C<$swFileName> is UNICODE.
 1319 
 1320 =item RegSetValueW
 1321 
 1322 =item C<RegSetValueW( $hKey, $swSubKey, $uType, $swValueData, $lValueData )>
 1323 
 1324 C<$swSubKey> and C<$swValueData> are UNICODE.  Note that
 1325 C<$lValueData> is measured as number of bytes even though
 1326 C<$swValueData> is always UNICODE.
 1327 
 1328 =item RegSetValueExW
 1329 
 1330 =item C<RegSetValueExW( $hKey, $swName, $uZero, $uType, $pData, $lData )>
 1331 
 1332 C<$swName> is UNICODE.
 1333 
 1334 C<$pData> is UNICODE if C<$uType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
 1335 or C<REG_MULTI_SZ>.  Note that C<$lData> is measured as number of
 1336 bytes even in these cases.
 1337 
 1338 =item RegUnLoadKeyW
 1339 
 1340 =item C<RegUnLoadKeyW( $hKey, $swSubKey )>
 1341 
 1342 C<$swSubKey> is UNICODE.
 1343 
 1344 =item :HKEY_
 1345 
 1346 All C<HKEY_*> constants:
 1347 
 1348     HKEY_CLASSES_ROOT   HKEY_CURRENT_CONFIG HKEY_CURRENT_USER
 1349     HKEY_DYN_DATA       HKEY_LOCAL_MACHINE  HKEY_PERFORMANCE_DATA
 1350     HKEY_USERS
 1351 
 1352 =item :KEY_
 1353 
 1354 All C<KEY_*> constants:
 1355 
 1356     KEY_QUERY_VALUE     KEY_SET_VALUE       KEY_CREATE_SUB_KEY
 1357     KEY_ENUMERATE_SUB_KEYS  KEY_NOTIFY      KEY_CREATE_LINK
 1358     KEY_READ        KEY_WRITE       KEY_EXECUTE
 1359     KEY_ALL_ACCESS
 1360 
 1361 =item :REG_
 1362 
 1363 All C<REG_*> constants:
 1364 
 1365     REG_CREATED_NEW_KEY     REG_OPENED_EXISTING_KEY
 1366 
 1367     REG_LEGAL_CHANGE_FILTER     REG_NOTIFY_CHANGE_ATTRIBUTES
 1368     REG_NOTIFY_CHANGE_NAME      REG_NOTIFY_CHANGE_LAST_SET
 1369     REG_NOTIFY_CHANGE_SECURITY  REG_LEGAL_OPTION
 1370 
 1371     REG_OPTION_BACKUP_RESTORE   REG_OPTION_CREATE_LINK
 1372     REG_OPTION_NON_VOLATILE     REG_OPTION_OPEN_LINK
 1373     REG_OPTION_RESERVED     REG_OPTION_VOLATILE
 1374 
 1375     REG_WHOLE_HIVE_VOLATILE     REG_REFRESH_HIVE
 1376     REG_NO_LAZY_FLUSH
 1377 
 1378     REG_NONE            REG_SZ
 1379     REG_EXPAND_SZ           REG_BINARY
 1380     REG_DWORD           REG_DWORD_LITTLE_ENDIAN
 1381     REG_DWORD_BIG_ENDIAN        REG_LINK
 1382     REG_MULTI_SZ            REG_RESOURCE_LIST
 1383     REG_FULL_RESOURCE_DESCRIPTOR    REG_RESOURCE_REQUIREMENTS_LIST
 1384 
 1385 =item :ALL
 1386 
 1387 All of the above.
 1388 
 1389 =item :SE_
 1390 
 1391 The strings for the following privilege names:
 1392 
 1393     SE_ASSIGNPRIMARYTOKEN_NAME  SE_AUDIT_NAME
 1394     SE_BACKUP_NAME          SE_CHANGE_NOTIFY_NAME
 1395     SE_CREATE_PAGEFILE_NAME     SE_CREATE_PERMANENT_NAME
 1396     SE_CREATE_TOKEN_NAME        SE_DEBUG_NAME
 1397     SE_INCREASE_QUOTA_NAME      SE_INC_BASE_PRIORITY_NAME
 1398     SE_LOAD_DRIVER_NAME     SE_LOCK_MEMORY_NAME
 1399     SE_MACHINE_ACCOUNT_NAME     SE_PROF_SINGLE_PROCESS_NAME
 1400     SE_REMOTE_SHUTDOWN_NAME     SE_RESTORE_NAME
 1401     SE_SECURITY_NAME        SE_SHUTDOWN_NAME
 1402     SE_SYSTEMTIME_NAME      SE_SYSTEM_ENVIRONMENT_NAME
 1403     SE_SYSTEM_PROFILE_NAME      SE_TAKE_OWNERSHIP_NAME
 1404     SE_TCB_NAME         SE_UNSOLICITED_INPUT_NAME
 1405 
 1406 It can be difficult to successfully build this module in a way
 1407 that makes these constants available.  So some builds of this
 1408 module may not make them available.  For such builds, trying
 1409 to export any of these constants will cause a fatal error.
 1410 For this reason, none of these symbols are currently included
 1411 in the C<":ALL"> grouping.
 1412 
 1413 =back
 1414 
 1415 =back
 1416 
 1417 =head2 The Win32API:: hierarchy
 1418 
 1419 This and the other Win32API:: modules are meant to expose the
 1420 nearly raw API calls so they can be used from Perl code in any
 1421 way they might be used from C code.  This provides the following
 1422 advantages:
 1423 
 1424 =over
 1425 
 1426 =item Many modules can be written by people that don't have a C compiler.
 1427 
 1428 =item Encourages more module code to be written in Perl [not C].
 1429 
 1430 Perl code is often much easier to inspect, debug, customize, and
 1431 enhance than XS code.
 1432 
 1433 =item Allows those already familiar with the Win32 API to get
 1434 off to a quick start.
 1435 
 1436 =item Provides an interactive tool for exploring even obscure
 1437 details of the Win32 API.
 1438 
 1439 It can be very useful to interactively explore ad-hoc calls into
 1440 parts of the Win32 API using:
 1441 
 1442     perl -de 0
 1443 
 1444 =item Ensures that native Win32 data structures can be used.
 1445 
 1446 This allows maximum efficiency.  It also allows data from one
 1447 module [for example, time or security information from the
 1448 C<Win32API::Registry> or C<Win32API::File> modules] to be used
 1449 with other modules [for example, C<Win32API::Time> and
 1450 C<Win32API::SecDesc>].
 1451 
 1452 =item Provides a single version of the XS interface to each API
 1453 call where improvements can be collected.
 1454 
 1455 =back
 1456 
 1457 =head2 Buffer sizes
 1458 
 1459 For each parameter that specifies a buffer size, a value of C<0>
 1460 can be passed.  For parameter that are pointers to buffer sizes,
 1461 you can also pass in C<NULL> by specifying an empty list reference,
 1462 C<[]>.  Both of these cases will ensure that the variable has
 1463 I<some> buffer space allocated to it and pass in that buffer's
 1464 allocated size.  Many of the calls indicate, via C<ERROR_MORE_DATA>,
 1465 that the buffer size was not sufficient and the F<Registry.xs>
 1466 code will automatically enlarge the buffer to the required size
 1467 and repeat the call.
 1468 
 1469 Numeric buffer sizes are used as minimum initial sizes for the
 1470 buffers.  The larger of this size and the size of space already
 1471 allocated to the scalar will be passed to the underlying routine. 
 1472 If that size was insufficient, and the underlying call provides
 1473 an easy method for determining the needed buffer size, then the
 1474 buffer will be enlarged and the call repeated as above.
 1475 
 1476 The underlying calls define buffer size parameter as unsigned, so
 1477 negative buffer sizes are treated as very large positive buffer
 1478 sizes which usually cause C<malloc()> to fail.
 1479 
 1480 To force the F<Registry.xs> code to pass in a specific value for
 1481 a buffer size, precede the size with an equals sign via C<"=".>. 
 1482 Buffer sizes that are passed in as strings starting with an equals
 1483 sign will have the equal sign stripped and the remainder of the string
 1484 interpreted as a number [via C's C<strtoul()> using only base 10]
 1485 which will be passed to the underlying routine [even if the allocated
 1486 buffer is actually larger].  The F<Registry.xs> code will enlarge the
 1487 buffer to the specified size, if needed, but will not enlarge the
 1488 buffer based on the underlying routine requesting more space.
 1489 
 1490 Some Reg*() calls may not currently set the buffer size when they
 1491 return C<ERROR_MORE_DATA>.  But some that are not documented as
 1492 doing so, currently do so anyway.  So the code assumes that any
 1493 routine I<might> do this and resizes any buffers and repeats the
 1494 call.   We hope that eventually all routines will provide this
 1495 feature.
 1496 
 1497 When you use C<[]> for a buffer size, you can still find the
 1498 length of the data returned by using C<length($buffer)>.  Note
 1499 that this length will be in bytes while a few of the buffer
 1500 sizes would have been in units of wide characters.
 1501 
 1502 Note that the RegQueryValueEx*() and RegEnumValue*() calls
 1503 will trim the trailing C<'\0'> [if present] from the returned data
 1504 values of type C<REG_SZ> or C<REG_EXPAND_SZ> but only if the
 1505 value data length parameter is omitted [or specified as C<[]>].
 1506 
 1507 The RegSetValueEx*() calls will add a trailing C<'\0'> [if
 1508 missing] to the supplied data values of type C<REG_SZ> and
 1509 C<REG_EXPAND_SZ> but only if the value data length parameter
 1510 is omitted [or specified as C<0>].
 1511 
 1512 =head2 Hungarian Notation
 1513 
 1514 The following abbreviations are used at the start of each parameter
 1515 name to hint at aspects of how the parameter is used.  The prefix
 1516 is always in lower case and followed by a capital letter that starts
 1517 the descriptive part of the parameter name.  Several of the following
 1518 abbreviations can be combined into a single prefix.
 1519 
 1520 Probably not all of these prefix notations are used by this module. 
 1521 This document section may be included in any C<Win32API> module and
 1522 so covers some notations not used by this specific module.
 1523 
 1524 =over
 1525 
 1526 =item s
 1527 
 1528 A string.  In C, a C<'\0'>-terminated C<char *>.  In Perl, just a
 1529 string except that it will be truncated at the first C<"\0">, if
 1530 it contains one.
 1531 
 1532 =item sw
 1533 
 1534 A wide [UNICODE] string.  In C, a C<L'\0'>-terminated C<WCHAR *>.
 1535 In Perl, a string that contains UNICODE data.  You can convert a
 1536 string to UNICODE in Perl via:
 1537 
 1538     $string= "This is an example string";
 1539     $unicode= pack( "S*", unpack("C*",$string), 0 );
 1540 
 1541 Note how C<, 0> above causes an explicit C<L'\0'> to be added since
 1542 Perl's implicit C<'\0'> that it puts after each of its strings is not
 1543 wide enough to terminate a UNICODE string.  So UNICODE strings are
 1544 different than regular strings in that the Perl version of a regular
 1545 string will not include the trailing C<'\0'> while the Perl version
 1546 of a UNICODE string must include the trailing C<L'\0'>.
 1547 
 1548 If a UNICODE string contains no non-ASCII characters, then you
 1549 can convert it back into a normal string via:
 1550 
 1551     $string= pack( "C*", unpack("S*",$unicode) );
 1552     $string =~ s/\0$//;
 1553 
 1554 =item p
 1555 
 1556 A pointer to some buffer [usually containing some C<struct>].  In C,
 1557 a C<void *> or some other pointer type.  In Perl, a string that is
 1558 usually manipulated using C<pack> and C<unpack>.  The "p" is usually
 1559 followed by more prefix character(s) to indicate what type of data is
 1560 stored in the buffer.
 1561 
 1562 =item a
 1563 
 1564 A packed array.  In C, an array [usually of C<struct>s].  In Perl, a
 1565 string containing the packed data.  The "a" is usually followed by
 1566 more prefix character(s) to indicate the data type of the elements.
 1567 
 1568 These packed arrays are also called "vectors" in places to avoid
 1569 confusion with Perl arrays.
 1570 
 1571 =item n
 1572 
 1573 A generic number.   In C, any of the integer or floating point data
 1574 types.  In Perl, a number; either an integer, unsigned, or double
 1575 [IV, UV, or NV, respectively].  Usually an integer.
 1576 
 1577 =item iv
 1578 
 1579 A signed integral value.  In C, any of the signed integer data types. 
 1580 In Perl, an integer [IV].
 1581 
 1582 =item u
 1583 
 1584 An unsigned integral value.  In C, any of the unsigned integer data
 1585 types.  In Perl, an unsigned integer [UV].
 1586 
 1587 =item d
 1588 
 1589 A floating-point number.  In C, a C<float> or C<double> or, perhaps,
 1590 a C<long double>.  In Perl, a double-precision floating-point number
 1591 [NV].
 1592 
 1593 =item b
 1594 
 1595 A Boolean value.  In C, any integer data type, though usually via
 1596 a type alias of C<bool> or C<BOOL>, containing either a 0 [false] or
 1597 non-zero [true] value.  In Perl, a scalar containing a Boolean value
 1598 [C<0>, C<"">, or C<undef> for "false" and anything else for "true"].
 1599 
 1600 =item c
 1601 
 1602 A count of items.  In C, any integer data type.  In Perl, an unsigned
 1603 integer [UV].  Usually used in conjunction with a "vector" parameter
 1604 [see L</a> above] to indicate the number of elements.
 1605 
 1606 =item l
 1607 
 1608 A length [in bytes].  In C, any integer data type.  In Perl, an
 1609 unsigned integer [UV].  Usually used in conjunction with a "string"
 1610 or "pointer" parameter [see L</s> and L</p> above] to indicate the
 1611 buffer size or the size of the value stored in the buffer.
 1612 
 1613 For strings, there is no general rule as to whether the trailing
 1614 C<'\0'> is included in such sizes.  For this reason, the C<Win32API>
 1615 modules follow the Perl rule of always allocating one extra byte
 1616 and reporting buffer sizes as being one smaller than allocated in
 1617 case the C<'\0'> is not included in the size.
 1618 
 1619 =item lw
 1620 
 1621 A length measured as number of UNICODE characters.  In C, a count
 1622 of C<WCHAR>s.  In Perl, an unsigned integer [UV] counting "shorts"
 1623 [see "s" and "S" in C<pack> and C<unpack>].
 1624 
 1625 For UNICODE strings, the trailing C<L'\0'> may or may not be
 1626 included in a length so, again, we always allocate extra room
 1627 for one and don't report that extra space.
 1628 
 1629 =item h
 1630 
 1631 A handle.  In C, a C<HANDLE> or more-specific handle data type. 
 1632 In Perl, an unsigned integer [UV].  In C, these handles are often
 1633 actually some type of pointer, but Perl just treats them as opaque
 1634 numbers, as it should.  This prefix is also used for other pointers
 1635 that are treated as integers in Perl code.
 1636 
 1637 =item r
 1638 
 1639 A record.  In C, almost always a C<struct> or perhaps C<union>.  Note
 1640 that C C<struct>s are rarely passed by value so the "r" is almost
 1641 always preceded by a "p" or "a" [see L</p> and L</a> above].  For
 1642 the very rare unadorned "r", Perl stores the record in the same way
 1643 as a "pr", that is, in a string.  For the very rare case where Perl
 1644 explicitly stores a pointer to the C<struct> rather than storing the
 1645 C<struct> directly in a Perl string, the prefix "pp" or "ppr" or even
 1646 "par" is used.
 1647 
 1648 =item sv
 1649 
 1650 =item rv
 1651 
 1652 =item hv
 1653 
 1654 =item av
 1655 
 1656 =item cv
 1657 
 1658 A Perl data type.  Respectively, a scalar value [SV], a reference
 1659 [RV] [usually to a scalar], a hash [HV], a Perl array [AV], or a Perl
 1660 code reference [PVCV].  For the "hv", "av", and "cv" prefixes, a
 1661 leading "rv" is usually assumed.  For a parameter to an XS subroutine,
 1662 a prefix of "sv" means the parameter is a scalar and so may be a string
 1663 or a number [or C<undef>] or even both at the same time.  So "sv"
 1664 doesn't imply a leading "rv".
 1665 
 1666 =item Input or Output
 1667 
 1668 Whether a parameter is for input data, output data, or both is usually
 1669 not reflected by the data type prefix.  In cases where this is not
 1670 obvious nor reflected in the parameter name proper, we may use the
 1671 following in front of the data type prefix.
 1672 
 1673 =over
 1674 
 1675 =item i
 1676 
 1677 An input parameter given to the API [usually omitted].
 1678 
 1679 =item o
 1680 
 1681 An output-only parameter taken from the API.  You should not get a
 1682 warning if such a parameter is C<undef> when you pass it into the
 1683 function.  You should get an error if such a parameter is read-only.
 1684 You can [usually] pass in C<[]> for such a parameter to have the
 1685 parameter silently ignored.
 1686 
 1687 The output may be written directly into the Perl variable passed
 1688 to the subroutine, the same way the buffer parameter to Perl's
 1689 C<sysread()>.  This method is often avoided in Perl because
 1690 the call then lacks any visual cue that some parameters are being
 1691 overwritten.   But this method closely matches the C API which is
 1692 what we are trying to do.
 1693 
 1694 =item io
 1695 
 1696 Input given to the API then overwritten with output taken from the
 1697 API.  You should get a warning [if B<-w> is in effect] if such a
 1698 parameter is C<undef> when you pass it into the function [unless it
 1699 is a buffer or buffer length parameter].  If the value is read-only,
 1700 then [for most parameters] the output is silently not written.  This
 1701 is because it is often convenient to pass in read-only constants for
 1702 many such parameters.  You can also usually pass in C<[]> for such
 1703 parameters.
 1704 
 1705 =back
 1706 
 1707 =item pp
 1708 
 1709 =item ppr
 1710 
 1711 =item par
 1712 
 1713 =item pap
 1714 
 1715 These are just unusual combinations of prefix characters described above.
 1716 
 1717 For each, a pointer is stored in a [4-byte] Perl string.  You can
 1718 usually use C<unpack "P"> to access the real data from Perl.
 1719 
 1720 For "ppr" [and often for "pp"], the pointer points directly at a
 1721 C C<struct>.  For "par", the pointer points to the first element
 1722 of a C [packed] array of C<struct>s.  For "pap", the pointer points
 1723 to a C [packed] array of pointers to other things.
 1724 
 1725 =item ap
 1726 
 1727 Here we have a list of pointers packed into a single Perl string.
 1728 
 1729 =back
 1730 
 1731 
 1732 =head1 BUGS
 1733 
 1734 The old ActiveState ports of Perl for Win32 [but not, ActivePerl, the
 1735 ActiveState distributions of standard Perl 5.004 and beyond] do not support
 1736 the tools for building extensions and so do not support this extension.
 1737 
 1738 No routines are provided for using the data returned in the C<FILETIME>
 1739 buffers.  Those are in the C<Win32API::Time> module.
 1740 
 1741 No routines are provided for dealing with UNICODE data effectively. 
 1742 See L</:FuncW> above for some simple-minded UNICODE methods.
 1743 
 1744 Parts of the module test will fail if used on a version of Perl
 1745 that does not yet set C<$^E> based on C<GetLastError()>.
 1746 
 1747 On NT 4.0 [at least], the RegEnum*() calls do not set the required
 1748 buffer sizes when returning C<ERROR_MORE_DATA> so this module will
 1749 not grow the buffers in such cases.  C<Win32::TieRegistry> overcomes
 1750 this by using values from C<RegQueryInfoKey()> for buffer sizes in
 1751 RegEnum* calls.
 1752 
 1753 On NT 4.0 [at least], C<RegQueryInfoKey()> on C<HKEY_PERFORMANCE_DATA>
 1754 never succeeds.  Also, C<RegQueryValueEx()> on C<HKEY_PERFORMANCE_DATA>
 1755 never returns the required buffer size.  To access C<HKEY_PERFORMANCE_DATA>
 1756 you will need to keep growing the data buffer until the call succeeds.
 1757 
 1758 Because C<goto &subroutine> seems to be buggy under Win32 Perl,
 1759 it is not used in the stubs in F<Registry.pm>.
 1760 
 1761 =head1 AUTHOR
 1762 
 1763 Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
 1764 
 1765 =head1 LICENSE
 1766 
 1767 perl
 1768 
 1769 =head1 SEE ALSO
 1770 
 1771 =over
 1772 
 1773 =item L<Win32::TieRegistry>
 1774 
 1775 =item L<Win32::Registry>
 1776 
 1777 =back
 1778 
 1779 =cut