ch9.htm

《Perl 5 Unreleased》

</TD></TR>
<TR VALIGN=TOP><TD WIDTH=176>NTRegEnumValue</TD><TD WIDTH=168>NTRegSetKeySecurity
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=176>NTRegFlushKey</TD><TD WIDTH=168>NTRegSetValue
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=176>NTRegGetKeySecurity</TD><TD WIDTH=168>NTRegSetValueEx
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=176>NTRegLoadKey</TD><TD WIDTH=168>NTRegUnLoadKey
</TD></TR>
</TABLE></CENTER>
<P>
<H5>NTRegCloseKey</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">RegCloseKey</FONT></TT> function
releases a given key handle. The syntax for this call is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegCloseKey $hkeyHandle</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$hkeyHandle</FONT></TT> for a specified
key is rendered invalid and therefore cannot be used after it
has been closed. Key handles should be closed as soon as possible.
Also note that due to caching, the information might not be written
to disk immediately. Use the <TT><FONT FACE="Courier">NTRegFlushKey</FONT></TT>
call to force writing the key to disk. The <TT><FONT FACE="Courier">NTRegFlush</FONT></TT>
key is a system resource hog and should be used with care.
</BLOCKQUOTE>
<H5>NTRegConnectRegistry</H5>
<BLOCKQUOTE>
The syntax for this function is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegConnectRegistry $computer, $hkey,
$result</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegConnectRegistry</FONT></TT> establishes
a connection to a predefined Registry handle <TT><FONT FACE="Courier">$hkey</FONT></TT>
on another computer specified in <TT><FONT FACE="Courier">$computer</FONT></TT>.
The returned handle is stored in <TT><FONT FACE="Courier">$result</FONT></TT>.
Use a value of <TT><FONT FACE="Courier">NULL</FONT></TT> for <TT><FONT FACE="Courier">$computer</FONT></TT>
if connecting locally. Only the constants <TT><FONT FACE="Courier">$hkey_LOCAL_MAchINE</FONT></TT>
and <TT><FONT FACE="Courier">$hkey_USERS</FONT></TT> are valid
for <TT><FONT FACE="Courier">$hkey</FONT></TT>. Use the call to
<TT><FONT FACE="Courier">NTRegCloseKey</FONT></TT> when you are
done with the handle in <TT><FONT FACE="Courier">$result</FONT></TT>.
<BR>
</BLOCKQUOTE>
<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD ><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD >
<BLOCKQUOTE>
The value in <TT><FONT FACE="Courier">$hkey</FONT></TT> for most of the functions listed in this section can be replaced by a call to <TT><FONT FACE="Courier">NTRegConnectRegistry</FONT></TT> to get a name from a remote computer.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H5>NTRegCreateKey</H5>
<BLOCKQUOTE>
This function creates a subkey under a given handle and is provided
for older programs. Use the <TT><FONT FACE="Courier">NTRegCreateKeyEx</FONT></TT>
function for future portability. The syntax for this function
is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegCreateKey $hkey, $subkey, $result</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The call to this function creates the key named in <TT><FONT FACE="Courier">$subkey</FONT></TT>
under the already open key handle <TT><FONT FACE="Courier">$hkey</FONT></TT>.
The returned handle is stored in <TT><FONT FACE="Courier">$result</FONT></TT>.
If the key already exists in the Registry, the function opens
it and returns the handle in <TT><FONT FACE="Courier">$result</FONT></TT>.
</BLOCKQUOTE>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">$hkey</FONT></TT> can have one of
the following values:
</BLOCKQUOTE>
<UL>
<LI><TT><FONT FACE="Courier">$hkey_CLASSES_ROOT</FONT></TT>
<LI><TT><FONT FACE="Courier">$hkey_CURRENT_USER</FONT></TT>
<LI><TT><FONT FACE="Courier">$hkey_LOCAL_MAchINE</FONT></TT>
<LI><TT><FONT FACE="Courier">$hkey_USERS</FONT></TT>
</UL>
<H5>NTRegCreateKeyEx</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">NTRegCreateKeyEx</FONT></TT> function
is the preferred way of creating keys. The syntax for this function
is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegCreateKeyEx $hkey, $subkey, NULL,
$class,<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$options, $accessMode,
$security,<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$result, $disposition</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
This function creates the subkey named in <TT><FONT FACE="Courier">$subkey</FONT></TT>
and returns the handle of the newly opened key in <TT><FONT FACE="Courier">$result</FONT></TT>.
If the key already exists in the Registry, the function opens
it and returns its handle instead. The <TT><FONT FACE="Courier">$class</FONT></TT>
string specifies the object-type for the key.
</BLOCKQUOTE>
<BLOCKQUOTE>
The value in <TT><FONT FACE="Courier">$options</FONT></TT> can
be <TT><FONT FACE="Courier">REG_OPTION_VOLATILE</FONT></TT> or
the value of <TT><FONT FACE="Courier">REG_OPTION_NON_VOLATILE</FONT></TT>.
Volatile keys are stored in memory only and are not preserved
in between Windows NT sessions. Nonvolatile keys are saved to
disk and preserved when the system is restarted. Use volatile
options when testing the access mode in which the key is specified
in the <TT><FONT FACE="Courier">NT.ph</FONT></TT> file in the
source code for the Win32 Perl distribution. The <TT><FONT FACE="Courier">$security</FONT></TT>
descriptor can be <TT><FONT FACE="Courier">NULL</FONT></TT> or
set as described in the Win32 API documentation.
</BLOCKQUOTE>
<BLOCKQUOTE>
The newly created key that the <TT><FONT FACE="Courier">NTRegCreateKeyEx</FONT></TT>
function creates is not set to a default value. Use the <TT><FONT FACE="Courier">NTRegSetValue</FONT></TT>
or <TT><FONT FACE="Courier">NTRegSetValueEx</FONT></TT> function
to set the value of this key.
</BLOCKQUOTE>
<BLOCKQUOTE>
An application cannot create a key under <TT><FONT FACE="Courier">$hkey_USERS</FONT></TT>
or <TT><FONT FACE="Courier">$hkey_LOCAL_MAchINE</FONT></TT>.
</BLOCKQUOTE>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">$disposition</FONT></TT> variable
is set to either <TT><FONT FACE="Courier">REG_CREATED_NEW_KEY</FONT></TT>
or <TT><FONT FACE="Courier">REG_OPENED_EXISTING_KEY</FONT></TT>.
If a new key is opened, the current process owns this key and
locks access to it until the key is released. A returned value
of the existing key specifies that another process owns the lock
to the returned key.
</BLOCKQUOTE>
<H5>NTRegDeleteKey</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">NTRegDeleteKey</FONT></TT> function
deletes the named <TT><FONT FACE="Courier">$subkey</FONT></TT>
under the <TT><FONT FACE="Courier">$hkey</FONT></TT>. This function
cannot delete a key that has any existing subkeys. The subkey
to be deleted must be a subkey of the key identified by <TT><FONT FACE="Courier">$hkey</FONT></TT>.
The syntax for this function is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegDeleteKey $hkey, $subkey</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The key must already exist before it can be deleted.
</BLOCKQUOTE>
<H5>NTRegDeleteValue</H5>
<BLOCKQUOTE>
This <TT><FONT FACE="Courier">NTRegDeleteValue</FONT></TT> function
resets the value of an existing key. The syntax is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegDeleteValue $hkey, VALUE</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The key must already exist with a value before it can be reset.
</BLOCKQUOTE>
<H5>NTRegEnumKey</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">NTRegEnumKey</FONT></TT> function
is an old function for retrieving names of subkeys. For newer
applications, use the <TT><FONT FACE="Courier">NTRegEnumKeyEx</FONT></TT>
call. The syntax for this old call is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegEnumKey $hkey, $index, $keyname</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
In the Registry, subkeys are not ordered. Therefore, the returned
value can be in any order, and you must sort the returned values
yourself. To use this function, call the <TT><FONT FACE="Courier">NTRegEnumKey</FONT></TT>
function with the <TT><FONT FACE="Courier">$index</FONT></TT>
set to zero:
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$index = 0;<BR>
while(&amp;NTRegEnum($hkey,$index,$keyname) != false) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;printf &quot; [%d] = %s \n&quot;, $index++,
$keyname;<BR>
}</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The last key in the list is retrieved with a call to <TT><FONT FACE="Courier">NTRegQueryInfoKey</FONT></TT>.
Do not change the value of or create new keys while you are iterating
through the list of keys because you may change the order in which
the keys are listed. To open the key in <TT><FONT FACE="Courier">$hkey</FONT></TT>,
use the <TT><FONT FACE="Courier">RegCreateKeyEx</FONT></TT> or
<TT><FONT FACE="Courier">RegOpenKeyEx</FONT></TT> function with
<TT><FONT FACE="Courier">KEY_ENUMERATE_SUB_KEYS</FONT></TT> access.
</BLOCKQUOTE>
<H5>NTRegEnumKeyEx</H5>
<BLOCKQUOTE>
The syntax for this function is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegEnumKeyEx $hkey, $index, $subKeyName,
NULL, $class, $lastWrite</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">NTRegEnumKeyEx</FONT></TT> function
enumerates subkeys of the open key <TT><FONT FACE="Courier">$hkey</FONT></TT>,
returning the <TT><FONT FACE="Courier">$subKeyName</FONT></TT>,
<TT><FONT FACE="Courier">$class</FONT></TT>, and time of <TT><FONT FACE="Courier">$lastWrite</FONT></TT>
for the key indexed by <TT><FONT FACE="Courier">ISUBKEY</FONT></TT>.
The function retrieves information about one subkey each time
it is called. Unlike the <TT><FONT FACE="Courier">NTRegEnumKey</FONT></TT>
function, <TT><FONT FACE="Courier">NTRegEnumKeyEx</FONT></TT>
retrieves the class name of the subkey and the time it was last
modified.
</BLOCKQUOTE>
<BLOCKQUOTE>
The calling convention for running through the keys is the same
as that for <TT><FONT FACE="Courier">NTRegEnumKey</FONT></TT>.
</BLOCKQUOTE>
<H5>NTRegEnumValue</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">NTRegEnumValue</FONT></TT> function
enumerates the values for the key specified in <TT><FONT FACE="Courier">$hkey</FONT></TT>.
The function takes one value in <TT><FONT FACE="Courier">$name</FONT></TT>
and the <TT><FONT FACE="Courier">$data</FONT></TT> block. It can
also take types in <TT><FONT FACE="Courier">$data</FONT></TT>
as listed in the <TT><FONT FACE="Courier">NT.ph</FONT></TT> file.
The index for the <TT><FONT FACE="Courier">$data</FONT></TT> type
is in <TT><FONT FACE="Courier">$integerValue</FONT></TT>. The
syntax for this call is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegEnumValue $hkey, $integerValue,
$name, $type, NULL, $data</FONT></TT>
</BLOCKQUOTE>
<H5>NTRegFlushKey $hkey</H5>
<BLOCKQUOTE>
The <TT><FONT FACE="Courier">RegFlushKey</FONT></TT> function
writes all the contents and parameters of the open key <TT><FONT FACE="Courier">$hkey</FONT></TT>
into the Registry. The function returns after the data has been
completely written to disk. The syntax for this command is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegFlushKey $hkey</FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
Registry changes are flushed automatically to disk by the Registry
using a lazy write mechanism at shutdown time. Call this function
to write any modifications immediately to disk. An important point
to remember is that this function may also flush contents of other
keys.
</BLOCKQUOTE>
<H5>NTRegGetKeySecurity</H5>
<BLOCKQUOTE>
This function gets a copy of the security descriptor protecting
the open Registry key <TT><FONT FACE="Courier">$hkey</FONT></TT>.
The requested security information is specified in <TT><FONT FACE="Courier">$securityInfo</FONT></TT>,
and the returned descriptor is stored in <TT><FONT FACE="Courier">$descriptor</FONT></TT>.
The syntax for this function is
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">NTRegGetKeySecurity $hkey, $descriptor,
$securityInfo</FONT></TT>
</BLOCKQUOTE>
<H5>NTRegLoadKey</H5>
<BLOCKQUOTE>
The syntax for the <TT><FONT FACE="Courier">NTRegLoadKey</FONT></TT>
function is
</BLOCKQUOTE>