ch10.htm

《Perl 5 Unreleased》

17 &ErrorMsg;    # Tell me if there were
any errors. :w<BR>
18<BR>
19 $pobj-&gt;FindNext();<BR>
20 &amp;ErrorMsg;&nbsp;&nbsp;&nbsp;&nbsp;# Tell me if there were
any errors. :w<BR>
21 $pobj-&gt;Wait(8000);<BR>
22 print &quot;Hey! Someone's messing with drive D: \n&quot; ;
<BR>
23 $pobj-&gt;Close;</FONT></TT>
</BLOCKQUOTE>
<HR>
<H2><A NAME="TheWin32EventlogModule"><FONT SIZE=5 COLOR=#FF0000>The
</FONT><TT><FONT SIZE=5 COLOR=#FF0000 FACE="Courier">Win32::Eventlog</FONT></TT><FONT SIZE=5 COLOR=#FF0000>
Module</FONT></A></H2>
<P>
The Windows NT system tracks events in the system using an event
logging facility. Perl scripts can read, modify, and extract information
from log records. This feature is a very powerful tool to use
when generating status reports about a system.
<P>
Before you use <TT><FONT FACE="Courier">Win32::Eventlog</FONT></TT>,
you have to open an event log and associate a <TT><FONT FACE="Courier">Win32::Eventlog</FONT></TT>
object with it. Here's the call to do this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Open Win32::EventLog($EventObj, $sourceName,
[$serverName]);</FONT></TT>
</BLOCKQUOTE>
<P>
On returning from this function, the <TT><FONT FACE="Courier">$EventObj</FONT></TT>
variable will be set to a reference to an <TT><FONT FACE="Courier">EventLog</FONT></TT>
object. The name of the source for the events that will be set
is <TT><FONT FACE="Courier">$sourceName</FONT></TT>. The <TT><FONT FACE="Courier">$ServerName</FONT></TT>
variable is optional and, if omitted or explicitly set to <TT><FONT FACE="Courier">NULL</FONT></TT>,
will be set to the local machine.
<P>
You can even create your own backups by using the <TT><FONT FACE="Courier">Backup</FONT></TT>
method on the <TT><FONT FACE="Courier">$EventObj</FONT></TT> object.
The file is created and the events in the current event log in
the <TT><FONT FACE="Courier">$EventObj</FONT></TT> object are
written to.
<P>
Any previously written file will be overwritten if a file with
the same name already exists. The syntax for this command is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Backup( $filename );</FONT></TT>
</BLOCKQUOTE>
<P>
where <TT><FONT FACE="Courier">$filename</FONT></TT> is the string
of the file to which to write the event log.
<H3><A NAME="ReadingEvents">Reading Events</A></H3>
<P>
To read events in a backup or event log, you have to use the <TT><FONT FACE="Courier">Read()</FONT></TT>
method on the <TT><FONT FACE="Courier">$EventObject</FONT></TT>.
The syntax for the <TT><FONT FACE="Courier">Read()</FONT></TT>
method is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Read($readFlags,$recordOffset,%EventInfo);</FONT></TT>
</BLOCKQUOTE>
<P>
The<TT><FONT FACE="Courier"> $readFlags</FONT></TT> variable is
set to specify how to read the events. The <TT><FONT FACE="Courier">$recordNumber</FONT></TT>
variable is set to the index (starting from 1, not 0). The hash
<TT><FONT FACE="Courier">%EventInfo</FONT></TT> is set to the
returned event's value. <TT><FONT FACE="Courier">$readFlag</FONT></TT>
can be set to a combination of these values:<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=253><TT><FONT FACE="Courier">EVENTLOG_FORWARDS_READ</FONT></TT>
</TD><TD WIDTH=337>Reads in forward chronological order. Cannot be used with <TT><FONT FACE="Courier">EVENTLOG_BACKWARDS_READ</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=253><TT><FONT FACE="Courier">EVENTLOG_BACKWARDS_READ</FONT></TT>
</TD><TD WIDTH=337>Reads in reverse chronological order. Cannot be used with <TT><FONT FACE="Courier">EVENTLOG_FORWARDS_READ</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=253><TT><FONT FACE="Courier">EVENTLOG_SEEK_READ</FONT></TT>
</TD><TD WIDTH=337>Reads from record number specified in <TT><FONT FACE="Courier">$RecordOffset</FONT></TT>. You must specify the direction in which you are to read the file by setting either <TT><FONT FACE="Courier">EVENTLOG_FORWARDS_READ</FONT></TT> or 
<TT><FONT FACE="Courier">EVENTLOG_BACKWARDS_READ</FONT></TT>.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=253><TT><FONT FACE="Courier">EVENTLOG_SEQUENTIAL_READ</FONT></TT>
</TD><TD WIDTH=337>Reads from the next record after the previous <TT><FONT FACE="Courier">read</FONT></TT> operation.
</TD></TR>
</TABLE></CENTER>
<H3><A NAME="ReportingtheContentsofanEvent">Reporting the Contents
of an Event</A></H3>
<P>
To get a report of what you have just read, you can use the <TT><FONT FACE="Courier">Report()</FONT></TT>
method. The syntax for this call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Report($eventType, %EventInfo );</FONT></TT>
</BLOCKQUOTE>
<P>
<TT><FONT FACE="Courier">$eventType</FONT></TT> is the type of
event and <TT><FONT FACE="Courier">%EventInfo</FONT></TT> is the
returned value of an <TT><FONT FACE="Courier">%EVENTINFO</FONT></TT>
hash, which is usually the value returned from a <TT><FONT FACE="Courier">Read()</FONT></TT>
call. The options for <TT><FONT FACE="Courier">$eventType</FONT></TT>
are<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=289>EVENTLOG_ERROR_TYPE</TD><TD WIDTH=146>Error event
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=289>EVENTLOG_WARNING_TYPE</TD><TD WIDTH=146>Warning event
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=289>EVENTLOG_INFORMATION_TYPE</TD><TD WIDTH=146>Information event
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=289>EVENTLOG_AUDIT_SUccESS_TYPE</TD><TD WIDTH=146>Success audit event
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=289>EVENTLOG_AUDIT_FAILURE_TYPE</TD><TD WIDTH=146>Failure audit event
</TD></TR>
</TABLE></CENTER>
<P>
<TT><FONT FACE="Courier">%EventInfo</FONT></TT> hash can be parsed
with the following keys:<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=138><TT><FONT FACE="Courier">Category</FONT></TT>
</TD><TD WIDTH=391>An application-specific integer value for the type of event
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=138><TT><FONT FACE="Courier">EventID</FONT></TT>
</TD><TD WIDTH=391>A source-specific ID value of the event</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=138><TT><FONT FACE="Courier">EventRawData</FONT></TT>
</TD><TD WIDTH=391>Any application-specific raw binary data</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=138><TT><FONT FACE="Courier">Strings</FONT></TT>
</TD><TD WIDTH=391>Any application text strings</TD></TR>
<TR VALIGN=TOP><TD WIDTH=138><TT><FONT FACE="Courier">user</FONT></TT></TD>
<TD WIDTH=391>User name to which this event applies</TD></TR>
</TABLE></CENTER>
<P>
<P>
Three other functions also exist to get more information about
the position of events in a file. The returned values of these
functions can be used to specify what event record you are going
to process data from. Keep in mind that records are indexed by
starting at 1 and not 0.
<UL>
<LI><FONT COLOR=#000000>The</FONT> <TT><FONT FACE="Courier">GetOldest($recnum)</FONT></TT>
function sets the value of <TT><FONT FACE="Courier">$recnum</FONT></TT>,
the absolute record number of the last record in the event source.
<LI><FONT COLOR=#000000>The </FONT><TT><FONT FACE="Courier">GetNumber(
$NumberOfEvents )</FONT></TT> function returns the number of events.
<LI><FONT COLOR=#000000>The </FONT><TT><FONT FACE="Courier">Clear(
$filename )</FONT></TT> function clears the event log in the current
event file. If the <TT><FONT FACE="Courier">$filename</FONT></TT>
option is not given, the current event log is not written to the
file. If the <TT><FONT FACE="Courier">$filename</FONT></TT> option
is given and you have permissions to write to this directory,
the current event log is written to the file.
</UL>
<H2><A NAME="TheWin32RegistryModule"><FONT SIZE=5 COLOR=#FF0000>The
</FONT><TT><FONT SIZE=5 COLOR=#FF0000 FACE="Courier">Win32::Registry</FONT></TT><FONT SIZE=5 COLOR=#FF0000>
Module</FONT></A></H2>
<P>
The <TT><FONT FACE="Courier">Win32::Registry</FONT></TT> module
lets you work with the Windows NT Registry model. The way to start
working with the model is to first create a <TT><FONT FACE="Courier">Win32::Registry</FONT></TT>
object with the <TT><FONT FACE="Courier">open()</FONT></TT> call
for a key. The syntax for the open call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Win32::Registry::Open($RegistryObj,$key
)</FONT></TT>
</BLOCKQUOTE>
<P>
<TT><FONT FACE="Courier">$RegistryObj</FONT></TT> returns a reference
to a reference object for the predefined key specified in <TT><FONT FACE="Courier">$key</FONT></TT>.
If the specified key does not exist, it is not created. <TT><FONT FACE="Courier">$key</FONT></TT>
can only hold any already opened key.
<P>
When the <TT><FONT FACE="Courier">Registry</FONT></TT> module
is loaded, four <TT><FONT FACE="Courier">Registry</FONT></TT>
objects are created in the <TT><FONT FACE="Courier">main:: namespace</FONT></TT>.
These predefined Registry objects can be referred to by the generic
names within Windows NT:
<UL>
<LI><TT><FONT FACE="Courier">LOCAL_MAchINE</FONT></TT>
<LI><TT><FONT FACE="Courier">USERS</FONT></TT>
<LI><TT><FONT FACE="Courier">CURRENT_USER</FONT></TT>
<LI><TT><FONT FACE="Courier">CLASSES_ROOT</FONT></TT>
</UL>
<P>
To create a new key, you have to use the <TT><FONT FACE="Courier">Create()</FONT></TT>
call. Here's the syntax for the <TT><FONT FACE="Courier">Create()</FONT></TT>
call:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Win32::Registry::Create($RegistryObj,$key
)</FONT></TT>
</BLOCKQUOTE>
<P>
where <TT><FONT FACE="Courier">$RegistryObj</FONT></TT> returns
a reference to a <TT><FONT FACE="Courier">Registry</FONT></TT>
object. The <TT><FONT FACE="Courier">$key</FONT></TT> variable
contains the name of a key. If the key exists, then the <TT><FONT FACE="Courier">create</FONT></TT>
function will open it; otherwise, it will create a new key and
return a reference to it. The user must have the security privileges
to create a key.
<P>
Once you have a key in an object, you can get its value with the
<TT><FONT FACE="Courier">QueryValue</FONT></TT> method. The syntax
for the <TT><FONT FACE="Courier">QueryValue</FONT></TT> method
is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;QueryValue($subKey,$valueRef);</FONT></TT>
</BLOCKQUOTE>
<P>
Given the name of the subkey of the <TT><FONT FACE="Courier">regObject</FONT></TT>
in <TT><FONT FACE="Courier">$subKey</FONT></TT>, the <TT><FONT FACE="Courier">QueryValue</FONT></TT>
function sets the value of the variable at <TT><FONT FACE="Courier">$valueRef</FONT></TT>.
To get more information about a key, you can use the <TT><FONT FACE="Courier">QueryKey</FONT></TT>
method with this calling syntax:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;QueryKey ($keyClass, $numSubkeys,
$numValues);</FONT></TT>
</BLOCKQUOTE>
<P>
All three arguments to this function are set to a value when the
function returns. On returning, <TT><FONT FACE="Courier">$keyClass</FONT></TT>
is set to a string specifying the class of the key. The <TT><FONT FACE="Courier">$numSubKeys</FONT></TT>
contains the number of subkeys, and the <TT><FONT FACE="Courier">$numValues</FONT></TT>
variable contains the number of values for the current key.
<P>
Keys can have more than one value associated with them. To get
these values from a key, call the <TT><FONT FACE="Courier">GetValues()</FONT></TT>
method. The syntax for this call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;GetValues(\%Values);</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">%Values</FONT></TT> hash is set to
the values in the <TT><FONT FACE="Courier">$regObject</FONT></TT>
key. The hash <TT><FONT FACE="Courier">%Values</FONT></TT> will
be keyed by deriving a value from the name and type of the object
to get a key of the form <TT><FONT FACE="Courier">{$name,$type,$data}</FONT></TT>.
<P>
The <TT><FONT FACE="Courier">GetKeys(\@Subkeys)</FONT></TT> function
returns a list of names of subkeys for a given key in the array
<TT><FONT FACE="Courier">@Subkeys</FONT></TT>. To get a list of
subkeys for an object, the call will be of this form:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;GetValues(\@subkeys);</FONT></TT>
</BLOCKQUOTE>
<P>
You can save the current key status (called <I>hive</I>) with
a call to the <TT><FONT FACE="Courier">Save()</FONT></TT> method
for a <TT><FONT FACE="Courier">Registry</FONT></TT> object. The
syntax for this method is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;Save( $filename);</FONT></TT>
</BLOCKQUOTE>
<P>
where <TT><FONT FACE="Courier">$filename</FONT></TT> is the name
of the file to save to.
<P>
To load the information about a subkey from a file on disk, you
can use the <TT><FONT FACE="Courier">Load</FONT></TT> method.
The syntax for this call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$regObject-&gt;Load( $subkey, $filename);</FONT></TT>
</BLOCKQUOTE>
<P>