summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Win32API/Registry.pm
blob: dbf98b4e2e903a90bc80b3e48aca8d8593dc415f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
# Registry.pm -- Low-level access to functions/constants from WINREG.h

package Win32API::Registry;

use strict;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); #@EXPORT_FAIL);
$VERSION= '0.24';

require Exporter;
require DynaLoader;
@ISA= qw(Exporter DynaLoader);

@EXPORT= qw();
%EXPORT_TAGS= (
    Func =>	[qw(		regConstant		regLastError
	AllowPriv		AbortSystemShutdown	InitiateSystemShutdown
	RegCloseKey		RegConnectRegistry	RegCreateKey
	RegCreateKeyEx		RegDeleteKey		RegDeleteValue
	RegEnumKey		RegEnumKeyEx		RegEnumValue
	RegFlushKey		RegGetKeySecurity	RegLoadKey
	RegNotifyChangeKeyValue	RegOpenKey		RegOpenKeyEx
	RegQueryInfoKey		RegQueryMultipleValues	RegQueryValue
	RegQueryValueEx		RegReplaceKey		RegRestoreKey
	RegSaveKey		RegSetKeySecurity	RegSetValue
	RegSetValueEx		RegUnLoadKey )],
    FuncA =>	[qw(
	AbortSystemShutdownA	InitiateSystemShutdownA
	RegConnectRegistryA	RegCreateKeyA		RegCreateKeyExA
	RegDeleteKeyA		RegDeleteValueA		RegEnumKeyA
	RegEnumKeyExA		RegEnumValueA		RegLoadKeyA
	RegOpenKeyA		RegOpenKeyExA		RegQueryInfoKeyA
	RegQueryMultipleValuesA	RegQueryValueA		RegQueryValueExA
	RegReplaceKeyA		RegRestoreKeyA		RegSaveKeyA
	RegSetValueA		RegSetValueExA		RegUnLoadKeyA )],
    FuncW =>	[qw(
	AbortSystemShutdownW	InitiateSystemShutdownW
	RegConnectRegistryW	RegCreateKeyW		RegCreateKeyExW
	RegDeleteKeyW		RegDeleteValueW		RegEnumKeyW
	RegEnumKeyExW		RegEnumValueW		RegLoadKeyW
	RegOpenKeyW		RegOpenKeyExW		RegQueryInfoKeyW
	RegQueryMultipleValuesW	RegQueryValueW		RegQueryValueExW
	RegReplaceKeyW		RegRestoreKeyW		RegSaveKeyW
	RegSetValueW		RegSetValueExW		RegUnLoadKeyW )],
    HKEY_ =>	[qw(
	HKEY_CLASSES_ROOT	HKEY_CURRENT_CONFIG	HKEY_CURRENT_USER
	HKEY_DYN_DATA		HKEY_LOCAL_MACHINE	HKEY_PERFORMANCE_DATA
	HKEY_USERS )],
    KEY_ =>	[qw(
	KEY_QUERY_VALUE		KEY_SET_VALUE		KEY_CREATE_SUB_KEY
	KEY_ENUMERATE_SUB_KEYS	KEY_NOTIFY		KEY_CREATE_LINK
	KEY_READ		KEY_WRITE		KEY_EXECUTE
	KEY_ALL_ACCESS),
	'KEY_DELETE',		# DELETE          (0x00010000L)
	'KEY_READ_CONTROL',	# READ_CONTROL    (0x00020000L)
	'KEY_WRITE_DAC',	# WRITE_DAC       (0x00040000L)
	'KEY_WRITE_OWNER',	# WRITE_OWNER     (0x00080000L)
	'KEY_SYNCHRONIZE',	# SYNCHRONIZE     (0x00100000L) (not used)
	],
    REG_ =>	[qw(
	REG_OPTION_RESERVED	REG_OPTION_NON_VOLATILE	REG_OPTION_VOLATILE
	REG_OPTION_CREATE_LINK	REG_OPTION_BACKUP_RESTORE
	REG_OPTION_OPEN_LINK	REG_LEGAL_OPTION	REG_CREATED_NEW_KEY
	REG_OPENED_EXISTING_KEY	REG_WHOLE_HIVE_VOLATILE	REG_REFRESH_HIVE
	REG_NO_LAZY_FLUSH	REG_NOTIFY_CHANGE_ATTRIBUTES
	REG_NOTIFY_CHANGE_NAME	REG_NOTIFY_CHANGE_LAST_SET
	REG_NOTIFY_CHANGE_SECURITY			REG_LEGAL_CHANGE_FILTER
	REG_NONE		REG_SZ			REG_EXPAND_SZ
	REG_BINARY		REG_DWORD		REG_DWORD_LITTLE_ENDIAN
	REG_DWORD_BIG_ENDIAN	REG_LINK		REG_MULTI_SZ
	REG_RESOURCE_LIST	REG_FULL_RESOURCE_DESCRIPTOR
	REG_RESOURCE_REQUIREMENTS_LIST )],
    SE_ =>	[qw(
	SE_ASSIGNPRIMARYTOKEN_NAME	SE_AUDIT_NAME
	SE_BACKUP_NAME			SE_CHANGE_NOTIFY_NAME
	SE_CREATE_PAGEFILE_NAME		SE_CREATE_PERMANENT_NAME
	SE_CREATE_TOKEN_NAME		SE_DEBUG_NAME
	SE_INCREASE_QUOTA_NAME		SE_INC_BASE_PRIORITY_NAME
	SE_LOAD_DRIVER_NAME		SE_LOCK_MEMORY_NAME
	SE_MACHINE_ACCOUNT_NAME		SE_PROF_SINGLE_PROCESS_NAME
	SE_REMOTE_SHUTDOWN_NAME		SE_RESTORE_NAME
	SE_SECURITY_NAME		SE_SHUTDOWN_NAME
	SE_SYSTEMTIME_NAME		SE_SYSTEM_ENVIRONMENT_NAME
	SE_SYSTEM_PROFILE_NAME		SE_TAKE_OWNERSHIP_NAME
	SE_TCB_NAME			SE_UNSOLICITED_INPUT_NAME )],
);
@EXPORT_OK= ();
{ my $ref;
    foreach $ref (  values(%EXPORT_TAGS)  ) {
	push( @EXPORT_OK, @$ref )   unless  $ref->[0] =~ /^SE_/;
    }
}
$EXPORT_TAGS{ALL}= [ @EXPORT_OK ];	# \@EXPORT_OK once SE_* settles down.
# push( @EXPORT_OK, "JHEREG_TACOSALAD" );	# Used to test Mkconst2perl
push( @EXPORT_OK, @{$EXPORT_TAGS{SE_}} );

bootstrap Win32API::Registry $VERSION;

# Preloaded methods go here.

# To convert C constants to Perl code in cRegistry.pc
# [instead of C or C++ code in cRegistry.h]:
#    * Modify F<Makefile.PL> to add WriteMakeFile() =>
#      CONST2PERL/postamble => [[ "Win32API::Registry" => ]] WRITE_PERL => 1.
#    * Either comment out C<#include "cRegistry.h"> from F<Registry.xs>
#      or make F<cRegistry.h> an empty file.
#    * Make sure the following C<if> block is not commented out.
#    * "nmake clean", "perl Makefile.PL", "nmake"

if(  ! defined &REG_NONE  ) {
    require "Win32API/Registry/cRegistry.pc";
}

# This would be convenient but inconsistant and hard to explain:
#push( @{$EXPORT_TAGS{ALL}}, @{$EXPORT_TAGS{SE_}} )
#  if  defined &SE_TCB_NAME;

sub regConstant
{
    my( $name )= @_;
    if(  1 != @_  ||  ! $name  ||  $name =~ /\W/  ) {
	require Carp;
	Carp::croak( 'Usage: ',__PACKAGE__,'::regConstant("CONST_NAME")' );
    }
    my $proto= prototype $name;
    if(  defined \&$name
     &&  defined $proto
     &&  "" eq $proto  ) {
	no strict 'refs';
	return &$name;
    }
    return undef;
}

# We provide this for backwards compatibility:
sub constant
{
    my( $name )= @_;
    my $value= regConstant( $name );
    if(  defined $value  ) {
	$!= 0;
	return $value;
    }
    $!= 11; # EINVAL
    return 0;
}

# BEGIN {
#     my $code= 'return _regLastError(@_)';
#     local( $!, $^E )= ( 1, 1 );
#     if(  $! ne $^E  ) {
# 	$code= '
# 	    local( $^E )= _regLastError(@_);
# 	    my $ret= $^E;
# 	    return $ret;
# 	';
#     }
#     eval "sub regLastError { $code }";
#     die "$@"   if  $@;
# }

package Win32API::Registry::_error;

use overload
    '""' => sub {
	require Win32 unless defined &Win32::FormatMessage;
	$_ = Win32::FormatMessage(Win32API::Registry::_regLastError());
	tr/\r\n//d;
	return $_;
    },
    '0+' => sub { Win32API::Registry::_regLastError() },
    'fallback' => 1;

sub new { return bless {}, shift }
sub set { Win32API::Registry::_regLastError($_[1]); return $_[0] }

package Win32API::Registry;

my $_error = new Win32API::Registry::_error;

sub regLastError {
    require Carp;
    Carp::croak('Usage: ',__PACKAGE__,'::regLastError( [$setWin32ErrCode] )') if @_ > 1;
    $_error->set($_[0]) if defined $_[0];
    return $_error;
}

# Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we
# need this next chunk to prevent Win32API::Registry->nonesuch() from
# looking for "nonesuch.al" and producing confusing error messages:
use vars qw($AUTOLOAD);
sub AUTOLOAD {
    require Carp;
    Carp::croak(
      "Can't locate method $AUTOLOAD via package Win32API::Registry" );
}

# Replace "&rout;" with "goto &rout;" when that is supported on Win32.

# Let user omit all buffer sizes:
sub RegEnumKeyExA {
    if(  6 == @_  ) {	splice(@_,4,0,[]);  splice(@_,2,0,[]);  }
    &_RegEnumKeyExA;
}
sub RegEnumKeyExW {
    if(  6 == @_  ) {	splice(@_,4,0,[]);  splice(@_,2,0,[]);  }
    &_RegEnumKeyExW;
}
sub RegEnumValueA {
    if(  6 == @_  ) {	splice(@_,2,0,[]);  push(@_,[]);  }
    &_RegEnumValueA;
}
sub RegEnumValueW {
    if(  6 == @_  ) {	splice(@_,2,0,[]);  push(@_,[]);  }
    &_RegEnumValueW;
}
sub RegQueryInfoKeyA {
    if(  11 == @_  ) {	splice(@_,2,0,[]);  }
    &_RegQueryInfoKeyA;
}
sub RegQueryInfoKeyW {
    if(  11 == @_  ) {	splice(@_,2,0,[]);  }
    &_RegQueryInfoKeyW;
}

sub RegEnumKeyA {
    push(@_,[])   if  3 == @_;
    &_RegEnumKeyA;
}
sub RegEnumKeyW {
    push(@_,[])   if  3 == @_;
    &_RegEnumKeyW;
}
sub RegGetKeySecurity {
    push(@_,[])   if  3 == @_;
    &_RegGetKeySecurity;
}
sub RegQueryMultipleValuesA {
    push(@_,[])   if  4 == @_;
    &_RegQueryMultipleValuesA;
}
sub RegQueryMultipleValuesW {
    push(@_,[])   if  4 == @_;
    &_RegQueryMultipleValuesW;
}
sub RegQueryValueA {
    push(@_,[])   if  3 == @_;
    &_RegQueryValueA;
}
sub RegQueryValueW {
    push(@_,[])   if  3 == @_;
    &_RegQueryValueW;
}
sub RegQueryValueExA {
    push(@_,[])   if  5 == @_;
    &_RegQueryValueExA;
}
sub RegQueryValueExW {
    push(@_,[])   if  5 == @_;
    &_RegQueryValueExW;
}
sub RegSetValueA {
    push(@_,0)   if  4 == @_;
    &_RegSetValueA;
}
sub RegSetValueW {
    push(@_,0)   if  4 == @_;
    &_RegSetValueW;
}
sub RegSetValueExA {
    push(@_,0)   if  5 == @_;
    &_RegSetValueExA;
}
sub RegSetValueExW {
    push(@_,0)   if  5 == @_;
    &_RegSetValueExW;
}

# Aliases for non-Unicode functions:
sub AbortSystemShutdown		{ &AbortSystemShutdownA; }
sub InitiateSystemShutdown	{ &InitiateSystemShutdownA; }
sub RegConnectRegistry		{ &RegConnectRegistryA; }
sub RegCreateKey		{ &RegCreateKeyA; }
sub RegCreateKeyEx		{ &RegCreateKeyExA; }
sub RegDeleteKey		{ &RegDeleteKeyA; }
sub RegDeleteValue		{ &RegDeleteValueA; }
sub RegEnumKey			{ &RegEnumKeyA; }
sub RegEnumKeyEx		{ &RegEnumKeyExA; }
sub RegEnumValue		{ &RegEnumValueA; }
sub RegLoadKey			{ &RegLoadKeyA; }
sub RegOpenKey			{ &RegOpenKeyA; }
sub RegOpenKeyEx		{ &RegOpenKeyExA; }
sub RegQueryInfoKey		{ &RegQueryInfoKeyA; }
sub RegQueryMultipleValues	{ &RegQueryMultipleValuesA; }
sub RegQueryValue		{ &RegQueryValueA; }
sub RegQueryValueEx		{ &RegQueryValueExA; }
sub RegReplaceKey		{ &RegReplaceKeyA; }
sub RegRestoreKey		{ &RegRestoreKeyA; }
sub RegSaveKey			{ &RegSaveKeyA; }
sub RegSetValue			{ &RegSetValueA; }
sub RegSetValueEx		{ &RegSetValueExA; }
sub RegUnLoadKey		{ &RegUnLoadKeyA; }

1;
__END__

=head1 NAME

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

=head1 SYNOPSIS

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

  RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key );
    or  die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
	    regLastError(),"\n";
  RegQueryValueEx( $key, "Information", [], $type, $data, [] );
    or  die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: ",
	    regLastError(),"\n";
  [...]
  RegCloseKey( $key )
    or  die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
	    regLastError(),"\n";

=head1 DESCRIPTION

This provides fairly low-level access to the Win32 System API
calls dealing with the Registry [mostly from WINREG.H].  This
is mostly intended to be used by other modules such as
C<Win32::TieRegistry> [which provides an extremely Perl-friendly
method for using the Registry].

For a description of the logical structure of the Registry, see
the documentation for the C<Win32::TieRegistry> module.

To pass in C<NULL> as the pointer to an optional buffer, pass in
an empty list reference, C<[]>.

Beyond raw access to the API calls and related constants, this module
handles smart buffer allocation and translation of return codes.

All calls return a true value for success and a false value for
failure.  After any failure, C<$^E> should automatically be set
to indicate the reason.  However, current versions of Perl often
overwrite C<$^E> too quickly, so you can use C<regLastError()>
instead, which is only set by Win32API::Registry routines.

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

=head2 Exports

Nothing is exported by default.  The following tags can be used to
have sets of symbols exported.

[Note that much of the following documentation refers to the
behavior of the underlying API calls which may vary in current
and future versions of the Win32 API without any changes to this
module.  Therefore you should check the Win32 API documentation
directly when needed.]

=over

=item :Func

The basic function names:

=over

=item AllowPriv

=item C<AllowPriv( $sPrivName, $bEnable )>

Not a Win32 API call.  Enables or disables a specific privilege for
the current process.  Returns a true value if successful and a false
value [and sets C<$^E>/C<regLastError()>] on failure.  This routine
does not provide a way to tell if a privilege is currently enabled.

C<$sPrivname> is a Win32 privilege name [see L</:SE_>].  For example,
C<"SeBackupPrivilege"> [a.k.a. C<SE_BACKUP_NAME>] controls whether
you can use C<RegSaveKey()> and C<"SeRestorePrivilege"> [a.k.a.
C<SE_RESTORE_NAME>] controls whether you can use C<RegLoadKey()>.

If C<$bEnable> is true, then C<AllowPriv()> tries to enable the
privilege.  Otherwise it tries to disable the privilege.

=item AbortSystemShutdown

=item C<AbortSystemShutdown( $sComputerName )>

Tries to abort a remote shutdown request previously made via
C<InitiateSystemShutdown()>.  Returns a true value if successful
and a false value [and sets C<$^E>/C<regLastError()>] on failure.

=item InitiateSystemShutdown

=item C<InitiateSystemShutdown( $sComputer, $sMessage, $uTimeoutSecs, $bForce, $bReboot )>

Requests that a [remote] computer be shutdown or rebooted.
Returns a true value if successful and a false value [and
sets C<$^E>/C<regLastError()>] on failure.

C<$sComputer> is the name [or address] of the computer to be
shutdown or rebooted.  You can use C<[]> [for C<NULL>] or C<"">
to indicate the local computer.

C<$sMessage> is the message to be displayed in a pop-up window
on the desktop of the computer to be shutdown or rebooted until
the timeout expires or the shutdown is aborted via
C<AbortSystemShutdown()>.  With C<$iTimeoutSecs == 0>, the
message will never be visible.

C<$iTimeoutSecs> is the number of seconds to wait before starting
the shutdown.

If C<$bForce> is false, then any applications running on the remote
computer get a chance to prompt the remote user whether they want
to save changes.  Also, for any applications that do not exit quickly
enough, the operating system will prompt the user whether they wish
to wait longer for the application to exit or force it to exit now.
At any of these prompts the user can press B<CANCEL> to abort the
shutdown but if no applications have unsaved data, they will likely
all exit quickly and the shutdown will progress with the remote user
having no option to cancel the shutdown.

If C<$bForce> is true, all applications are told to exit immediately
and so will not prompt the user even if there is unsaved data.  Any
applications that take too long to exit will be forcibly killed after
a short time.  The only way to abort the shutdown is to call
C<AbortSystemShutdown()> before the timeout expires and there is no
way to abort the shutdown once it has begun.

If C<$bReboot> is true, the computer will automatically reboot once
the shutdown is complete.  If C<$bReboot> is false, then when the
shutdown is complete the computer will halt at a screen indicating
that the shutdown is complete and offering a way for the user to
start to boot the computer.

You must have the C<"SeRemoteShutdownPrivilege"> privilege
on the remote computer for this call to succeed.  If shutting
down the local computer, then the calling process must have
the C<"SeShutdownPrivilege"> privilege and have it enabled.

=item RegCloseKey

=item C<RegCloseKey( $hKey )>

Closes the handle to a Registry key returned by C<RegOpenKeyEx()>,
C<RegConnectRegistry()>, C<RegCreateKeyEx()>, or a few other
routines.  Returns a true value if successful and a false value
[and sets C<$^E>/C<regLastError()>] on failure.

=item RegConnectRegistry

=item C<RegConnectRegistry( $sComputer, $hRootKey, $ohKey )>

Connects to one of the root Registry keys of a remote computer.
Returns a true value if successful and a false value [and
sets C<$^E>/C<regLastError()>] on failure.

C<$sComputer> is the name [or address] of a remote computer
whose Registry you wish to access.

C<$hKey> must be either C<HKEY_LOCAL_MACHINE> or C<HKEY_USERS>
and specifies which root Registry key on the remote computer
you wish to have access to.

C<$phKey> will be set to the handle to be used to access the
remote Registry key if the call succeeds.

=item regConstant

=item C<$value= regConstant( $sConstantName )>

Fetch the value of a constant.  Returns C<undef> if C<$sConstantName>
is not the name of a constant supported by this module.  Never sets
C<$!> nor C<$^E>.

This function is rarely used since you will usually get the value of a
constant by having that constant imported into your package by listing
the constant name in the C<use Win32API::Registry> statement and then
simply using the constant name in your code [perhaps followed by
C<()>].  This function is useful for verifying constant names not in
Perl code, for example, after prompting a user to type in a constant
name.

=item RegCreateKey

=item C<RegCreateKey( $hKey, $sSubKey, $ohSubKey )>

This routine is meant only for compatibility with Windows version
3.1.  Use C<RegCreateKeyEx()> instead.

=item RegCreateKeyEx

=item C<RegCreateKeyEx( $hKey, $sSubKey, $uZero, $sClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>

Creates a new Registry subkey.  Returns a true value if successful and
a false value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sSubKey> is the name of the new subkey to be created.

C<$iZero> is reserved for future use and should always be specified
as C<0>.

C<$sClass> is a string to be used as the class for the new
subkey.  We are not aware of any current use for Registry key
class information so the empty string, C<"">, should usually
be used here.

C<$iOpts> is a numeric value containing bits that control options
used while creating the new subkey.  C<REG_OPTION_NON_VOLATILE>
is the default.  C<REG_OPTION_VOLATILE> [which is ignored on
Windows 95] means the data stored under this key is not kept
in a file and will not be preserved when the system reboots.
C<REG_OPTION_BACKUP_RESTORE> [also ignored on Windows 95] means
ignore the C<$iAccess> parameter and try to open the new key with
the access required to backup or restore the key.

C<$iAccess> is a numeric mask of bits specifying what type of
access is desired when opening the new subkey.  See C<RegOpenKeyEx()>.

C<$pSecAttr> is a C<SECURITY_ATTRIBUTES> structure packed into
a Perl string which controls whether the returned handle can be
inherited by child processes.  Normally you would pass C<[]> for
this parameter to have C<NULL> passed to the underlying API
indicating that the handle cannot be inherited.  If not under
Windows95, then C<$pSecAttr> also allows you to specify
C<SECURITY_DESCRIPTOR> that controls which users will have
what type of access to the new key -- otherwise the new key
inherits its security from its parent key.

C<$phKey> will be set to the handle to be used to access the new
subkey if the call succeeds.

C<$piDisp> will be set to either C<REG_CREATED_NEW_KEY> or
C<REG_OPENED_EXISTING_KEY> to indicate for which reason the
call succeeded.  Can be specified as C<[]> if you don't care.

If C<$phKey> and C<$piDisp> start out as integers, then they will
probably remain unchanged if the call fails.

=item RegDeleteKey

=item C<RegDeleteKey( $hKey, $sSubKey )>

Deletes a subkey of an open Registry key provided that the subkey
contains no subkeys of its own [but the subkey may contain values].
Returns a true value if successful and a false value [and sets
C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sSubKey> is the name of the subkey to be deleted.

=item RegDeleteValue

=item C<RegDeleteValue( $hKey, $sValueName )>

Deletes a value from an open Registry key.  Returns a true value if
successful and a false value [and sets C<$^E>/C<regLastError()>] on
failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sValueKey> is the name of the value to be deleted.

=item RegEnumKey

=item C<RegEnumKey( $hKey, $uIndex, $osName, $ilNameSize )>

This routine is meant only for compatibility with Windows version
3.1.  Use C<RegEnumKeyEx()> instead.

=item RegEnumKeyEx

=item C<RegEnumKeyEx( $hKey, $uIndex, $osName, $iolName, $pNull, $osClass, $iolClass, $opftLastWrite )>

Lets you enumerate the names of all of the subkeys directly under
an open Registry key.  Returns a true value if successful and a false
value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$iIndex> is the sequence number of the immediate subkey that
you want information on.  Start with this value as C<0> then
repeat the call incrementing this value each time until the
call fails with C<$^E>/C<regLastError()> numerically equal to
C<ERROR_NO_MORE_ITEMS>.

C<$sName> will be set to the name of the subkey.  Can be C<[]> if
you don't care about the name.

C<$plName> initially specifies the [minimum] buffer size to be
allocated for C<$sName>.  Will be set to the length of the subkey
name if the requested subkey exists even if C<$sName> isn't
successfully set to the subkey name.  See L<Buffer sizes> for
more information.

C<$pNull> is reserved for future used and should be passed as C<[]>.

C<$sClass> will be set to the class name for the subkey.  Can be
C<[]> if you don't care about the class.

C<$plClass> initially specifies the [minimum] buffer size to be
allocated for C<$sClass> and will be set to the length of the
subkey class name if the requested subkey exists.  See L<Buffer
sizes> for more information.

C<$pftLastWrite> will be set to a C<FILETIME> structure packed
into a Perl string and indicating when the subkey was last changed.
Can be C<[]>.

You may omit both C<$plName> and C<$plClass> to get the same effect
as passing in C<[]> for each of them.

=item RegEnumValue

=item C<RegEnumValue( $hKey, $uIndex, $osValName, $iolValName, $pNull, $ouType, $opValData, $iolValData )>

Lets you enumerate the names of all of the values contained in an
open Registry key.  Returns a true value if successful and a false
value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$iIndex> is the sequence number of the value that you want
information on.  Start with this value as C<0> then repeat the
call incrementing this value each time until the call fails with
C<ERROR_NO_MORE_ITEMS>.

C<$sValName> will be set to the name of the value.  Can be C<[]>
if you don't care about the name.

C<$plValName> initially specifies the [minimum] buffer size to be
allocated for C<$sValName>.  Will be set to the length of the value
name if the requested value exists even if C<$sValName> isn't
successfully set to the value name.  See L<Buffer sizes> for
more information.

C<$pNull> is reserved for future used and should be passed as C<[]>.

C<$piType> will be set to the type of data stored in the value data.
If the call succeeds, it will be set to a C<REG_*> value unless
passed in as C<[]>.

C<$pValData> will be set to the data [packed into a Perl string]
that is stored in the requested value.  Can be C<[]> if you don't
care about the value data.

C<$plValData> initially specifies the [minimum] buffer size to be
allocated for C<$sValData> and will be set to the length of the
value data if the requested value exists.  See L<Buffer sizes> for
more information.

You may omit both C<$plValName> and C<$plValData> to get the same
effect as passing in C<[]> for each of them.

=item RegFlushKey

=item C<RegFlushKey( $hKey )>

Forces the data stored under an open Registry key to be flushed
to the disk file where the data is preserved between reboots.
Forced flushing is not guaranteed to be efficient so this routine
should almost never be called.  Returns a true value if successful
and a false value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

=item RegGetKeySecurity

=item C<RegGetKeySecurity( $hKey, $uSecInfo, $opSecDesc, $iolSecDesc )>

Retrieves one of the C<SECURITY_DESCRIPTOR> structures describing
part of the security for an open Registry key.  Returns a true value
if successful and a false value [and sets C<$^E>/C<regLastError()>]
on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$iSecInfo> is a numeric C<SECURITY_INFORMATION> value that
specifies which parts of the C<SECURITY_DESCRIPTOR> structure
to retrieve.  Should be C<OWNER_SECURITY_INFORMATION>,
C<GROUP_SECURITY_INFORMATION>, C<DACL_SECURITY_INFORMATION>, or
or C<SACL_SECURITY_INFORMATION> or two or more of these bits
combined using C<|>.

C<$pSecDesc> will be set to the requested C<SECURITY_DESCRIPTOR>
structure [packed into a Perl string].

C<$plSecDesc> initially specifies the [minimum] buffer size to be
allocated for C<$sSecDesc> and will be set to the length of the
security descriptor.  See L<Buffer sizes> for more information.
You may omit this parameter to get the same effect as passing in
C<[]> for it.

=item regLastError

=item C<$svError= regLastError();>

=item C<regLastError( $uError );>

Returns the last error encountered by a routine from this module. 
It is just like C<$^E> except it isn't changed by anything except
routines from this module.  Ideally you could just use C<$^E>, but
current versions of Perl often overwrite C<$^E> before you get a
chance to check it and really old versions of Perl don't really
support C<$^E> under Win32.

Just like C<$^E>, in a numeric context C<regLastError()> returns
the numeric error value while in a string context it returns a
text description of the error [actually it returns a Perl scalar
that contains both values so C<$x= regLastError()> causes C<$x>
to give different values in string vs. numeric contexts].

The last form sets the error returned by future calls to
C<regLastError()> and should not be used often.  C<$uError> must
be a numeric error code.  Also returns the dual-valued version
of C<$uError>.

=item RegLoadKey

=item C<RegLoadKey( $hKey, $sSubKey, $sFileName )>

Loads a hive file.  That is, it creates a new subkey in the
Registry and associates that subkey with a disk file that contains
a Registry hive so that the new subkey can be used to access the
keys and values stored in that hive.  Hives are usually created
via C<RegSaveKey()>.  Returns a true value if successful and a
false value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key that can have hives
loaded to it.  This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
or a remote version of one of these from a call to
C<RegConnectRegistry()>.

C<$sSubKey> is the name of the new subkey to created and associated
with the hive file.

C<$sFileName> is the name of the hive file to be loaded.  This
file name is interpretted relative to the
C<%SystemRoot%/System32/config> directory on the computer where
the C<$hKey> key resides.  If C<$sFileName> is on a FAT file
system, then its name must not have an extension.

You must have the C<SE_RESTORE_NAME> privilege to use this routine.

WARNING:  Loading of hive files via a network share may silently
corrupt the hive and so should not be attempted [this is a problem
in at least some versions of the underlying API which this module
does not try to fix or avoid].  To access a hive file located on a
remote computer, connect to the remote computer's Registry and load
the hive via that.

=item RegNotifyChangeKeyValue

=item C<RegNotifyChangeKeyValue( $hKey, $bWatchSubtree, $uNotifyFilter, $hEvent, $bAsync )>

Arranges for your process to be notified when part of the Registry
is changed.  Returns a true value if successful and a false value
[and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call] for which you wish to be notified when any changes
are made to it.

If C<$bWatchSubtree> is true, then changes to any subkey or
descendant of C<$hKey> are also reported.

C<$iNotifyFilter> controllers what types of changes are reported.  It
is a numeric value containing one or more of the following bit masks:

=over

=item C<REG_NOTIFY_CHANGE_NAME>

Notify if a subkey is added or deleted to a monitored key.

=item C<REG_NOTIFY_CHANGE_LAST_SET>

Notify if a value in a monitored key is added, deleted, or modified.

=item C<REG_NOTIFY_CHANGE_SECURITY>

Notify if a security descriptor of a monitored key is changed.

=item C<REG_NOTIFY_CHANGE_ATTRIBUTES>

Notify if any attributes of a monitored key are changed [class
name or security descriptors].

=back

C<$hEvent> is ignored unless C<$bAsync> is true.  Otherwise, C<$hEvent>
is a handle to a Win32 I<event> that will be signaled when changes are
to be reported.

If C<$bAsync> is true, then C<RegNotifyChangeKeyValue()> returns
immediately and uses C<$hEvent> to notify your process of changes.
If C<$bAsync> is false, then C<RegNotifyChangeKeyValue()> does
not return until there is a change to be notified of.

This routine does not work with Registry keys on remote computers.

=item RegOpenKey

=item C<RegOpenKey( $hKey, $sSubKey, $ohSubKey )>

This routine is meant only for compatibility with Windows version
3.1.  Use C<RegOpenKeyEx()> instead.

=item RegOpenKeyEx

=item C<RegOpenKeyEx( $hKey, $sSubKey, $uOptions, $uAccess, $ohSubKey )>

Opens an existing Registry key.  Returns a true value if successful
and a false value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sSubKey> is the name of an existing subkey to be opened.
Can be C<""> or C<[]> to open an additional handle to the
key specified by C<$hKey>.

C<$iOptions> is a numeric value containing bits that control options
used while opening the subkey.  There are currently no supported
options so this parameter should be specified as C<0>.

C<$iAccess> is a numeric mask of bits specifying what type of
access is desired when opening the new subkey.  Should be a
combination of one or more of the following bit masks:

=over

=item C<KEY_ALL_ACCESS>

    KEY_READ | KEY_WRITE | KEY_CREATE_LINK

=item C<KEY_READ>

    KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ

=item C<KEY_WRITE>

    KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE

=item C<KEY_QUERY_VALUE>

=item C<KEY_SET_VALUE>

=item C<KEY_ENUMERATE_SUB_KEYS>

=item C<KEY_CREATE_SUB_KEY>

=item C<KEY_NOTIFY>

Allows you to use C<RegNotifyChangeKeyValue()> on the opened key.

=item C<KEY_EXECUTE>

Same as C<KEY_READ>.

=item C<KEY_CREATE_LINK>

Gives you permission to create a symbolic link like
C<HKEY_CLASSES_ROOT> and C<HKEY_CURRENT_USER>, though the method for
doing so is not documented [and probably requires use of the mostly
undocumented "native" routines, C<Nt*()> a.k.a. C<Zw*()>].

=back

C<$phKey> will be set to the handle to be used to access the new subkey
if the call succeeds.

=item RegQueryInfoKey

=item C<RegQueryInfoKey( $hKey, $osClass, $iolClass, $pNull, $ocSubKeys, $olSubKey, $olSubClass, $ocValues, $olValName, $olValData, $olSecDesc, $opftTime )>

Gets miscellaneous information about an open Registry key.
Returns a true value if successful and a false value [and
sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sClass> will be set to the class name for the key.  Can be
C<[]> if you don't care about the class.

C<$plClass> initially specifies the [minimum] buffer size to be
allocated for C<$sClass> and will be set to the length of the
key's class name.  See L<Buffer sizes> for more information.
You may omit this parameter to get the same effect as passing in
C<[]> for it.

C<$pNull> is reserved for future use and should be passed as C<[]>.

C<$pcSubKeys> will be set to the count of the number of subkeys
directly under this key.  Can be C<[]>.

C<$plSubKey> will be set to the length of the longest subkey name.
Can be C<[]>.

C<$plSubClass> will be set to the length of the longest class name
used with an immediate subkey of this key.  Can be C<[]>.

C<$pcValues> will be set to the count of the number of values in
this key.  Can be C<[]>.

C<$plValName> will be set to the length of the longest value name
in this key.  Can be C<[]>.

C<$plValData> will be set to the length of the longest value data
in this key.  Can be C<[]>.

C<$plSecDesc> will be set to the length of this key's full security
descriptor.

C<$pftTime> will be set to a C<FILETIME> structure packed
into a Perl string and indicating when this key was last changed.
Can be C<[]>.

=item RegQueryMultipleValues

=item C<RegQueryMultipleValues( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>

Allows you to use a single call to query several values from a single
open Registry key to maximize efficiency.  Returns a true value if
successful and a false value [and sets C<$^E>/C<regLastError()>] on
failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$pValueEnts> should contain a list of C<VALENT> structures packed
into a single Perl string.  Each C<VALENT> structure should have
the C<ve_valuename> entry [the first 4 bytes] pointing to a string
containing the name of a value stored in this key.  The remaining
fields are set if the function succeeds.

C<$cValueEnts> should contain the count of the number of C<VALENT>
structures contained in C<$pValueEnts>.

C<$pBuffer> will be set to the data from all of the requested values
concatenated into a single Perl string.

C<$plBuffer> initially specifies the [minimum] buffer size to be
allocated for C<$sBuffer> and will be set to the total length of
the data to be written to C<$sBuffer>.  See L<Buffer sizes> for
more information.  You may omit this parameter to get the same
effect as passing in C<[]> for it.

Here is sample code to populate C<$pValueEnts>:

    # @ValueNames= ...list of value name strings...;
    $cValueEnts= @ValueNames;
    $pValueEnts= pack( " p x4 x4 x4 " x $cValueEnts, @ValueNames );

Here is sample code to retrieve the data type and data length
returned in C<$pValueEnts>:

    @Lengths= unpack( " x4 L x4 x4 " x $cValueEnts, $pValueEnts );
    @Types=   unpack( " x4 x4 x4 L " x $cValueEnts, $pValueEnts );

Given the above, and assuming you haven't modified C<$sBuffer> since
the call, you can also extract the value data strings from C<$sBuffer>
by using the pointers returned in C<$pValueEnts>:

    @Data=    unpack(  join( "", map {" x4 x4 P$_ x4 "} @Lengths ),
    		$pValueEnts  );

Much better is to use the lengths and extract directly from
C<$sBuffer> using C<unpack()> [or C<substr()>]:

    @Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );

=item RegQueryValue

=item C<RegQueryValue( $hKey, $sSubKey, $osValueData, $iolValueData )>

This routine is meant only for compatibility with Windows version
3.1.  Use C<RegQueryValueEx()> instead.  This routine can only
query unamed values [a.k.a. "default values"], that is, values with
a name of C<"">.

=item RegQueryValueEx

=item C<RegQueryValueEx( $hKey, $sValueName, $pNull, $ouType, $opValueData, $iolValueData )>

Lets you look up value data stored in an open Registry key by
specifying the value name.  Returns a true value if successful
and a false value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sValueName> is the name of the value whose data you wish to
retrieve.

C<$pNull> this parameter is reserved for future use and should be
specified as C<[]>.

C<$piType> will be set to indicate what type of data is stored in
the named value.  Will be set to a C<REG_*> value if the function
succeeds.

C<$pValueData> will be set to the value data [packed into a Perl
string] that is stored in the named value.  Can be C<[]> if you
don't care about the value data.

C<$plValueData> initially specifies the [minimum] buffer size to be
allocated for C<$sValueData> and will be set to the size [always
in bytes] of the data to be written to C<$sValueData>, even if
C<$sValueData> is not successfully written to.  See L<Buffer sizes>
for more information.

=item RegReplaceKey

=item C<RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )>

Lets you replace an entire hive when the system is next booted. 
Returns a true value if successful and a false value [and sets
C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key that has hive(s)
loaded in it.  This must be C<HKEY_LOCAL_MACHINE>,
C<HKEY_USERS>, or a remote version of one of these from
a call to C<RegConnectRegistry()>.

C<$sSubKey> is the name of the subkey of C<$hKey> whose hive
you wish to have replaced on the next reboot.

C<$sNewFile> is the name of a file that will replace the existing
hive file when the system reboots.

C<$sOldFile> is the file name to save the current hive file to
when the system reboots.

C<$sNewFile> and C<$sOldFile> are interpretted relative to the
C<%SystemRoot%/System32/config> directory on the computer where
the C<$hKey> key resides [I think].  If either file is [would be]
on a FAT file system, then its name must not have an extension.

You must have the C<SE_RESTORE_NAME> privilege to use this routine.

=item RegRestoreKey

=item C<RegRestoreKey( $hKey, $sFileName, $uFlags )>

Reads in a hive file and copies its contents over an existing
Registry tree.  Returns a true value if successful and a false
value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sFileName> is the name of the hive file to be read.  For each
value and subkey in this file, a value or subkey will be added
or replaced in C<$hKey>.

C<$uFlags> is usally C<0>.  It can also be C<REG_WHOLE_HIVE_VOLATILE>
which, rather than copying the hive over the existing key,
replaces the existing key with a temporary, memory-only Registry
key and then copies the hive contents into it.  This option only
works if C<$hKey> is C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>, or a
remote version of one of these from a call to C<RegConnectRegistry()>.

C<RegRestoreKey> does I<not> delete values nor keys from the
existing Registry tree when there is no corresponding value/key
in the hive file.

=item RegSaveKey

=item C<RegSaveKey( $hKey, $sFileName, $pSecAttr )>

Dumps any open Registry key and all of its subkeys and values into
a new hive file.  Returns a true value if successful and a false
value [and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sFileName> is the name of the file that the Registry tree
should be saved to.  It is interpretted relative to the
C<%SystemRoot%/System32/config> directory on the computer where
the C<$hKey> key resides.  If C<$sFileName> is on a FAT file system,
then it must not have an extension.

C<$pSecAttr> contains a C<SECURITY_ATTRIBUTES> structure that specifies
the permissions to be set on the new file that is created.  This can
be C<[]>.

You must have the C<SE_RESTORE_NAME> privilege to use this routine.

=item RegSetKeySecurity

=item C<RegSetKeySecurity( $hKey, $uSecInfo, $pSecDesc )>

Sets [part of] the C<SECURITY_DESCRIPTOR> structure describing part
of the security for an open Registry key.  Returns a true value if
successful and a false value [and sets C<$^E>/C<regLastError()>] on
failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$uSecInfo> is a numeric C<SECURITY_INFORMATION> value that
specifies which C<SECURITY_DESCRIPTOR> structure to set.  Should
be C<OWNER_SECURITY_INFORMATION>, C<GROUP_SECURITY_INFORMATION>,
C<DACL_SECURITY_INFORMATION>, or C<SACL_SECURITY_INFORMATION>
or two or more of these bits combined using C<|>.

C<$pSecDesc> contains the new C<SECURITY_DESCRIPTOR> structure
packed into a Perl string.

=item RegSetValue

=item C<RegSetValue( $hKey, $sSubKey, $uType, $sValueData, $lValueData )>

This routine is meant only for compatibility with Windows version
3.1.  Use C<RegSetValueEx()> instead.  This routine can only
set unamed values [a.k.a. "default values"].

=item RegSetValueEx

=item C<RegSetValueEx( $hKey, $sName, $uZero, $uType, $pData, $lData )>

Adds or replaces a value in an open Registry key.  Returns
a true value if successful and a false value [and sets
C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
a previous call].

C<$sName> is the name of the value to be set.

C<$uZero> is reserved for future use and should be specified as C<0>.

C<$uType> is the type of data stored in C<$pData>.  It should
be a C<REG_*> value.

C<$pData> is the value data packed into a Perl string.

C<$lData> is the length of the value data that is stored in C<$pData>.
You will usually omit this parameter or pass in C<0> to have
C<length($pData)> used.  In both of these cases, if C<$iType> is
C<REG_SZ> or C<REG_EXPAND_SZ>, C<RegSetValueEx()> will append a
trailing C<'\0'> to the end of C<$pData> [unless there is already
one].

=item RegUnLoadKey

=item C<RegUnLoadKey( $hKey, $sSubKey )>

Unloads a previously loaded hive file.  That is, closes the
hive file then deletes the subkey that was providing access
to it.  Returns a true value if successful and a false value
[and sets C<$^E>/C<regLastError()>] on failure.

C<$hKey> is the handle to a Registry key that has hives
loaded in it.  This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
or a remote version of one of these from a call to
C<RegConnectRegistry()>.

C<$sSubKey> is the name of the subkey whose hive you wish to
have unloaded.

=item :FuncA

The ASCII-specific function names.

Each of these is identical to the version listed above without the
trailing "A":

	AbortSystemShutdownA	InitiateSystemShutdownA
	RegConnectRegistryA	RegCreateKeyA		RegCreateKeyExA
	RegDeleteKeyA		RegDeleteValueA		RegEnumKeyA
	RegEnumKeyExA		RegEnumValueA		RegLoadKeyA
	RegOpenKeyA		RegOpenKeyExA		RegQueryInfoKeyA
	RegQueryMultipleValuesA	RegQueryValueA		RegQueryValueExA
	RegReplaceKeyA		RegRestoreKeyA		RegSaveKeyA
	RegSetValueA		RegSetValueExA		RegUnLoadKeyA

=item :FuncW

The UNICODE-specific function names.  These are the same as the
versions listed above without the trailing "W" except that string
parameters are UNICODE strings rather than ASCII strings, as
indicated.

=item AbortSystemShutdownW

=item C<AbortSystemShutdownW( $swComputerName )>

C<$swComputerName> is UNICODE.

=item InitiateSystemShutdownW

=item C<InitiateSystemShutdownW( $swComputer, $swMessage, $uTimeoutSecs, $bForce, $bReboot )>

C<$swComputer> and C<$swMessage> are UNICODE.

=item RegConnectRegistryW

=item C<RegConnectRegistryW( $swComputer, $hRootKey, $ohKey )>

C<$swComputer> is UNICODE.

=item RegCreateKeyW

=item C<RegCreateKeyW( $hKey, $swSubKey, $ohSubKey )>

C<$swSubKey> is UNICODE.

=item RegCreateKeyExW

=item C<RegCreateKeyExW( $hKey, $swSubKey, $uZero, $swClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>

C<$swSubKey> and C<$swClass> are UNICODE.

=item RegDeleteKeyW

=item C<RegDeleteKeyW( $hKey, $swSubKey )>

C<$swSubKey> is UNICODE.

=item RegDeleteValueW

=item C<RegDeleteValueW( $hKey, $swValueName )>

C<$swValueName> is UNICODE.

=item RegEnumKeyW

=item C<RegEnumKeyW( $hKey, $uIndex, $oswName, $ilwNameSize )>

C<$oswName> is UNICODE and C<$ilwNameSize> is measured as number of
C<WCHAR>s.

=item RegEnumKeyExW

=item C<RegEnumKeyExW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $oswClass, $iolwClass, $opftLastWrite )>

C<$swName> and C<$swClass> are UNICODE and C<$iolwName> and C<$iolwClass>
are measured as number of C<WCHAR>s.

=item RegEnumValueW

=item C<RegEnumValueW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $ouType, $opData, $iolData )>

C<$oswName> is UNICODE and C<$iolwName> is measured as number
of C<WCHAR>s.

C<$opData> is UNICODE if C<$piType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
or C<REG_MULTI_SZ>.  Note that C<$iolData> is measured as number
of bytes even in these cases.

=item RegLoadKeyW

=item C<RegLoadKeyW( $hKey, $swSubKey, $swFileName )>

C<$swSubKey> and C<$swFileName> are UNICODE.

=item RegOpenKeyW

=item C<RegOpenKeyW( $hKey, $swSubKey, $ohSubKey )>

C<$swSubKey> is UNICODE.

=item RegOpenKeyExW

=item C<RegOpenKeyExW( $hKey, $swSubKey, $uOptions, $uAccess, $ohSubKey )>

C<$swSubKey> is UNICODE.

=item RegQueryInfoKeyW

=item C<RegQueryInfoKeyW( $hKey, $oswClass, $iolwClass, $pNull, $ocSubKeys, $olwSubKey, $olwSubClass, $ocValues, $olwValName, $olValData, $olSecDesc, $opftTime )>

C<$swClass> is UNICODE.  C<$iolwClass>, C<$olwSubKey>, C<$olwSubClass>,
and C<$olwValName> are measured as number of C<WCHAR>s.  Note that
C<$olValData> is measured as number of bytes.

=item RegQueryMultipleValuesW

=item C<RegQueryMultipleValuesW( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>

The C<ve_valuename> fields of the C<VALENT> [actually C<VALENTW>]
structures in C<$ioarValueEnts> are UNICODE.  Values of type C<REG_SZ>,
C<REG_EXPAND_SZ>, and C<REG_MULTI_SZ> are written to C<$opBuffer>
in UNICODE.  Note that C<$iolBuffer> and the C<ve_valuelen> fields
of the C<VALENT> [C<VALENTW>] structures are measured as number of
bytes.

=item RegQueryValueW

=item C<RegQueryValueW( $hKey, $swSubKey, $oswValueData, $iolValueData )>

C<$swSubKey> and C<$oswValueData> are UNICODE.  Note that
C<$iolValueData> is measured as number of bytes.

=item RegQueryValueExW

=item C<RegQueryValueExW( $hKey, $swName, $pNull, $ouType, $opData, $iolData )>

C<$swName> is UNICODE.

C<$opData> is UNICODE if C<$ouType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
or C<REG_MULTI_SZ>.  Note that C<$iolData> is measured as number of
bytes even in these cases.

=item RegReplaceKeyW

=item C<RegReplaceKeyW( $hKey, $swSubKey, $swNewFile, $swOldFile )>

C<$swSubKey>, C<$swNewFile>, and C<$swOldFile> are UNICODE.

=item RegRestoreKeyW

=item C<RegRestoreKeyW( $hKey, $swFileName, $uFlags )>

C<$swFileName> is UNICODE.

=item RegSaveKeyW

=item C<RegSaveKeyW( $hKey, $swFileName, $pSecAttr )>

C<$swFileName> is UNICODE.

=item RegSetValueW

=item C<RegSetValueW( $hKey, $swSubKey, $uType, $swValueData, $lValueData )>

C<$swSubKey> and C<$swValueData> are UNICODE.  Note that
C<$lValueData> is measured as number of bytes even though
C<$swValueData> is always UNICODE.

=item RegSetValueExW

=item C<RegSetValueExW( $hKey, $swName, $uZero, $uType, $pData, $lData )>

C<$swName> is UNICODE.

C<$pData> is UNICODE if C<$uType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
or C<REG_MULTI_SZ>.  Note that C<$lData> is measured as number of
bytes even in these cases.

=item RegUnLoadKeyW

=item C<RegUnLoadKeyW( $hKey, $swSubKey )>

C<$swSubKey> is UNICODE.

=item :HKEY_

All C<HKEY_*> constants:

	HKEY_CLASSES_ROOT	HKEY_CURRENT_CONFIG	HKEY_CURRENT_USER
	HKEY_DYN_DATA		HKEY_LOCAL_MACHINE	HKEY_PERFORMANCE_DATA
	HKEY_USERS

=item :KEY_

All C<KEY_*> constants:

	KEY_QUERY_VALUE		KEY_SET_VALUE		KEY_CREATE_SUB_KEY
	KEY_ENUMERATE_SUB_KEYS	KEY_NOTIFY		KEY_CREATE_LINK
	KEY_READ		KEY_WRITE		KEY_EXECUTE
	KEY_ALL_ACCESS

=item :REG_

All C<REG_*> constants:

	REG_CREATED_NEW_KEY		REG_OPENED_EXISTING_KEY

	REG_LEGAL_CHANGE_FILTER		REG_NOTIFY_CHANGE_ATTRIBUTES
	REG_NOTIFY_CHANGE_NAME		REG_NOTIFY_CHANGE_LAST_SET
	REG_NOTIFY_CHANGE_SECURITY	REG_LEGAL_OPTION

	REG_OPTION_BACKUP_RESTORE	REG_OPTION_CREATE_LINK
	REG_OPTION_NON_VOLATILE		REG_OPTION_OPEN_LINK
	REG_OPTION_RESERVED		REG_OPTION_VOLATILE

	REG_WHOLE_HIVE_VOLATILE		REG_REFRESH_HIVE
	REG_NO_LAZY_FLUSH

	REG_NONE			REG_SZ
	REG_EXPAND_SZ			REG_BINARY
	REG_DWORD			REG_DWORD_LITTLE_ENDIAN
	REG_DWORD_BIG_ENDIAN		REG_LINK
	REG_MULTI_SZ			REG_RESOURCE_LIST
	REG_FULL_RESOURCE_DESCRIPTOR	REG_RESOURCE_REQUIREMENTS_LIST

=item :ALL

All of the above.

=item :SE_

The strings for the following privilege names:

	SE_ASSIGNPRIMARYTOKEN_NAME	SE_AUDIT_NAME
	SE_BACKUP_NAME			SE_CHANGE_NOTIFY_NAME
	SE_CREATE_PAGEFILE_NAME		SE_CREATE_PERMANENT_NAME
	SE_CREATE_TOKEN_NAME		SE_DEBUG_NAME
	SE_INCREASE_QUOTA_NAME		SE_INC_BASE_PRIORITY_NAME
	SE_LOAD_DRIVER_NAME		SE_LOCK_MEMORY_NAME
	SE_MACHINE_ACCOUNT_NAME		SE_PROF_SINGLE_PROCESS_NAME
	SE_REMOTE_SHUTDOWN_NAME		SE_RESTORE_NAME
	SE_SECURITY_NAME		SE_SHUTDOWN_NAME
	SE_SYSTEMTIME_NAME		SE_SYSTEM_ENVIRONMENT_NAME
	SE_SYSTEM_PROFILE_NAME		SE_TAKE_OWNERSHIP_NAME
	SE_TCB_NAME			SE_UNSOLICITED_INPUT_NAME

It can be difficult to successfully build this module in a way
that makes these constants available.  So some builds of this
module may not make them available.  For such builds, trying
to export any of these constants will cause a fatal error.
For this reason, none of these symbols are currently included
in the C<":ALL"> grouping.

=back

=head2 The Win32API:: heirarchy

This and the other Win32API:: modules are meant to expose the
nearly raw API calls so they can be used from Perl code in any
way they might be used from C code.  This provides the following
advantages:

=over

=item Many modules can be written by people that don't have a C compiler.

=item Encourages more module code to be written in Perl [not C].

Perl code is often much easier to inspect, debug, customize, and
enhance than XS code.

=item Allows those already familiar with the Win32 API to get
off to a quick start.

=item Provides an interactive tool for exploring even obscure
details of the Win32 API.

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

    perl -de 0

=item Ensures that native Win32 data structures can be used.

This allows maximum efficiency.  It also allows data from one
module [for example, time or security information from the
C<Win32API::Registry> or C<Win32API::File> modules] to be used
with other modules [for example, C<Win32API::Time> and
C<Win32API::SecDesc>].

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

=back

=head2 Buffer sizes

For each parameter that specifies a buffer size, a value of C<0>
can be passed.  For parameter that are pointers to buffer sizes,
you can also pass in C<NULL> by specifying an empty list reference,
C<[]>.  Both of these cases will ensure that the variable has
I<some> buffer space allocated to it and pass in that buffer's
allocated size.  Many of the calls indicate, via C<ERROR_MORE_DATA>,
that the buffer size was not sufficient and the F<Registry.xs>
code will automatically enlarge the buffer to the required size
and repeat the call.

Numeric buffer sizes are used as minimum initial sizes for the
buffers.  The larger of this size and the size of space already
allocated to the scalar will be passed to the underlying routine. 
If that size was insufficient, and the underlying call provides
an easy method for determining the needed buffer size, then the
buffer will be enlarged and the call repeated as above.

The underlying calls define buffer size parameter as unsigned, so
negative buffer sizes are treated as very large positive buffer
sizes which usually cause C<malloc()> to fail.

To force the F<Registry.xs> code to pass in a specific value for
a buffer size, preceed the size with an equals sign via C<"=".>. 
Buffer sizes that are passed in as strings starting with an equals
sign will have the equal sign stripped and the remainder of the string
interpretted as a number [via C's C<strtoul()> using only base 10]
which will be passed to the underlying routine [even if the allocated
buffer is actually larger].  The F<Registry.xs> code will enlarge the
buffer to the specified size, if needed, but will not enlarge the
buffer based on the underlying routine requesting more space.

Some Reg*() calls may not currently set the buffer size when they
return C<ERROR_MORE_DATA>.  But some that are not documented as
doing so, currently do so anyway.  So the code assumes that any
routine I<might> do this and resizes any buffers and repeats the
call.   We hope that eventually all routines will provide this
feature.

When you use C<[]> for a buffer size, you can still find the
length of the data returned by using C<length($buffer)>.  Note
that this length will be in bytes while a few of the buffer
sizes would have been in units of wide characters.

Note that the RegQueryValueEx*() and RegEnumValue*() calls
will trim the trailing C<'\0'> [if present] from the returned data
values of type C<REG_SZ> or C<REG_EXPAND_SZ> but only if the
value data length parameter is omitted [or specified as C<[]>].

The RegSetValueEx*() calls will add a trailing C<'\0'> [if
missing] to the supplied data values of type C<REG_SZ> and
C<REG_EXPAND_SZ> but only if the value data length parameter
is omitted [or specified as C<0>].

=head2 Hungarian Notation

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

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

=over

=item s

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

=item sw

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

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

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

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

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

=item p

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

=item a

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

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

=item n

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

=item iv

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

=item u

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

=item d

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

=item b

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

=item c

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

=item l

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

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

=item lw

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

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

=item h

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

=item r

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

=item sv

=item rv

=item hv

=item av

=item cv

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

=item Input or Output

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

=over

=item i

An input parameter given to the API [usually omitted].

=item o

An output-only parameter taken from the API.  You should not get a
warning if such a parameter is C<undef> when you pass it into the
function.  You should get an error if such a parameter is read-only.
You can [usually] pass in C<[]> for such a parameter to have the
parameter silently ignored.

The output may be written directly into the Perl variable passed
to the subroutine, the same way the buffer parameter to Perl's
C<sysread()>.  This method is often avoided in Perl because
the call then lacks any visual cue that some parameters are being
overwritten.   But this method closely matches the C API which is
what we are trying to do.

=item io

Input given to the API then overwritten with output taken from the
API.  You should get a warning [if B<-w> is in effect] if such a
parameter is C<undef> when you pass it into the function [unless it
is a buffer or buffer length parameter].  If the value is read-only,
then [for most parameters] the output is silently not written.  This
is because it is often convenient to pass in read-only constants for
many such parameters.  You can also usually pass in C<[]> for such
parameters.

=back

=item pp

=item ppr

=item par

=item pap

These are just unusual combinations of prefix characters described above.

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

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

=item ap

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

=back

=head1 BUGS

The old ActiveState ports of Perl for Win32 [but not, ActivePerl, the
ActiveState distributions of standard Perl 5.004 and beyond] do not support
the tools for building extensions and so do not support this extension.

No routines are provided for using the data returned in the C<FILETIME>
buffers.  Those are in the C<Win32API::Time> module.

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

Parts of the module test will fail if used on a version of Perl
that does not yet set C<$^E> based on C<GetLastError()>.

On NT 4.0 [at least], the RegEnum*() calls do not set the required
buffer sizes when returning C<ERROR_MORE_DATA> so this module will
not grow the buffers in such cases.  C<Win32::TieRegistry> overcomes
this by using values from C<RegQueryInfoKey()> for buffer sizes in
RegEnum* calls.

On NT 4.0 [at least], C<RegQueryInfoKey()> on C<HKEY_PERFORMANCE_DATA>
never succeeds.  Also, C<RegQueryValueEx()> on C<HKEY_PERFORMANCE_DATA>
never returns the required buffer size.  To access C<HKEY_PERFORMANCE_DATA>
you will need to keep growing the data buffer until the call succeeds.

Because C<goto &subroutine> seems to be buggy under Win32 Perl,
it is not used in the stubs in F<Registry.pm>.

=head1 AUTHOR

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

=head1 SEE ALSO

=over

=item L<Win32::TieRegistry>

=item L<Win32::Registry>

=back

=cut