NAME
Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H
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";
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 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. However, current versions of Perl often overwrite $^E
too quickly, so you can use regLastError()
instead, which is only set by Win32API::Registry routines. regLastError()
is also good if you have a really old version of Perl that does not connect $^E
to GetLastError()
on Win32.
Note that $!
is not set by these routines except by Win32API::Registry::constant()
when a constant is not defined.
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.]
- :Func
-
The basic function names:
- AllowPriv
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
$^E
/regLastError()
] on failure. This routine does not provide a way to tell if a privilege is currently enabled.$sPrivname
is a Win32 privilege name [see ":SE_"]. For example,"SeBackupPrivilege"
[a.k.a.SE_BACKUP_NAME
] controls whether you can useRegSaveKey()
and"SeRestorePrivilege"
[a.k.a.SE_RESTORE_NAME
] controls whether you can useRegLoadKey()
.If
$bEnable
is true, thenAllowPriv()
tries to enable the privilege. Otherwise it tries to disable the privilege. - AbortSystemShutdown
AbortSystemShutdown( $sComputerName )
-
Tries to abort a remote shutdown request previously made via
InitiateSystemShutdown()
. Returns a true value if successful and a false value [and sets$^E
/regLastError()
] on failure. - InitiateSystemShutdown
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
$^E
/regLastError()
] on failure.$sComputer
is the name [or address] of the computer to be shutdown or rebooted. You can use[]
[forNULL
] 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 viaAbortSystemShutdown()
. 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 callAbortSystemShutdown()
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. - RegCloseKey
RegCloseKey( $hKey )
-
Closes the handle to a Registry key returned by
RegOpenKeyEx()
,RegConnectRegistry()
,RegCreateKeyEx()
, or a few other routines. Returns a true value if successful and a false value [and sets$^E
/regLastError()
] on failure. - RegConnectRegistry
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
$^E
/regLastError()
] on failure.$sComputer
is the name [or address] of a remote computer whose Registry you wish to access.$hKey
must be eitherHKEY_LOCAL_MACHINE
orHKEY_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 if the call succeeds. - regConstant
$value= regConstant( $sConstantName )
-
Fetch the value of a constant. Returns
undef
if$sConstantName
is not the name of a constant supported by this module. Never sets$!
nor$^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
use Win32API::Registry
statement and then simply using the constant name in your code [perhaps followed by()
]. This function is useful for verifying constant names not in Perl code, for example, after prompting a user to type in a constant name. - RegCreateKey
RegCreateKey( $hKey, $sSubKey, $ohSubKey )
-
This routine is meant only for compatibility with Windows version 3.1. Use
RegCreateKeyEx()
instead. - RegCreateKeyEx
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 as0
.$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. SeeRegOpenKeyEx()
.$pSecAttr
is aSECURITY_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 parameter to haveNULL
passed to the underlying API indicating that the handle cannot be inherited. If not under Windows95, then$pSecAttr
also allows you to specifySECURITY_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 if the call succeeds.$piDisp
will be set to eitherREG_CREATED_NEW_KEY
orREG_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 as integers, then they will probably remain unchanged if the call fails. - RegDeleteKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$sSubKey
is the name of the subkey to be deleted. - RegDeleteValue
RegDeleteValue( $hKey, $sValueName )
-
Deletes a value from an open Registry key. Returns a true value if successful and a false value [and sets
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$sValueKey
is the name of the value to be deleted. - RegEnumKey
RegEnumKey( $hKey, $uIndex, $osName, $ilNameSize )
-
This routine is meant only for compatibility with Windows version 3.1. Use
RegEnumKeyEx()
instead. - RegEnumKeyEx
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$iIndex
is the sequence number of the immediate subkey that you want information on. Start with this value as0
then repeat the call incrementing this value each time until the call fails with$^E
/regLastError()
numerically equal toERROR_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 aFILETIME
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. - RegEnumValue
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$iIndex
is the sequence number of the value that you want information on. Start with this value as0
then repeat the call incrementing this value each time until the call fails withERROR_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 aREG_*
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. - RegFlushKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call]. - RegGetKeySecurity
RegGetKeySecurity( $hKey, $uSecInfo, $opSecDesc, $iolSecDesc )
-
Retrieves one of the
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$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$iSecInfo
is a numericSECURITY_INFORMATION
value that specifies which parts of theSECURITY_DESCRIPTOR
structure to retrieve. Should beOWNER_SECURITY_INFORMATION
,GROUP_SECURITY_INFORMATION
,DACL_SECURITY_INFORMATION
, or orSACL_SECURITY_INFORMATION
or two or more of these bits combined using|
.$pSecDesc
will be set to the requestedSECURITY_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. - regLastError
$svError= regLastError();
regLastError( $uError );
-
Returns the last error encountered by a routine from this module. It is just like
$^E
except it isn't changed by anything except routines from this module. Ideally you could just use$^E
, but current versions of Perl often overwrite$^E
before you get a chance to check it and really old versions of Perl don't really support$^E
under Win32.Just like
$^E
, in a numeric contextregLastError()
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$x= regLastError()
causes$x
to give different values in string vs. numeric contexts]. On old versions of Perl where$^E
isn't tied toGetLastError()
,regLastError
simply returns the number of the error and you'll need to use <Win32::FormatMessage> to get the error string.The last form sets the error returned by future calls to
regLastError()
and should not be used often.$uError
must be a numeric error code. Also returns the dual-valued version of$uError
. - RegLoadKey
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
RegSaveKey()
. Returns a true value if successful and a false value [and sets$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key that can have hives loaded to it. This must beHKEY_LOCAL_MACHINE
,HKEY_USERS
, or a remote version of one of these from a call toRegConnectRegistry()
.$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 interpreted relative to the%SystemRoot%/System32/config
directory on the computer where the$hKey
key resides. If$sFileName
is on a FAT file system, then its name must not have an extension.You must have the
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.
- RegNotifyChangeKeyValue
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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:REG_NOTIFY_CHANGE_NAME
-
Notify if a subkey is added or deleted to a monitored key.
REG_NOTIFY_CHANGE_LAST_SET
-
Notify if a value in a monitored key is added, deleted, or modified.
REG_NOTIFY_CHANGE_SECURITY
-
Notify if a security descriptor of a monitored key is changed.
REG_NOTIFY_CHANGE_ATTRIBUTES
-
Notify if any attributes of a monitored key are changed [class name or security descriptors].
$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, thenRegNotifyChangeKeyValue()
returns immediately and uses$hEvent
to notify your process of changes. If$bAsync
is false, thenRegNotifyChangeKeyValue()
does not return until there is a change to be notified of.This routine does not work with Registry keys on remote computers.
- RegOpenKey
RegOpenKey( $hKey, $sSubKey, $ohSubKey )
-
This routine is meant only for compatibility with Windows version 3.1. Use
RegOpenKeyEx()
instead. - RegOpenKeyEx
RegOpenKeyEx( $hKey, $sSubKey, $uOptions, $uAccess, $ohSubKey )
-
Opens an existing Registry key. Returns a true value if successful and a false value [and sets
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 opening the subkey. There are currently no supported options so this parameter should be specified as0
.$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_ALL_ACCESS
-
KEY_READ | KEY_WRITE | KEY_CREATE_LINK
KEY_READ
-
KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
KEY_WRITE
-
KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
KEY_QUERY_VALUE
KEY_SET_VALUE
KEY_ENUMERATE_SUB_KEYS
KEY_CREATE_SUB_KEY
KEY_NOTIFY
-
Allows you to use
RegNotifyChangeKeyValue()
on the opened key. KEY_EXECUTE
-
Same as
KEY_READ
. KEY_CREATE_LINK
-
Gives you permission to create a symbolic link like
HKEY_CLASSES_ROOT
andHKEY_CURRENT_USER
, though the method for doing so is not documented [and probably requires use of the mostly undocumented "native" routines,Nt*()
a.k.a.Zw*()
].
$phKey
will be set to the handle to be used to access the new subkey if the call succeeds. - RegQueryInfoKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 use 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 full security descriptor.$pftTime
will be set to aFILETIME
structure packed into a Perl string and indicating when this key was last changed. Can be[]
. - RegQueryMultipleValues
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$pValueEnts
should contain a list ofVALENT
structures packed into a single Perl string. EachVALENT
structure should have theve_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.$cValueEnts
should contain the count of the number ofVALENT
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
:# @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
$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
usingunpack()
[orsubstr()
]:@Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
- RegQueryValue
RegQueryValue( $hKey, $sSubKey, $osValueData, $iolValueData )
-
This routine is meant only for compatibility with Windows version 3.1. Use
RegQueryValueEx()
instead. This routine can only query unnamed values [a.k.a. "default values"], that is, values with a name of""
. - RegQueryValueEx
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 aREG_*
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
, even if$sValueData
is not successfully written to. See "Buffer sizes" for more information. - RegReplaceKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key that has hive(s) loaded in it. This must beHKEY_LOCAL_MACHINE
,HKEY_USERS
, or a remote version of one of these from a call toRegConnectRegistry()
.$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.$sNewFile
and$sOldFile
are interpreted relative to the%SystemRoot%/System32/config
directory on the computer where the$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
SE_RESTORE_NAME
privilege to use this routine. - RegRestoreKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 usually0
. It can also beREG_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
isHKEY_LOCAL_MACHINE
,HKEY_USERS
, or a remote version of one of these from a call toRegConnectRegistry()
.RegRestoreKey
does not delete values nor keys from the existing Registry tree when there is no corresponding value/key in the hive file. - RegSaveKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$sFileName
is the name of the file that the Registry tree should be saved to. It is interpreted relative to the%SystemRoot%/System32/config
directory on the computer where the$hKey
key resides. If$sFileName
is on a FAT file system, then it must not have an extension.$pSecAttr
contains aSECURITY_ATTRIBUTES
structure that specifies the permissions to be set on the new file that is created. This can be[]
.You must have the
SE_RESTORE_NAME
privilege to use this routine. - RegSetKeySecurity
RegSetKeySecurity( $hKey, $uSecInfo, $pSecDesc )
-
Sets [part of] the
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$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
or from a previous call].$uSecInfo
is a numericSECURITY_INFORMATION
value that specifies whichSECURITY_DESCRIPTOR
structure to set. Should beOWNER_SECURITY_INFORMATION
,GROUP_SECURITY_INFORMATION
,DACL_SECURITY_INFORMATION
, orSACL_SECURITY_INFORMATION
or two or more of these bits combined using|
.$pSecDesc
contains the newSECURITY_DESCRIPTOR
structure packed into a Perl string. - RegSetValue
RegSetValue( $hKey, $sSubKey, $uType, $sValueData, $lValueData )
-
This routine is meant only for compatibility with Windows version 3.1. Use
RegSetValueEx()
instead. This routine can only set unnamed values [a.k.a. "default values"]. - RegSetValueEx
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key [eitherHKEY_*
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 as0
.$uType
is the type of data stored in$pData
. It should be aREG_*
value.$pData
is the value data packed into a Perl string.$lData
is the length of the value data that is stored in$pData
. You will usually omit this parameter or pass in0
to havelength($pData)
used. In both of these cases, if$iType
isREG_SZ
orREG_EXPAND_SZ
,RegSetValueEx()
will append a trailing'\0'
to the end of$pData
[unless there is already one]. - RegUnLoadKey
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
$^E
/regLastError()
] on failure.$hKey
is the handle to a Registry key that has hives loaded in it. This must beHKEY_LOCAL_MACHINE
,HKEY_USERS
, or a remote version of one of these from a call toRegConnectRegistry()
.$sSubKey
is the name of the subkey whose hive you wish to have unloaded. - :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
- :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.
- AbortSystemShutdownW
AbortSystemShutdownW( $swComputerName )
-
$swComputerName
is UNICODE. - InitiateSystemShutdownW
InitiateSystemShutdownW( $swComputer, $swMessage, $uTimeoutSecs, $bForce, $bReboot )
-
$swComputer
and$swMessage
are UNICODE. - RegConnectRegistryW
RegConnectRegistryW( $swComputer, $hRootKey, $ohKey )
-
$swComputer
is UNICODE. - RegCreateKeyW
RegCreateKeyW( $hKey, $swSubKey, $ohSubKey )
-
$swSubKey
is UNICODE. - RegCreateKeyExW
RegCreateKeyExW( $hKey, $swSubKey, $uZero, $swClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )
-
$swSubKey
and$swClass
are UNICODE. - RegDeleteKeyW
RegDeleteKeyW( $hKey, $swSubKey )
-
$swSubKey
is UNICODE. - RegDeleteValueW
RegDeleteValueW( $hKey, $swValueName )
-
$swValueName
is UNICODE. - RegEnumKeyW
RegEnumKeyW( $hKey, $uIndex, $oswName, $ilwNameSize )
-
$oswName
is UNICODE and$ilwNameSize
is measured as number ofWCHAR
s. - RegEnumKeyExW
RegEnumKeyExW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $oswClass, $iolwClass, $opftLastWrite )
-
$swName
and$swClass
are UNICODE and$iolwName
and$iolwClass
are measured as number ofWCHAR
s. - RegEnumValueW
RegEnumValueW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $ouType, $opData, $iolData )
-
$oswName
is UNICODE and$iolwName
is measured as number ofWCHAR
s.$opData
is UNICODE if$piType
isREG_SZ
,REG_EXPAND_SZ
, orREG_MULTI_SZ
. Note that$iolData
is measured as number of bytes even in these cases. - RegLoadKeyW
RegLoadKeyW( $hKey, $swSubKey, $swFileName )
-
$swSubKey
and$swFileName
are UNICODE. - RegOpenKeyW
RegOpenKeyW( $hKey, $swSubKey, $ohSubKey )
-
$swSubKey
is UNICODE. - RegOpenKeyExW
RegOpenKeyExW( $hKey, $swSubKey, $uOptions, $uAccess, $ohSubKey )
-
$swSubKey
is UNICODE. - RegQueryInfoKeyW
RegQueryInfoKeyW( $hKey, $oswClass, $iolwClass, $pNull, $ocSubKeys, $olwSubKey, $olwSubClass, $ocValues, $olwValName, $olValData, $olSecDesc, $opftTime )
-
$swClass
is UNICODE.$iolwClass
,$olwSubKey
,$olwSubClass
, and$olwValName
are measured as number ofWCHAR
s. Note that$olValData
is measured as number of bytes. - RegQueryMultipleValuesW
RegQueryMultipleValuesW( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )
-
The
ve_valuename
fields of theVALENT
[actuallyVALENTW
] structures in$ioarValueEnts
are UNICODE. Values of typeREG_SZ
,REG_EXPAND_SZ
, andREG_MULTI_SZ
are written to$opBuffer
in UNICODE. Note that$iolBuffer
and theve_valuelen
fields of theVALENT
[VALENTW
] structures are measured as number of bytes. - RegQueryValueW
RegQueryValueW( $hKey, $swSubKey, $oswValueData, $iolValueData )
-
$swSubKey
and$oswValueData
are UNICODE. Note that$iolValueData
is measured as number of bytes. - RegQueryValueExW
RegQueryValueExW( $hKey, $swName, $pNull, $ouType, $opData, $iolData )
-
$swName
is UNICODE.$opData
is UNICODE if$ouType
isREG_SZ
,REG_EXPAND_SZ
, orREG_MULTI_SZ
. Note that$iolData
is measured as number of bytes even in these cases. - RegReplaceKeyW
RegReplaceKeyW( $hKey, $swSubKey, $swNewFile, $swOldFile )
-
$swSubKey
,$swNewFile
, and$swOldFile
are UNICODE. - RegRestoreKeyW
RegRestoreKeyW( $hKey, $swFileName, $uFlags )
-
$swFileName
is UNICODE. - RegSaveKeyW
RegSaveKeyW( $hKey, $swFileName, $pSecAttr )
-
$swFileName
is UNICODE. - RegSetValueW
RegSetValueW( $hKey, $swSubKey, $uType, $swValueData, $lValueData )
-
$swSubKey
and$swValueData
are UNICODE. Note that$lValueData
is measured as number of bytes even though$swValueData
is always UNICODE. - RegSetValueExW
RegSetValueExW( $hKey, $swName, $uZero, $uType, $pData, $lData )
-
$swName
is UNICODE.$pData
is UNICODE if$uType
isREG_SZ
,REG_EXPAND_SZ
, orREG_MULTI_SZ
. Note that$lData
is measured as number of bytes even in these cases. - RegUnLoadKeyW
RegUnLoadKeyW( $hKey, $swSubKey )
-
$swSubKey
is UNICODE. - :HKEY_
-
All
HKEY_*
constants:HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER HKEY_DYN_DATA HKEY_LOCAL_MACHINE HKEY_PERFORMANCE_DATA HKEY_USERS
- :KEY_
-
All
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_
-
All
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
- :ALL
-
All of the above.
- :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
":ALL"
grouping.
The Win32API:: hierarchy
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:
- Many modules can be written by people that don't have a C compiler.
- 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.
- Allows those already familiar with the Win32 API to get off to a quick start.
- 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
- 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
Win32API::Registry
orWin32API::File
modules] to be used with other modules [for example,Win32API::Time
andWin32API::SecDesc
]. - Provides a single version of the XS interface to each API call where improvements can be collected.
Buffer sizes
For each parameter that specifies a buffer size, a value of 0
can be passed. For parameter 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 parameter 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, precede the size with an equals sign via "=".
. 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 interpreted 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 parameter 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 parameter is omitted [or specified as 0
].
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 Win32API
module and so covers some notations not used by this specific module.
- s
-
A string. In C, a
'\0'
-terminatedchar *
. In Perl, just a string except that it will be truncated at the first"\0"
, if it contains one. - sw
-
A wide [UNICODE] string. In C, a
L'\0'
-terminatedWCHAR *
. 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
, 0
above causes an explicitL'\0'
to be added since Perl's implicit'\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 trailing'\0'
while the Perl version of a UNICODE string must include the trailingL'\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$//;
- p
-
A pointer to some buffer [usually containing some
struct
]. In C, avoid *
or some other pointer type. In Perl, a string that is usually manipulated usingpack
andunpack
. The "p" is usually followed by more prefix character(s) to indicate what type of data is stored in the buffer. - a
-
A packed array. In C, an array [usually of
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.
- 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.
- iv
-
A signed integral value. In C, any of the signed integer data types. In Perl, an integer [IV].
- u
-
An unsigned integral value. In C, any of the unsigned integer data types. In Perl, an unsigned integer [UV].
- d
-
A floating-point number. In C, a
float
ordouble
or, perhaps, along double
. In Perl, a double-precision floating-point number [NV]. - b
-
A Boolean value. In C, any integer data type, though usually via a type alias of
bool
orBOOL
, containing either a 0 [false] or non-zero [true] value. In Perl, a scalar containing a Boolean value [0
,""
, orundef
for "false" and anything else for "true"]. - 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 "a" above] to indicate the number of elements.
- 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 "s" and "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
'\0'
is included in such sizes. For this reason, theWin32API
modules follow 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. - lw
-
A length measured as number of UNICODE characters. In C, a count of
WCHAR
s. In Perl, an unsigned integer [UV] counting "shorts" [see "s" and "S" inpack
andunpack
].For UNICODE strings, the trailing
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. - h
-
A handle. In C, a
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. - r
-
A record. In C, almost always a
struct
or perhapsunion
. Note that Cstruct
s are rarely passed by value so the "r" is almost always preceded 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 thestruct
rather than storing thestruct
directly in a Perl string, the prefix "pp" or "ppr" or even "par" is used. - sv
- rv
- hv
- av
- 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
undef
] or even both at the same time. So "sv" doesn't imply a leading "rv". - 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.
- i
-
An input parameter given to the API [usually omitted].
- o
-
An output-only parameter taken from the API. You should not get a warning if such a parameter is
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.The output may be written directly into the Perl variable passed to the subroutine, the same way the buffer parameter to Perl's
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. - io
-
Input given to the API then overwritten with output taken from the API. You should get a warning [if -w is in effect] if such a parameter is
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[]
for such parameters.
- pp
- ppr
- par
- 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
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 ofstruct
s. For "pap", the pointer points to a C [packed] array of pointers to other things. - ap
-
Here we have a list of pointers packed into a single Perl string.
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 FILETIME
buffers. Those are in the Win32API::Time
module.
No routines are provided for dealing with UNICODE data effectively. See ":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 $^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.
AUTHOR
Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
LICENSE
perl