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