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