registry.pm

ARM上的如果你对底层感兴趣

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 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>:

    $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( $hKey, $sSubKey, $sValueData, $plValueData )

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").

=item RegQueryValueEx( $hKey, $sValueName, $pNull, $piType, $pValueData, $plValueData )

Lets you look up value data using the name of the value stored in an
open Registry key.

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>.  See
L<Buffer sizes> for more information.

=item RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )

Lets you replace an entire hive when the system is next booted.

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 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.

=item RegRestoreKey( $hKey, $sFileName, $iFlags )

Reads in a hive file and copies its contents over an existing
Registry tree.

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<$iFlags> 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()>.

=item RegSaveKey( $hKey, $sFileName, $pSecAttr )

Dumps any open Registry key and all of its subkeys and values into
a new hive file.

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.

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<[]>.

=item RegSetKeySecurity( $hKey, $iSecInfo, $pSecDesc )

Sets one of the C<SECURITY_DESCRIPTOR> structures describing part
of the security for an open Registry key.

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 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>.

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

=item RegSetValue( $hKey, $sSubKey, $iType, $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( $hKey, $sValueName, $iZero, $iType, $pValueData, $lValueData )

Sets a value.

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 to be set.

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

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

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

C<$lValueData> the length of the value data that is stored in
C<$pValueData>.  You will usually omit this parameter or pass
in C<0> to have C<length($pValueData)> 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<$pValueData> [unless there is already one].

=item 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.

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 ASCI-specific function names.

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

=item :FuncW

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

=item AbortSystemShutdownW( $sComputerName )

C<$sComputerName> is UNICODE.

=item InitiateSystemShutdownW( $sComputer, $sMessage, $iTimeoutSecs, $bForce, $bReboot )

C<$sComputer> is UNICODE.

=item RegConnectRegistryW( $sComputer, $hKey, $phKey )

C<$sComputer> is UNICODE.

=item RegCreateKeyW( $hKey, $sSubKey, $phKey )

C<$sSubKey> is UNICODE.

=item RegCreateKeyExW( $hKey, $sSubKey, $iZero, $sClass, $iOpts, $iAccess, $pSecAttr, $phKey, $piDisp )

C<$sSubKey> and C<$sClass> are UNICODE.

=item RegDeleteKeyW( $hKey, $sSubKey )

C<$sSubKey> is UNICODE.

=item RegDeleteValueW( $hKey, $sValueName )

C<$sValueName> is UNICODE.

=item RegEnumKeyW( $hKey, $iIndex, $sName, $lwNameSize )

C<$sName> is UNICODE and C<$lwNameSize> is measured as number
of C<WCHAR>s.

=item RegEnumKeyExW( $hKey, $iIndex, $sName, $plwName, $pNull, $sClass, $plwClass, $pftLastWrite )

C<$sName> and C<$sClass> are UNICODE and C<$plwName> and C<$plwClass>
are measured as number of C<WCHAR>s.

=item RegEnumValueW( $hKey, $iIndex, $sValName, $plwValName, $pNull, $piType, $pValData, $plValData )

C<$sValName> is UNICODE and C<$plwValName> is measured as number
of C<WCHAR>s.

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

=item RegLoadKeyW( $hKey, $sSubKey, $sFileName )

C<$sSubKey> and C<$sFileName> are UNICODE.

=item RegOpenKeyW( $hKey, $sSubKey, $phKey )

C<$sSubKey> is UNICODE.

=item RegOpenKeyExW( $hKey, $sSubKey, $iOptions, $iAccess, $phKey )

C<$sSubKey> is UNICODE.

=item RegQueryInfoKeyW( $hKey, $sClass, $plwClass, $pNull, $pcSubKeys, $plwSubKey, $plwSubClass, $pcValues, $plwValName, $plValData, $plSecDesc, $pftTime )

C<$sClass> is UNICODE.  C<$plwClass>, C<$plwSubKey>, C<$plwSubClass>,
and C<$plwValName> are measured as number of C<WCHAR>s.  Note that
C<$plValData> is measured as number of bytes.

=item RegQueryMultipleValuesW( $hKey, $pValueEnts, $cValueEnts, $pBuffer, $plBuffer )

The C<ve_valuename> fields of the C<VALENT> structures in
C<$pValueEnts> are UNICODE.  Values of type C<REG_SZ>, C<REG_EXPAND_SZ>,
and C<REG_MULTI_SZ> are written to C<$pBuffer> in UNICODE.
Note that C<$plBuffer> and the C<ve_valuelen> fields of the
C<VALENT> structures are measured as number of bytes.

=item RegQueryValueW( $hKey, $sSubKey, $sValueData, $plValueData )

C<$sSubKey> and C<$sValueData> is UNICODE.  Note that C<$plValueData>
is measured as number of bytes.

=item RegQueryValueExW( $hKey, $sValueName, $pNull, $piType, $pValueData, $plValueData )

C<$sValueName> is UNICODE.

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

=item RegReplaceKeyW( $hKey, $sSubKey, $sNewFile, $sOldFile )

C<$sSubKey>, C<$sNewFile>, and C<$sOldFile> are UNICODE.

=item RegRestoreKeyW( $hKey, $sFileName, $iFlags )

C<$sFileName> is UNICODE.

=item RegSaveKeyW( $hKey, $sFileName, $pSecAttr )

C<$sFileName> is UNICODE.

=item RegSetValueW( $hKey, $sSubKey, $iType, $sValueData, $lValueData )

C<$sSubKey> and C<$sValueData> is UNICODE.  Note that
C<$lValueData> is measured as number of bytes.

=item RegSetValueExW( $hKey, $sValueName, $iZero, $iType, $pValueData, $lValueData )

C<$sValueName> is UNICODE.

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

=item RegUnLoadKeyW( $hKey, $sSubKey )

C<$sSubKey> 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_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

=item :ALL

All of the above.

=back

=head1 BUGS

The ActiveState ports of Perl for Win32 [but not the ActiveState
bundles 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 will be in C<Win32API::Time> when it becomes available.

No routines are provided for dealing with UNICODE data effectively.
Such are available elsewhere.

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, it is not
used in the stubs in F<Registry.pm>.

Using C<undef> as an argument to any of the stubs in F<Registry.pm>
may cause warnings when the C<undef> is then passed to the function
from F<Registry.xs> that does the real work.

=head1 AUTHOR

Tye McQueen, [e-mail], http://www.metronet.com/~tye/.

=head1 SEE ALSO

=over

=item L<Win32::TieRegistry>

=item L<Win32::Registry>

=back

=cut