NAME
      Parse::EventLog - Parse information from Windows Event Logs

SYNOPSIS
     use Parse::EventLog;
     my $elog =
      Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

     my %c = $elog->getNewestEvent();
     # Do something interesting here.

     while (%c = $elog->getPreviousEvent()) {
      print localtime($c{TimeGenerated}) .
       ": $c{EventID} generated by $c{Source} on $c{Computer}.\n";
      # Do a lot of interesting somethings here.
     }

DESCRIPTION
    Parse::EventLog is a module designed to allow parsing of binary Windows
    2000+ Event Logs on any platform. For better Event Log parsing on
    Windows platforms, see Win32::EventLog.

    When instansiated with the location of an Event Log file, you will be
    able to walk through the existing events in chronological order from
    oldest to newest or vice versa, as well as being able to extract the
    whole log to a hash table and seek through however you wish.

METHODS
  new
     my $eventlog =
      Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

    Parse::EventLog constructor, called with the location of the event log
    file to open. Returns a Parse::EventLog object or dies on error. Stores
    the internal record pointer at the newest event, so the next call to
    getPreviousEvent will succeed but getNextEvent will fail (there are no
    newer events).

  getOldestEvent
     my %event = $eventlog->getOldestEvent();

    Returns a hash table containing the oldest entry in the event logand
    moves the current event pointer to the oldest event.

  getNewestEvent
     my %event = $eventlog->getNewestEvent();

    Returns a hash table containing the newest entry in the event log and
    moves the current event pointer to the newest event.

  getNextEvent
     my %event = $eventlog->getNextEvent();

    Moves us forward in time, returning a hash table containing the next
    event in the event log. Returns an empty array/hashtable if there are no
    more events to get.

  getPreviousEvent
     my %event = $eventlog->getPreviousEvent();

    Moves us backward in time, returning a hash table containing the
    previous event in the event log. Returns an empty array/hashtable if
    there are no more events to get.

  getAll
     my %event = $eventlog->getAll();

    Returns a copy of the internal Event Log hash table for your own
    nefarious pleasure. The main hash table is keyed by the internal
    RecordNumber (which is unique to each entry in the file). The value of
    each of those keys is another hash table containing the actual event (in
    the same format as is returned by the other get*Event functions).

   Example
     my %c = $eventlog->getAll();
     foreach my $a (keys %c) {
      print 'Time: ' . localtime($c{$a}{'TimeGenerated'} . "\n";
      print "Computer: $c{$a}{'Computer'}\n";
      print "Source: $c{$a}{'Source'}\n";
      print 'Type: ' . GetEventType($c{$a}{'EventType'}) . "\n";
      print '-' x 10;
     }

  count
     my $count = $eventlog->count();

    Returns the number of entries loaded from the event log.

FUNCTIONS
  GetEventType
     print 'Event type:' . GetEventType($c{'EventType'}) . "\n";

    Returns a string containing the type of event (Error, Warning,
    Information, Audit Success, Audit Failure, or Unknown).

    GetEventType is exported by default.

CONSTANTS
    Several constants are exported by default. These constants are Event
    Type definitions. They are as follows:

    * EVENT_ERROR (1)
    * EVENT_WARNING (2)
    * EVENT_INFORMATION (4)
    * EVENT_AUDIT_SUCCESS (8)
    * EVENT_AUDIT_FAILURE (16)

RETURN VALUES
    On success, all of the get*Event functions return a hash of the current
    Event. The hash itself has several keys made up of each of the values in
    the Event itself. The following keys are defined (note the capitals):

  TimeGenerated
    The epoch time the event was generated, suitable for feeding to gmtime
    and localtime.

  TimeWritten
    The epoch time the event was written to the event log, usually the same
    as TimeGenerated (give or take a second). Suitable for feeding to gmtime
    and localtime.

  RecordNumber
    The record number of the event. This is assigned and due to the binary
    nature of the file, and can not be expected to be consistant or unique
    on subsequent parsings of the same file.

  EventID
    The event identification number, vendor and application specific.
    Details can often be found in the Microsoft Knowledge Base.

  EventType
    The event type, vendor and application specific.

  Source
    Source of the event, usually the application or service name.

  Computer
    The name of the computer that generated the event.

  SID
    The SID associated with the entry. It is unknown whether this is the SID
    of the source PC, the PC the log was stored on, the user, or something
    else.

  NumStrings
    Number of strings in the event.

  Strings
    An array reference to all (if any) of the strings included with the
    event. Events work a lot like printf format strings, that is, there is a
    fixed message with a variable part, such as:

     The %s service failed to start due to the following error:
     The system cannot find the file specified.

    In this case, the Strings parameter would contain the name of the
    service that would be placed in %s above to complete the event message.

TO DO
    * Support for random access reads.
    * Parsing without loading the whole file into memory. By default, the
    files are only 64k, but it's possible to specify a much larger size.
    * Descriptions for general Microsoft Windows events.
    * Rename/alias getNextEvent and getPreviousEvent to getNewerEvent and
    getOlderEvent?

KNOWN BUGS
    * Occasional spurious Strings are read from the Event Log. It seems the
    log itself specifies they should be there, but there is only garbage
    data to be read.
    * Incomplete parsing. Due to the mysterious nature of the Event Logs and
    the lack of documentation on their format, there are several unknown
    fields in the log. These fields are currently ignored. If anyone knows
    what these fields are for, please let me know.

CAVEATS
    While this module can extract general information on the events, most of
    the error description is stored in system libraries specific to the
    Windows version and patch level that created the log. At this time,
    Parse::EventLog does not have a facility to extract that data.

    Assume the Event Viewer shows the following event description:

     The Print Spooler service was successfully sent a stop control.

    The data to build this description is stored in two locations. The
    first, a DLL file associated with the Service Control Manager, contains
    the string:

     The %s service was successfully sent a %s control.

    The Event Log itself contains the strings:

     Print Spooler
 
    and

     stop

    Unfortunately, at this time Parse::EventLog is not able to extract the
    string data from files outside of the Event Log itself, only the strings
    contained within it. At this time, I recommend either parsing the events
    on the Windows server itself (via Win32::EventLog or a syslog plugin) or
    manually looking up the data elsewhere.

SEE ALSO
    Win32::EventLog

THANKS
    Thanks to Malik of www.whitehats.ca for the initial data structure
    format that this module was based on. See:
    <http://www.whitehats.ca/main/members/Malik/malik_eventlogs/malik_eventl
    ogs.html> for more details and his origional work.

COPYRIGHT
    Copyright 2005-2006, John Eaglesham

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.