|
Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H |
Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H
use Win32API::Registry 0.13 qw( :ALL );
RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key );
or die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: $^E\n";
RegQueryValueEx( $key, "Information", [], $type, $data, [] );
or die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: $^E\n";
[...]
RegCloseKey( $key )
or die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: $^E\n";
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
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 Win32::TieRegistry module.
To pass in NULL as the pointer to an optional buffer, pass in
an empty list reference, [].
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, $^E should automatically be set to
indicate the reason. If you have a version of Perl that does not
yet connect $^E to GetLastError() under Win32, then you can
use $iError= Win32::GetLastError() to get the numeric error
code and pass that to Win32::FormatMessage($iError) to to get
the descriptive string, or just
Win32::FormatMessage(Win32::GetLastError()).
Note that $! is not set by these routines except by
Win32API::Registry::constant() when a constant is not defined.
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.]
$^E] on failure. This routine does not provide
a way to tell if a privilege is current enabled.
$sPrivname is a Win32 privilege name [see the SE_*_NAME
macros of winnt.h]. For example, "SeBackupPrivilege" [a.k.a.
SE_BACKUP_NAME] controls whether you can use RegSaveKey()
and "SeRestorePrivilege" [a.k.a. SE_RESTORE_NAME] controls
whether you can use RegLoadKey().
If $bEnable is true, then AllowPriv() tries to enable the
privilege. Otherwise it tries to disable the privilege.
InitiateSystemShutdown().
$sComputer is the name [or address] of the computer to be
shutdown or rebooted. You can use [] [for NULL] or ""
to indicate the local computer.
$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
AbortSystemShutdown(). With $iTimeoutSecs == 0, the message
will never be visible.
$iTimeoutSecs is the number of seconds to wait before starting
the shutdown.
If $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 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 $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
AbortSystemShutdown() before the timeout expires and there is no
way to abort the shutdown once it has begun.
If $bReboot is true, the computer will automatically reboot once
the shutdown is complete. If $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 "SeRemoteShutdownPrivilege" privilege
on the remote computer for this call to succeed. If shutting
down the local computer, then the calling process must have
the "SeShutdownPrivilege" privilege and have it enabled.
RegOpenKeyEx(),
RegConnectRegistry(), RegCreateKeyEx(), or a few other
routines.
$sComputer is the name [or address] of a remote computer you
whose Registry you wish to access.
$hKey must be either HKEY_LOCAL_MACHINE or HKEY_USERS
and specifies which root Registry key on the remote computer
you wish to have access to.
$phKey will be set to the handle to be used to access the remote
Registry key.
RegCreateKeyEx() instead.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sSubKey is the name of the new subkey to be created.
$iZero is reserved for future use and should always be specified
as 0.
$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, "", should usually
be used here.
$iOpts is a numeric value containing bits that control options
used while creating the new subkey. REG_OPTION_NON_VOLATILE
is the default. 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.
REG_OPTION_BACKUP_RESTORE [also ignored on Windows 95] means
ignore the $iAccess parameter and try to open the new key with
the access required to backup or restore the key.
$iAccess is a numeric mask of bits specifying what type of
access is desired when opening the new subkey. See RegOpenKeyEx().
$pSecAttr is a SECURITY_ATTRIBUTES structure packed into
a Perl string which controls whether the returned handle can be
inherited by child processes. Normally you would pass [] for
this argument to have NULL passed to the underlying API
indicating that the handle cannot be inherited. If not under
Windows95, then $pSecAttr also allows you to specify
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.
$phKey will be set to the handle to be used to access the new subkey.
$piDisp will be set to either REG_CREATED_NEW_KEY or
REG_OPENED_EXISTING_KEY to indicate for which reason the
call succeeded. Can be specified as [] if you don't care.
If $phKey and $piDisp start out is integers, then they will
probably remain unchanged if the call fails.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sSubKey is the name of the subkey to be deleted.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sValueKey is the name of the value to be deleted.
RegEnumKeyEx() instead.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$iIndex is the sequence number of the immediate subkey that you
want information on. Start with this value as 0 then repeat
the call incrementing this value each time until the call fails
with ERROR_NO_MORE_ITEMS.
$sName will be set to the name of the subkey. Can be [] if
you don't care about the name.
$plName initially specifies the [minimum] buffer size to be
allocated for $sName. Will be set to the length of the subkey
name if the requested subkey exists even if $sName isn't
successfully set to the subkey name. See Buffer sizes for
more information.
$pNull is reserved for future used and should be passed as [].
$sClass will be set to the class name for the subkey. Can be
[] if you don't care about the class.
$plClass initially specifies the [minimum] buffer size to be
allocated for $sClass and will be set to the length of the
subkey class name if the requested subkey exists. See Buffer sizes for more information.
$pftLastWrite will be set to a FILETIME structure packed
into a Perl string and indicating when the subkey was last changed.
Can be [].
You may omit both $plName and $plClass to get the same effect
as passing in [] for each of them.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$iIndex is the sequence number of the value that you want
information on. Start with this value as 0 then repeat the
call incrementing this value each time until the call fails with
ERROR_NO_MORE_ITEMS.
$sValName will be set to the name of the value. Can be []
if you don't care about the name.
$plValName initially specifies the [minimum] buffer size to be
allocated for $sValName. Will be set to the length of the value
name if the requested value exists even if $sValName isn't
successfully set to the value name. See Buffer sizes for
more information.
$pNull is reserved for future used and should be passed as [].
$piType will be set to the type of data stored in the value data.
If the call succeeds, it will be set to a REG_* value unless
passed in as [].
$pValData will be set to the data [packed into a Perl string]
that is stored in the requested value. Can be [] if you don't
care about the value data.
$plValData initially specifies the [minimum] buffer size to be
allocated for $sValData and will be set to the length of the
value data if the requested value exists. See Buffer sizes for
more information.
You may omit both $plValName and $plValData to get the same
effect as passing in [] for each of them.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
SECURITY_DESCRIPTOR structures describing
part of the security for an open Registry key.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$iSecInfo is a numeric SECURITY_INFORMATION value that
specifies which SECURITY_DESCRIPTOR structure to retrieve. Should
be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION,
DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION.
$pSecDesc will be set to the requested SECURITY_DESCRIPTOR
structure [packed into a Perl string].
$plSecDesc initially specifies the [minimum] buffer size to be
allocated for $sSecDesc and will be set to the length of the
security descriptor. See Buffer sizes for more information.
You may omit this parameter to get the same effect as passing in
[] for it.
RegSaveKey().
$hKey is the handle to a Registry key that can have hives
loaded to it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS,
or a remote version of one of these from a call to
RegConnectRegistry().
$sSubKey is the name of the new subkey to created and associated
with the hive file.
$sFileName is the name of the hive file to be loaded. This
file name is interpretted relative to the
%SystemRoot%/System32/config directory on the computer where
the $hKey key resides.
Loading of hive files located on network shares may fail or corrupt the hive and so should not be attempted.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call] for which you wish to be notified when any changes
are made to it.
If $bWatchSubtree is true, then changes to any subkey or
descendant of $hKey are also reported.
$iNotifyFilter controllers what types of changes are reported. It
is a numeric value containing one or more of the following bit masks:
$hEvent is ignored unless $bAsync is true. Otherwise, $hEvent
is a handle to a Win32 event that will be signaled when changes are
to be reported.
If $bAsync is true, then RegNotifyChangeKeyValue() returns
immediately and uses $hEvent to notify your process of changes.
If $bAsync is false, then RegNotifyChangeKeyValue() does
not return until there is a change to be notified of.
This routine does not work with Registry keys on remote computers.
RegOpenKeyEx() instead.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sSubKey is the name of an existing subkey to be opened.
Can be "" or [] to open an additional handle to the
key specified by $hKey.
$iOptions is a numeric value containing bits that control options
used while open the subkey. There are currently no supported options
so this parameters should be specified as 0.
$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:
KEY_READ | KEY_WRITE | KEY_CREATE_LINK
KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
KEY_READ.
HKEY_CLASSES_ROOT
and HKEY_CURRENT_USER if the method for doing so were documented.
$phKey will be set to the handle to be used to access the new subkey.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sClass will be set to the class name for the key. Can be
[] if you don't care about the class.
$plClass initially specifies the [minimum] buffer size to be
allocated for $sClass and will be set to the length of the
key's class name. See Buffer sizes for more information.
You may omit this parameter to get the same effect as passing in
[] for it.
$pNull is reserved for future used and should be passed as [].
$pcSubKeys will be set to the count of the number of subkeys directly
under this key. Can be [].
$plSubKey will be set to the length of the longest subkey name.
Can be [].
$plSubClass will be set to the length of the longest class name
used with an immediate subkey of this key. Can be [].
$pcValues will be set to the count of the number of values in
this key. Can be [].
$plValName will be set to the length of the longest value name
in this key. Can be [].
$plValData will be set to the length of the longest value data
in this key. Can be [].
$plSecDesc will be set to the length of this key's [longest?]
security descriptor.
$pftTime will be set to a FILETIME structure packed
into a Perl string and indicating when this key was last changed.
Can be [].
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$pValueEnts should contain a list of VALENT structures packed
into a single Perl string. Each VALENT structure should have
the ve_valuename entry pointing to a string containing the name
of a value stored in this key. The remaining fields are set if
the function succeeds.
$cValueEnts should contain the count of the number of VALENT
structures contained in $pValueEnts.
$pBuffer will be set to the data from all of the requested values
concatenated into a single Perl string.
$plBuffer initially specifies the [minimum] buffer size to be
allocated for $sBuffer and will be set to the total length of
the data to be written to $sBuffer. See Buffer sizes for
more information. You may omit this parameter to get the same
effect as passing in [] for it.
Here is sample code to populate $pValueEnts:
$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 $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 $sBuffer since
the call, you can also extract the value data strings from $sBuffer
by using the pointers returned in $pValueEnts:
@Data= unpack( join( "", map(" x4 x4 P$_ x4 ",@Lengths) ),
$pValueEnts );
Much better is to use the lengths and extract directly from
$sBuffer using unpack() [or substr()]:
@Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
RegQueryValueEx() instead. This routine can only
query unamed values (a.k.a. ``default values'').
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sValueName is the name of the value whose data you wish to
retrieve.
$pNull this parameter is reserved for future use and should be
specified as [].
$piType will be set to indicate what type of data is stored in
the named value. Will be set to a REG_* value if the function
succeeds.
$pValueData will be set to the value data [packed into a Perl
string] that is stored in the named value. Can be [] if you
don't care about the value data.
$plValueData initially specifies the [minimum] buffer size to be
allocated for $sValueData and will be set to the size [always
in bytes] of the data to be written to $sValueData. See
Buffer sizes for more information.
$hKey is the handle to a Registry key that has hives
loaded in it. This must be HKEY_LOCAL_MACHINE,
HKEY_USERS, or a remote version of one of these from
a call to RegConnectRegistry().
$sSubKey is the name of the subkey of $hKey whose hive
you wish to have replaced on the next reboot.
$sNewFile is the name of a file that will replace the existing
hive file when the system reboots.
$sOldFile is the file name to save the current hive file to
when the system reboots.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$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 $hKey.
$uFlags is usally 0. It can also be 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 $hKey is HKEY_LOCAL_MACHINE, HKEY_USERS, or a
remote version of one of these from a call to RegConnectRegistry().
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sFileName is the name of the file that the Registry tree should
be saved to. It is interpretted relative to the
%SystemRoot%/System32/config directory on the computer where
the $hKey key resides.
$pSecAttr contains a SECURITY_ATTRIBUTES structure that specifies
the permissions to be set on the new file that is created. This can
be [].
SECURITY_DESCRIPTOR structures describing part
of the security for an open Registry key.
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$uSecInfo is a numeric SECURITY_INFORMATION value that
specifies which SECURITY_DESCRIPTOR structure to set. Should
be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION,
DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION.
$pSecDesc contains the new SECURITY_DESCRIPTOR structure
packed into a Perl string.
RegSetValueEx() instead. This routine can only
set unamed values (a.k.a. ``default values'').
$hKey is the handle to a Registry key [either HKEY_* or from
a previous call].
$sName is the name of the value to be set.
$uZero is reserved for future use and should be specified as 0.
$uType is the type of data stored in $pData. It should
be a REG_* value.
$pData is the value data packed into a Perl string.
$lData the length of the value data that is stored in $pData.
You will usually omit this parameter or pass in 0 to have
length($pData) used. In both of these cases, if $iType is
REG_SZ or REG_EXPAND_SZ, RegSetValueEx() will append a
trailing '\0' to the end of $pData [unless there is already
one].
$hKey is the handle to a Registry key that has hives
loaded in it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS,
or a remote version of one of these from a call to
RegConnectRegistry().
$sSubKey is the name of the subkey whose hive you wish to
have unloaded.
Each of these is identical to 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
$swComputerName is UNICODE.
$swComputer and $swMessage are UNICODE.
$swComputer is UNICODE.
$swSubKey is UNICODE.
$swSubKey and $swClass are UNICODE.
$swSubKey is UNICODE.
$swValueName is UNICODE.
$oswName is UNICODE and $ilwNameSize is measured as number of
WCHARs.
$swName and $swClass are UNICODE and $iolwName and $iolwClass
are measured as number of WCHARs.
$oswName is UNICODE and $iolwName is measured as number
of WCHARs.
$opData is UNICODE if $piType is REG_SZ, REG_EXPAND_SZ,
or REG_MULTI_SZ. Note that $iolData is measured as number
of bytes even in these cases.
$swSubKey and $swFileName are UNICODE.
$swSubKey is UNICODE.
$swSubKey is UNICODE.
$swClass is UNICODE. $iolwClass, $olwSubKey, $olwSubClass,
and $olwValName are measured as number of WCHARs. Note that
$olValData is measured as number of bytes.
_RegQueryMultipleValuesW(hKey,ioarValueEnts,icValueEnts,opBuffer,iolBuffer)ve_valuename fields of the VALENT structures in
$ioarValueEnts are UNICODE. Values of type REG_SZ,
REG_EXPAND_SZ, and REG_MULTI_SZ are written to $opBuffer
in UNICODE. Note that $iolBuffer and the ve_valuelen fields
of the VALENT structures are measured as number of bytes.
$swSubKey and $oswValueData are UNICODE. Note that
$iolValueData is measured as number of bytes.
$swName is UNICODE.
$opData is UNICODE if $ouType is REG_SZ, REG_EXPAND_SZ,
or REG_MULTI_SZ. Note that $iolData is measured as number of
bytes even in these cases.
$swSubKey, $swNewFile, and $swOldFile are UNICODE.
$swFileName is UNICODE.
$swFileName is UNICODE.
$swSubKey and $swValueData are UNICODE. Note that
$lValueData is measured as number of bytes even though
$swValueData is always UNICODE.
$swName is UNICODE.
$pData is UNICODE if $uType is REG_SZ, REG_EXPAND_SZ,
or REG_MULTI_SZ. Note that $lData is measured as number of
bytes even in these cases.
$swSubKey is UNICODE.
HKEY_* constants:
HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER
HKEY_DYN_DATA HKEY_LOCAL_MACHINE HKEY_PERFORMANCE_DATA
HKEY_USERS
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
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
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:
Win32API::Registry or Win32API::File modules] to be used
with other modules [for example, Win32API::Time and
Win32API::Security].
For each argument that specifies a buffer size, a value of 0
can be passed. For arguments that are pointers to buffer sizes,
you can also pass in NULL by specifying an empty list reference,
[]. Both of these cases will ensure that the variable has
&some; buffer space allocated to it and pass in that buffer's
allocated size. Many of the calls indicate, via ERROR_MORE_DATA,
that the buffer size was not sufficient and the 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 arguments as unsigned, so
negative buffer sizes are treated as very large positive buffer
sizes which usually cause malloc() to fail.
To force the Registry.xs code to pass in a specific value for
a buffer size, preceed the size with "=". Buffer sizes that
are passed in as strings starting with an equal sign will have
the equal sign stripped and the remainder of the string interpretted
as a number [via C's strtoul() using only base 10] which will be
passed to the underlying routine [even if the allocated buffer is
actually larger]. The 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 ERROR_MORE_DATA. But some that are not documented as
doing so, currently do so anyway. So the code assumes that any
routine &might; do this and resizes any buffers and repeats the
call. We hope that eventually all routines will provide this
feature.
When you use [] for a buffer size, you can still find the
length of the data returned by using 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 '\0' [if present] from the returned data
values of type REG_SZ or REG_EXPAND_SZ but only if the
value data length argument is omitted [or specified as []].
The RegSetValueEx*() calls will add a trailing '\0' [if
missing] to the supplied data values of type REG_SZ and
REG_EXPAND_SZ but only if the value data length argument is
omitted [or specified as 0].
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 is included in each Win32API module and
so covers some notations not used by this specific module.
'\0'-terminated char *. In Perl, just a
string except that it will be truncated at the first "\0", if
it contains one.
L'\0'-terminated 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 that an explicit L'\0' must be added since Perl's implicit
'\0' that it puts after each of its strings is not wide enough to
terminate a UNICODE string.
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$//;
struct]. In C,
a void *. In Perl, a string that is usually manipulated using
pack and unpack. The ``p'' is usually followed by more prefix
character(s) to indicate what type of data is stored in the bufffer.
structs]. 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.
float or double or, perhaps,
a long double. In Perl, a double-precision floating-point number
[NV].
bool or BOOL, containing either a 0 [false] or
non-zero [true] value. In Perl, a scalar containing a Boolean value
[0, "", or undef for ``false'' and anything else for ``true''].
For strings, there is no general rule as to whether the trailing
'\0' is included in such sizes. For this reason, the Win32API
modules follows the Perl rule of always allocating one extra byte
and reporting buffer sizes as being one smaller than allocated in case
the '\0' is not included in the size.
WCHARs. In Perl, an unsigned integer [UV] counting ``shorts''
[see ``s'' and ``S'' in pack and unpack].
For UNICODE strings, the trailing L'\0' may or may not be included
in a length so, again, we always alllocate extra room for one and
don't report that extra space.
HANDLE or more-specific handle data type. In
Perl, a signed integer [IV]. In C, these handles are often actually
some type of pointer, but Perl just treats them as opaque numbers,
as it should.
struct or perhaps union. Note
that C structs are rarely passed by value so the ``r'' is almost
always preceeded by a ``p'' or `` ''a`` [see p and 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 struct rather than storing the
struct directly in a Perl string, the prefix ''pp`` or ''ppr`` or even
''par`` is used.
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 [] for such a parameter to have the
parameter silently ignored.
These parameters are written to directly, like the buffer argument to
Perl's sysread(). This method is often avoided because such calls
lack any visual cue that some parameters are being overwritten. But
this method closely matches the C API which is what we are trying to
do.
undef when you pass it into the function. If the
value is read-only, then [for most parameters] the output is silently
not written. This is because it is often convenient to pass in read-only
constants for many such parameters. You can also usually pass in
[] for such parameters.
For each, a pointer is stored in a [4-byte] Perl string. You can
usually use unpack "P" to access the real data from Perl.
For ``ppr'' [and often for ``pp''], the pointer points directly at a
C struct. For ``par'', the pointer points to the first element
of a C [packed] array of structs. For ``pap'', the pointer points
to a C [packed] array of pointers to other things.
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 FILETIME
buffers. Those will be in Win32API::Time when it becomes available.
No routines are provided for dealing with UNICODE data effectively. Such are available elsewhere. See also test.pl 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 $^E based on GetLastError().
On NT 4.0 (at least), the RegEnum* calls do not set the required
buffer sizes when returning ERROR_MORE_DATA so this module will
not grow the buffers in such cases. Win32::TieRegistry overcomes
this by using values from RegQueryInfoKey() for buffer sizes in
RegEnum* calls.
On NT 4.0 (at least), RegQueryInfoKey() on HKEY_PERFORMANCE_DATA
never succeeds. Also, RegQueryValueEx() on HKEY_PERFORMANCE_DATA
never returns the required buffer size. To access HKEY_PERFORMANCE_DATA
you will need to keep growing the data buffer until the call succeeds.
Because goto &subroutine seems to be buggy under Win32 Perl,
it is not used in the stubs in Registry.pm.
Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
|
Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H |