win32-eventlog 0.4.2

data/CHANGES

@@ -0,0 +1,139 @@
+= 0.4.2 - 6-Aug-2006
+* Fixed a bug in the EventLog.read method related to the
+  EVENTLOG_BACKWARDS_READ flag.
+* Fixed a bug in the EventLog.read method where the event_type was not being
+  set properly.  Thanks go to "TheR" for the spot and the fix.
+* Fixed bugs in the EventLog#tail method where it would fail if the log was
+  full and dups would appear.
+
+= 0.4.1 - 28-May-2006
+* Fixed a bug in the EventLog#notify_change method where the handle would
+  die after five or six reads.  Thanks go to botp for the spot.
+
+= 0.4.0 - 24-May-2006
+* Now pure Ruby.
+* Now includes a gemspec.
+* Fixed a major bug the EventLog#tail method where it was reading the log in
+  the wrong order (!!!).
+* Fixed a bug in the EventLog#report_event with regards to long category_id's.
+  Actually, this wasn't so much "fixed" as "avoided" by virtue of using a
+  pure Ruby solution.
+* Added the EventLog#full? method.
+* Documentation updates and corrections, including the tutorial on creating
+  and writing to your own event source.
+  
+== 0.3.3 - 2-Jan-2006
+* If EventLog.new fails, it now raises EventLogError instead of StandardError.
+* Added documentation to the eventlog.txt file for EventLog#notify_change.
+* Added inline rdoc to the C source code.
+* Code cleanup.
+
+== 0.3.2 - 26-May-2005
+* Code now more Unicode friendly, and other cleanup.
+* Made the .txt files rdoc friendly, and removed the .rd files.
+* Minor adjustments to the test suite.
+
+== 0.3.1 - 16-Feb-2005
+* Minor modifications to the source to eliminate some warnings that appeared
+  in Ruby 1.8.2 or later, plus other minor tweaks.
+* Renamed the sample programs and moved the 'examples' directory to the
+  toplevel directory.
+* Made this document rdoc friendly.
+
+== 0.3.0 - 30-Oct-2004
+* Added the notify_change() and tail() methods.
+* Added the write() alias for report_event().
+* The read() class and instance methods now return an array of structs if
+  no block is given.
+* Added the 'rubymsg.mc' message category file.  If installed, this will
+  create a 'RubyMsg' event source for use with win32-service, though you
+  may use it for whatever you wish.  See the README for more details. 
+* Renamed struct back to EventLogStruct - sorry, sorry - I promise I won't
+  change this again.
+* Fixed a bug where using EventLog::SEEK_READ did not work properly (thanks
+  Park).
+* Added the notify.rb test script under doc/examples.
+
+== 0.2.5 - 28-Oct-2004
+* Modified the open() and read() class methods to default to "Application"
+  for the default Event source.
+* Removed the .html files.  You can generate these on your own with rd2.
+
+== 0.2.4 - 19-Oct-2004
+* Fixed a bug where a segfault would result if an Event Log entry were
+  somehow corrupted.  Thanks go again to Joey Gibson for the spot.
+* Very minor doc corrections in tutorial.txt and eventlog.txt
+
+== 0.2.3 - 14-Oct-2004
+* Fixed a bug where some Event Log descriptions were returning nil instead
+  of the actual description.  Thanks go to Joey Gibson for the spot.
+* Minor test suite and doc additions, including a "future plan" that may
+  be of interest.
+
+== 0.2.2 - 02-Jul-2004
+* Fixed a bug in the read() method where not all the records were being
+  returned.
+* Fixed calls to rb_time_new() - second argument appears to be mandatory as
+  of 1.8.2.
+* Renamed struct returned by read() to "EventLog".
+* Changed struct members "id" and "type" to "event_id" and "event_type",
+  respectively.  This was to avoid any confusion with the builtin Ruby
+  methods of the same name.
+* Replaced STR2CSTR() with StringValuePtr(), as the former is deprecated.
+  This means that as of this version, Ruby 1.8.0 or later is required.
+* Moved the sample programs to doc/examples.
+
+== 0.2.1 - 04-Mar-2004
+* The add_event_source() and report_event() methods now accept symbols as
+  well as do key validation.
+* Moved the EventLogError class under the Win32 module.
+* Normalized the tc_eventlog.rb and tc_mc.rb scripts by making it easier to
+  run them standalone from another directory.
+* Minor modification to the build process.
+* Added a test_write.rb script for general futzing when it comes to creating
+  and writing events to the log.
+* Doc updates, warranty information added.
+
+== 0.2.0 - 1-Feb-2004
+* Changed the Win32EventLogError class to just EventLogError.  I felt the
+  Win32 was redundant given that the class is already under the Win32 module.
+* Fixed bug where bogus error messages were returned because I was calling
+  GetLastError() too late.
+* Fixed bug where error messages were getting cut off and/or garbled due to
+  \r\n character.  (Thanks Park Heesob).
+* Added open_backup class method.
+
+== 0.1.4 - 16-Jan-2004
+* Slightly better handling of the EventLog#close method.  Adopted from code
+  previously submitted by Park Heesob.
+* Fixed a bug in the (internal) GetUser() function that caused a segfault if
+  there were 250+ records.  That function has been greatly simplified.
+* Removed the rb_ensure() approach.  What I thought was a memory leak was not,
+  in fact, a memory leak.  Also, it was slowing down the method considerably.
+* Minor test suite update.
+
+== 0.1.3 - 7-Jan-2004
+* Fixed memory leaks in read() method (Park Heesob).
+* Added read() class method (Daniel Berger).
+* Test suite and doc additions & updates
+
+== 0.1.2 - 30-Nov-2003
+* Added the report_event method.  You can now write to the event log.
+* Added the add_event_source class method, allowing you to register a custom
+  event source.
+* Added the win32-mc package to the distribution.  This is a simple
+  wrapper to generate .dll files from .mc files.
+* Added Event Type constants
+* Test suite additions
+* Documentation updates and additions, including a small tutorial.
+
+== 0.1.1 - 5-Nov-2003
+* Fixed the free() call, and added implicit eventlog closing (when the
+  EventLog object is free'd).
+* Simplified constants by removing 'EVENTLOG_' portion of name.
+* Cleanup in the GetDescription() method, which was causing segfaults in
+  conjunction with TestUnit.
+* Minor doc updates and cleanup.
+
+== 0.1.0 - 14-Oct-2003
+* Initial release

data/MANIFEST

@@ -0,0 +1,22 @@
+MANIFEST
+CHANGES
+README
+install.rb
+win32-eventlog.gemspec
+
+doc/tutorial.txt
+
+examples/test_read.rb
+examples/test_write.rb
+examples/test_notify.rb
+
+lib/win32/eventlog.rb
+lib/win32/mc.rb
+
+misc/install_msg.rb
+misc/rubymsg.mc
+
+test/foo.mc
+test/ts_all.rb
+test/tc_eventlog.rb
+test/tc_mc.rb

data/README

@@ -0,0 +1,63 @@
+= What is it?
+An interface to the Windows Event Log.
+
+= Prerequisites
+Ruby 1.8.2 or later.
+windows-pr 0.5.0 or later.
+
+= Installation
+== Manual install
+ruby test\tc_eventlog.rb (optional)
+ruby install.rb
+== Gem Install
+ruby win32-eventlog.gemspec
+gem install win32-eventlog-X.Y.Z-mswin32.gem
+
+This will install both the win32-eventlog and win32-mc packages.  The latter
+is strictly for turning .mc files into .dll files.  See the mc documentation
+for more details.
+
+= Installing the 'RubyMsg' event source
+If you wish to install the RubyMsg event source, run the 'install_msg.rb'
+script in the 'misc' directory.  This will create a 'rubymsg' directory under
+your toplevel Ruby installation directory (usually C:\ruby), and create the
+.dll, .h, .rc and .res files there, in addition to copying the rubymsg.mc file.
+It will then install the 'RubyMsg' event source into your registry.
+
+DO NOT MOVE THE DLL FILE ONCE IT IS INSTALLED!  If you do, you will have
+to delete the registry entry and reinstall it with the correct path.
+
+Take a look at the rubymsg.mc file for the category and message values.  If
+you do not understand this, please read the 'tutorial.txt' file in the 'doc'
+directory.
+
+= Additional documentation
+If you are unfamiliar with message files and event logging on Windows in
+general, please read the 'tutorial.txt' file.
+
+There are also a couple of sample test scripts under the 'examples'
+directory if you want to futz around and get a feel for how things work.
+
+= If the tc_mc.rb tests fail
+There's a chance that you either don't have the mc, rc and/or link commands
+installed or they're not in your %PATH%.  If you have MSVC++, you should have
+them somewhere on your system.
+
+= Known Issues
+You may see this warning during the build and/or test phase:
+
+LINK : warning LNK4068: /MACHINE not specified; defaulting to X86
+
+You may ignore this warning.
+
+= License
+Ruby's
+
+= Warranty
+This package is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantability and fitness for a particular purpose.
+
+= Authors
+Daniel J. Berger
+Park Heesob

data/doc/tutorial.txt

@@ -0,0 +1,140 @@
+= Information about Message Files
+Each event source should register message files that contain description
+strings for each event identifier, event category, and parameter. Register
+these files in the EventMessageFile, CategoryMessageFile, and
+ParameterMessageFile registry values for the event source.
+
+Note: ParameterMessageFiles are not yet supported in the add_event_source
+method and probably won't be unless requested.
+
+You can create one message file that contains descriptions for the event
+identifiers, categories, and parameters, or create three separate message
+files. Several applications can share the same message file.
+
+You should typically create message files as resource-only DLLs. They are
+smaller and faster than ordinary DLLs.
+
+= What does a .mc file look like?
+
+A .mc file is just a plain text file that is parsed by the "mc" utility to
+generate a header and, ultimately, a .dll file.  Here is a quick sample.
+Note that there must be a newline after the last '.' at the bottom.
+The ';' character denotes a comment.
+
+; foo.mc
+MessageId=0x1
+SymbolicName=CATEGORY_ERROR
+Language=English
+error
+.
+
+MessageId=0x2
+SymbolicName=CATEGORY_WARNING
+Language=English
+warning
+.
+
+MessageId=0x3
+Severity=Error
+SymbolicName=FOO_ERROR
+Language=English
+Error: %1
+.
+
+= How to generate a .dll file from a .mc file
+To turn this file into a .dll you have two options.  The first is to use the
+command line utilities.  Follow these steps:
+
+1) mc filename.mc
+2) rc -r -fo filename.res filename.rc
+3) link -dll -noentry -out:filename.dll filename.res
+
+Your other option is to use the win32-mc package, which is a simple wrapper
+for the above commands, and is included with this package.  You now have a
+dll that you can associate with your event source (i.e. the one you associate
+with your application).  You can also take a look at the C header file that
+.mc generates and use that in your own extensions if you like.
+
+After this you'll need to register your event source and associate the .dll
+file with it.  To do that, use the EventLog.add_event_source method.  Be sure
+to specifiy the number of categories manually - it is not calculated
+automatically by the OS.
+
+Returning to the .mc file, the example I used actually creates two categories,
+"error" and "warning", and one event message.  The numbers you assign here
+create corresponding (though not identical) values in the header file that
+is generated.  It is the values found in the header file that you pass to the
+EventLog#report_event method for the category or event id.  Here's the
+relevant data from the foo.h file (using foo.mc above):
+
+#define CATEGORY_ERROR 0x00000001L
+#define CATEGORY_WARNING 0x00000002L
+#define FOO_ERROR 0xC0000003L
+
+In the case of categories, that number is the name number that shows up in the
+"category" field in the Event Viewer.  In the case of event message files, it
+is the text that shows up in the event description.
+
+The "data" field is what replaces "%1" as an actual text string in the event
+log, sort of like a printf (except that it's always a string).
+
+= Registering an event source
+First, create the .dll file from the .mc file.  Then register that .dll file
+for an event source we'll call "foo".  You can name the .dll file anything
+you like, but for sanity's sake I recommend keeping the same as the event
+source name.
+
+require "win32/eventlog"
+include Win32
+
+dll_file = "c:\\wherever\\foo.dll"
+
+EventLog.add_event_source(
+   "source"                => "Application",
+   "key_name"              => "foo",
+   "category_count"        => 2,
+   "event_message_file"    => dll_file,
+   "category_message_file" => dll_file
+)
+
+After you run this, you can run regedit and see that your event source has
+been inserted into the registry.  You can find it under:
+
+HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application.
+
+= Writing to the event source
+Now that our event source "foo" is registered, we can begin writing event
+log data for it.  Here's an example of how you use it:
+
+require "win32/eventlog"
+include Win32
+
+EventLog.open("Application") do |log|
+   log.report_event(
+      :source     => "foo",
+      :event_type => EventLog::WARN,
+      :category   => "0x00000002L".hex,
+      :event_id   => "0xC0000003L".hex,
+      :data       => "I'm warning you!"
+   )
+end
+
+Note the values used for the 'category' and 'event_id' keys.  Those are the
+values that were generated automatically in the foo.h file that I showed you
+above.  You'll have to manually inspect the header file that's generated to
+determine which values you should be using.
+
+You can now open your event log viewer and look at the message.  You can get
+to your event log viewer via Start -> Control Panel -> Administrative Tools ->
+Event Viewer.  You should see a warning message with the category "warning"
+and an event id of '3'.  If you right click on that entry and select
+"properties", you can see the event description is "Warning: I'm warning you!".
+
+== More Info
+For more information visit the following URL's:
+
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tools/tools/message_text_file_syntax.asp
+
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/message_files.asp
+
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tools/tools/header_section.asp

data/lib/win32/eventlog.rb

@@ -0,0 +1,754 @@
+require 'windows/error'
+require 'windows/eventlog'
+require 'windows/security'
+require 'windows/registry'
+require 'windows/system_info'
+require 'windows/library'
+require 'windows/synchronize'
+require 'windows/handle'
+
+class String
+   # Return the portion of the string up to the first NULL character.  This
+   # was added for both speed and convenience.
+   def nstrip
+      self[ /^[^\0]*/ ]
+   end
+end
+
+module Win32
+   class EventLogError < StandardError; end
+   class EventLog
+      include Windows::Error
+      include Windows::EventLog
+      include Windows::Security
+      include Windows::Registry
+      include Windows::SystemInfo
+      include Windows::Library
+      include Windows::Synchronize
+      include Windows::Handle
+      extend Windows::Error
+      extend Windows::Registry
+      
+      VERSION = '0.4.2'
+      
+      # Aliased read flags
+      FORWARDS_READ   = EVENTLOG_FORWARDS_READ
+      BACKWARDS_READ  = EVENTLOG_BACKWARDS_READ
+      SEEK_READ       = EVENTLOG_SEEK_READ
+      SEQUENTIAL_READ = EVENTLOG_SEQUENTIAL_READ
+      
+      # Aliased event types
+      SUCCESS         = EVENTLOG_SUCCESS
+      ERROR           = EVENTLOG_ERROR_TYPE
+      WARN            = EVENTLOG_WARNING_TYPE
+      INFO            = EVENTLOG_INFORMATION_TYPE
+      AUDIT_SUCCESS   = EVENTLOG_AUDIT_SUCCESS
+      AUDIT_FAILURE   = EVENTLOG_AUDIT_FAILURE
+      
+      # These are not meant for public use
+      BUFFER_SIZE = 1024 * 64
+      MAX_SIZE    = 256
+      MAX_STRINGS = 16
+      BASE_KEY    = "SYSTEM\\CurrentControlSet\\Services\\EventLog\\"
+      
+      EventLogStruct = Struct.new('EventLogStruct', :record_number,
+         :time_generated, :time_written, :event_id, :event_type, :category,
+         :source, :computer, :user, :description
+      )
+      
+      # The name of the event log source.  This will typically be
+      # 'Application', 'System' or 'Security', but could also refer to
+      # a custom event log source.
+      # 
+      attr_reader :source
+      
+      # The name of the server which the event log is reading from.
+      # 
+      attr_reader :server
+      
+      # The name of the file used in the EventLog.open_backup method.  This is
+      # set to nil if the file was not opened using the EventLog.open_backup
+      # method.
+      # 
+      attr_reader :file
+      
+      # Opens a handle to the new EventLog +source+ on +server+, or the local
+      # machine if no host is specified.  Typically, your source will be
+      # 'Application, 'Security' or 'System', although you can specify a
+      # custom log file as well.
+      # 
+      # If a custom, registered log file name cannot be found, the event
+      # logging service opens the 'Application' log file.  This is the
+      # behavior of the underlying Windows function, not my own doing.
+      # 
+      def initialize(source = 'Application', server = nil, file = nil)
+         @source = source || 'Application' # In case of explicit nil
+         @server = server
+         @file   = file
+         
+         # Avoid Win32API segfaults
+         raise TypeError unless @source.is_a?(String)
+         raise TypeError unless @server.is_a?(String) if @server
+         
+         function = 'OpenEventLog()'
+         
+         if @file.nil?
+            @handle = OpenEventLog(@server, @source)
+         else
+            @handle = OpenBackupEventLog(@server, @file)
+            function = 'OpenBackupEventLog()'
+         end
+         
+         if @handle == 0
+            error = "#{function} failed: " + get_last_error
+            raise EventLogError, error
+         end
+         
+         # Ensure the handle is closed at the end of a block
+         if block_given?
+            begin
+               yield self
+            ensure
+               close
+            end
+         end
+      end
+      
+      # Class method aliases
+      class << self
+         alias :open :new
+      end
+      
+      # Nearly identical to EventLog.open, except that the source is a backup
+      # file and not an event source (and there is no default).
+      # 
+      def self.open_backup(file, source = 'Application', server = nil)
+         @file   = file
+         @source = source
+         @server = server
+         
+         # Avoid Win32API segfaults
+         raise TypeError unless @file.is_a?(String)
+         raise TypeError unless @source.is_a?(String)
+         raise TypeError unless @server.is_a?(String) if @server        
+				
+         self.new(source, server, file)         
+      end
+      
+      # Adds an event source to the registry.  The following are valid keys:
+      #   
+      # * source                - Source name.  Set to "Application" by default
+      # * key_name              - Name stored as the registry key
+      # * category_count        - Number of supported (custom) categories
+      # * event_message_file    - File (dll) that defines events
+      # * category_message_file - File (dll) that defines categories
+      # * supported_types       - See the 'event types' constants
+      #
+      # Of these keys, only +key_name+ is mandatory.  An ArgumentError is
+      # raised if you attempt to use an invalid key.  If +supported_types+
+      # is not specified then the following value is used:
+      #
+      # EventLog::ERROR | EventLog::WARN | EventLog::INFO
+      #
+      # The +event_message_file+ and +category_message_file+ are typically,
+      # though not necessarily, the same file.  See the documentation on .mc files
+      # for more details.
+      #     
+      def self.add_event_source(args)
+         raise TypeError unless args.is_a?(Hash)
+         
+         hkey = [0].pack('L')
+         
+         valid_keys = %w/source key_name category_count event_message_file
+            category_message_file supported_types/
+
+         key_base = "SYSTEM\\CurrentControlSet\\Services\\EventLog\\"
+
+         # Default values
+         hash = {
+            'source'          => 'Application',
+            'supported_types' => ERROR | WARN | INFO
+         }
+         
+         # Validate the keys, and convert symbols and case to lowercase strings.     
+         args.each{ |key, val|
+            key = key.to_s.downcase
+            unless valid_keys.include?(key)
+               raise ArgumentError, "invalid key '#{key}'"
+            end
+            hash[key] = val
+         }
+         
+         # The key_name must be specified
+         unless hash['key_name']
+            raise EventLogError, 'no event_type specified'
+         end
+         
+         key = key_base << hash['source'] << "\\" << hash['key_name']
+         
+         if RegCreateKey(HKEY_LOCAL_MACHINE, key, hkey) != ERROR_SUCCESS
+            error = 'RegCreateKey() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         
+         hkey = hkey.unpack('L').first
+         
+         if hash['category_count']
+            data = [hash['category_count']].pack('L')
+            
+            rv = RegSetValueEx(
+               hkey,
+               'CategoryCount',
+               0,
+               REG_DWORD,
+               data,
+               data.size
+            )
+            
+            if rv != ERROR_SUCCESS
+               error = 'RegSetValueEx() failed: ', get_last_error
+               RegCloseKey(hkey)
+               raise EventLogError, error
+            end
+         end
+         
+         if hash['category_message_file']
+            data = File.expand_path(hash['category_message_file'])
+            
+            rv = RegSetValueEx(
+               hkey,
+               'CategoryMessageFile',
+               0,
+               REG_EXPAND_SZ,
+               data,
+               data.size
+            )
+            
+            if rv != ERROR_SUCCESS
+               error = 'RegSetValueEx() failed: ', get_last_error
+               RegCloseKey(hkey)
+               raise EventLogError, error
+            end
+         end
+         
+         if hash['event_message_file']
+            data = File.expand_path(hash['event_message_file'])
+            
+            rv = RegSetValueEx(
+               hkey,
+               'EventMessageFile',
+               0,
+               REG_EXPAND_SZ,
+               data,
+               data.size
+            )
+            
+            if rv != ERROR_SUCCESS
+               error = 'RegSetValueEx() failed: ', get_last_error
+               RegCloseKey(hkey)
+               raise EventLogError, error
+            end
+         end
+         
+         data = [hash['supported_types']].pack('L')
+         rv = RegSetValueEx(
+            hkey,
+            'TypesSupported',
+            0,
+            REG_DWORD,
+            data,
+            data.size
+         )
+            
+         if rv != ERROR_SUCCESS
+            error = 'RegSetValueEx() failed: ', get_last_error
+            RegCloseKey(hkey)
+            raise EventLogError, error
+         end
+         
+         RegCloseKey(hkey)
+         self
+      end
+      
+      # Backs up the event log to +file+.  Note that you cannot backup to
+      # a file that already exists or a EventLogError will be raised.
+      # 
+      def backup(file)
+         raise TypeError unless file.is_a?(String)
+         unless BackupEventLog(@handle, file)
+            error = 'BackupEventLog() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         self
+      end
+      
+      # Clears the EventLog.  If +backup_file+ is provided, it backs up the
+      # event log to that file first.
+      # 
+      def clear(backup_file = nil)
+         raise TypeError unless backup_file.is_a?(String) if backup_file
+         backup_file = 0 unless backup_file
+          
+         unless ClearEventLog(@handle, backup_file)
+            error = 'ClearEventLog() failed: ' + get_last_error
+            raise EventLogError
+         end
+         
+         self
+      end
+      
+      # Closes the EventLog handle.  Automatically closed for you if you use
+      # the block form of EventLog.new.
+      # 
+      def close
+         CloseEventLog(@handle)
+      end
+      
+      # Indicates whether or not the event log is full.
+      # 
+      def full?
+         buf    = [0].pack('L') # dwFull
+         needed = [0].pack('L')
+         
+         unless GetEventLogInformation(@handle, 0, buf, buf.size, needed)
+            raise 'GetEventLogInformation() failed: ' + get_last_error
+         end
+
+         buf[0,4].unpack('L').first != 0
+      end
+      
+      # Returns the absolute record number of the oldest record.  Note that
+      # this is not guaranteed to be 1 because event log records can be
+      # overwritten.
+      # 
+      def oldest_record_number
+         rec = [0].pack('L')
+         
+         unless GetOldestEventLogRecord(@handle, rec)
+            error = 'GetOldestEventLogRecord() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         
+         rec.unpack('L').first
+      end
+      
+      # Returns the total number of records for the given event log.
+      # 
+      def total_records
+         total = [0].pack('L')
+         
+         unless GetNumberOfEventLogRecords(@handle, total)
+            error = 'GetNumberOfEventLogRecords() failed: '
+            error += get_last_error
+            raise EventLogError, error
+         end
+         
+         total.unpack('L').first
+      end
+      
+      # Yields an EventLogStruct every time a record is written to the event
+      # log. Unlike EventLog#tail, this method breaks out of the block after
+      # the event.
+      # 
+      # Raises an EventLogError if no block is provided.
+      # 
+      def notify_change(&block)
+         unless block_given?
+            raise EventLogError, 'block missing for notify_change()'
+         end
+         
+         # Reopen the handle because the NotifyChangeEventLog() function will
+         # choke after five or six reads otherwise.
+         @handle = OpenEventLog(@server, @source)
+         
+         if @handle == 0
+            error = "OpenEventLog() failed: " + get_last_error
+            raise EventLogError, error
+         end
+         
+         event = CreateEvent(0, 0, 0, 0)
+         
+         unless NotifyChangeEventLog(@handle, event)
+            error = 'NotifyChangeEventLog() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         
+         wait_result = WaitForSingleObject(event, INFINITE)
+         
+         if wait_result == WAIT_FAILED
+            error = 'WaitForSingleObject() failed: ' + get_last_error
+            CloseHandle(event)
+            raise EventLogError, error
+         else
+            last = read_last_event
+            block.call(last)
+         end
+   
+         CloseHandle(event)
+         self
+      end
+      
+      # Yields an EventLogStruct every time a record is written to the event
+      # log, once every +frequency+ seconds. Unlike EventLog#notify_change,
+      # this method does not break out of the block after the event.  The read
+      # +frequency+ is set to 5 seconds by default.
+      # 
+      # Raises an EventLogError if no block is provided.
+      # 
+      # The delay between reads is due to the nature of the Windows event log.
+      # It is not really designed to be tailed in the manner of a Unix syslog,
+      # for example, in that not nearly as many events are typically recorded. 
+      # It's just not designed to be polled that heavily.
+      #
+      def tail(frequency = 5)
+         unless block_given?
+            raise EventLogError, 'block missing for tail()'
+         end
+         
+         old_total = total_records()       
+         flags     = FORWARDS_READ | SEEK_READ
+         rec_num   = read_last_event.record_number
+         
+         while true          
+            new_total = total_records()    
+            if new_total != old_total
+               rec_num = oldest_record_number() if full?
+               read(flags, rec_num).each{ |log| yield log }
+               old_total = new_total
+               rec_num   = read_last_event.record_number + 1
+            end
+            sleep frequency
+         end
+      end
+      
+      # EventLog#read(flags=nil, offset=0)
+      # EventLog#read(flags=nil, offset=0){ |log| ... }
+      # 
+      # Iterates over each record in the event log, yielding a EventLogStruct
+      # for each record.  The offset value is only used when used in
+      # conjunction with the EventLog::SEEK_READ flag.  Otherwise, it is
+      # ignored.  If no flags are specified, then the default flags are:
+      #   
+      # EventLog::SEQUENTIAL_READ | EventLog::FORWARDS_READ
+      #   
+      # The EventLogStruct struct contains the following members:
+      #   
+      # record_number  # Fixnum
+      # time_generated # Time
+      # time_written   # Time
+      # event_id       # Fixnum
+      # event_type     # String
+      # category       # String
+      # source         # String
+      # computer       # String
+      # user           # String or nil
+      # description    # String or nil
+      #   
+      # If no block is given the method returns an array of EventLogStruct's.
+      # 
+      def read(flags = nil, offset = 0)
+         buf    = 0.chr * BUFFER_SIZE # 64k buffer 
+         size   = buf.size      
+         read   = [0].pack('L')
+         needed = [0].pack('L')
+         array  = []
+         
+         unless flags
+            flags = FORWARDS_READ | SEQUENTIAL_READ
+         end
+         
+         while ReadEventLog(@handle, flags, offset, buf, size, read, needed) ||
+            GetLastError() == ERROR_INSUFFICIENT_BUFFER
+            
+            if GetLastError() == ERROR_INSUFFICIENT_BUFFER
+               buf += 0.chr * needed.unpack('L').first
+               ReadEventLog(@handle, flags, offset, buf, size, read, needed)
+            end
+                       
+            dwread = read.unpack('L').first
+               
+            while dwread > 0
+               struct       = EventLogStruct.new
+               event_source = buf[56..-1].nstrip
+               computer     = buf[56 + event_source.length + 1..-1].nstrip
+               
+               user = get_user(buf)
+               desc = get_description(buf, event_source)
+      
+               struct.source         = event_source
+               struct.computer       = computer
+               struct.record_number  = buf[8,4].unpack('L').first
+               struct.time_generated = Time.at(buf[12,4].unpack('L').first)
+               struct.time_written   = Time.at(buf[16,4].unpack('L').first)
+               struct.event_id       = buf[20,4].unpack('L').first & 0x0000FFFF
+               struct.event_type     = get_event_type(buf[24,2].unpack('S').first)
+               struct.user           = user
+               struct.category       = buf[28,2].unpack('S').first
+               struct.description 	 = desc
+
+               if block_given?
+                  yield struct
+               else
+                  array.push(struct)
+               end
+               
+               if flags & EVENTLOG_BACKWARDS_READ > 0
+                  offset = buf[8,4].unpack('L').first - 1
+               else
+                  offset = buf[8,4].unpack('L').first + 1
+               end
+               
+               length = buf[0,4].unpack('L').first # Length
+
+               dwread -= length
+               buf = buf[length..-1]
+            end
+            
+            buf = 0.chr * BUFFER_SIZE
+            read = [0].pack('L')
+         end
+         
+         block_given? ? nil : array
+      end
+      
+      # This class method is nearly identical to the EventLog#read instance
+      # method, except that it takes a +source+ and +server+ as the first two
+      # arguments.
+      # 
+      def self.read(source='Application', server=nil, flags=nil, offset=0)
+         self.new(source, server){ |log|
+            if block_given?
+               log.read(flags, offset){ |els| yield els }
+            else
+               return log.read(flags, offset)
+            end
+         }
+      end
+     
+      # EventLog#report_event(key => value, ...)
+      #
+      # Writes an event to the event log.  The following are valid keys:
+      #  
+      # source         # Event log source name. Defaults to "Application"
+      # event_id       # Event ID (defined in event message file)
+      # category       # Event category (defined in category message file)
+      # data           # String that is written to the log
+      # event_type     # Type of event, e.g. EventLog::ERROR, etc.
+      #   
+      # The +event_type+ keyword is the only mandatory keyword.  The others are
+      # optional.  Although the +source+ defaults to "Application", I
+      # recommend that you create an application specific event source and use
+      # that instead.  See the 'EventLog.add_event_source' method for more
+      # details.
+      #  
+      # The +event_id+ and +category+ values are defined in the message
+      # file(s) that you created for your application.  See the tutorial.txt
+      # file for more details on how to create a message file.
+      #   
+      # An ArgumentError is raised if you attempt to use an invalid key.
+      # 
+      def report_event(args)
+         raise TypeError unless args.is_a?(Hash)
+         
+         valid_keys  = %w/source event_id category data event_type/
+         num_strings = 0
+
+         # Default values
+         hash = {
+            'source'   => @source,
+            'event_id' => 0,
+            'category' => 0,
+            'data'     => 0
+         }
+         
+         # Validate the keys, and convert symbols and case to lowercase strings.     
+         args.each{ |key, val|
+            key = key.to_s.downcase
+            unless valid_keys.include?(key)
+               raise ArgumentError, "invalid key '#{key}'"
+            end
+            hash[key] = val
+         }
+         
+         # The event_type must be specified
+         unless hash['event_type']
+            raise EventLogError, 'no event_type specified'
+         end
+         
+         handle = RegisterEventSource(@server, hash['source'])
+         
+         if handle == 0
+            error = 'RegisterEventSource() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         
+         if hash['data'].is_a?(String)
+            data = hash['data'] << 0.chr
+            data = [data].pack('p*')
+            num_strings = 1
+         else
+            data = 0
+            num_strings = 0
+         end
+         
+         bool = ReportEvent(
+            handle,
+            hash['event_type'],
+            hash['category'],
+            hash['event_id'],
+            0,
+            num_strings,
+            0,
+            data,
+            0
+         )
+         
+         unless bool
+            error = 'ReportEvent() failed: ' + get_last_error
+            raise EventLogError, error
+         end
+         
+         self
+      end
+      
+      alias :write :report_event
+      
+      private
+      
+      # A private method that reads the last event log record.
+      # 
+      def read_last_event(handle=@handle, source=@source, server=@server)
+         buf    = 0.chr * BUFFER_SIZE # 64k buffer
+         read   = [0].pack('L')
+         needed = [0].pack('L')
+    
+         flags = EVENTLOG_BACKWARDS_READ | EVENTLOG_SEQUENTIAL_READ
+         ReadEventLog(@handle, flags, 0, buf, buf.size, read, needed)
+      
+         event_source = buf[56..-1].nstrip
+         computer     = buf[56 + event_source.length + 1..-1].nstrip
+         event_type   = get_event_type(buf[24,2].unpack('S').first)
+         user         = get_user(buf)
+         desc         = get_description(buf, event_source)
+      
+         struct = EventLogStruct.new
+         struct.source         = event_source
+         struct.computer       = computer
+         struct.record_number  = buf[8,4].unpack('L').first
+         struct.time_generated = Time.at(buf[12,4].unpack('L').first)
+         struct.time_written   = Time.at(buf[16,4].unpack('L').first)
+         struct.event_id       = buf[20,4].unpack('L').first & 0x0000FFFF
+         struct.event_type     = event_type
+         struct.user           = user
+         struct.category       = buf[28,2].unpack('S').first
+         struct.description 	 = desc
+         
+         struct
+      end
+      
+      # Private method that gets the event description (text) based on data
+      # from the EVENTLOGRECORD buffer.
+      # 
+      def get_description(rec, event_source)    
+         str     = rec[ rec[36,4].unpack('L').first .. -1]         
+         num     = rec[26,2].unpack('S').first # NumStrings
+         hkey    = [0].pack('L')
+         key     = BASE_KEY + "#{@source}\\#{event_source}"
+         buf     = 0.chr * 1024
+         
+         if num == 0
+            va_list_ptr = 0.chr * 4
+         else
+	         va_list = str.split(0.chr)[0...num]
+	         va_list_ptr = va_list.map{ |x|
+	            [x + 0.chr].pack('P').unpack('L').first
+	         }.pack('L*')
+         end
+         	         	
+         if RegOpenKeyEx(HKEY_LOCAL_MACHINE, key, 0, KEY_READ, hkey) == 0
+            value = 'EventMessageFile'
+            file  = 0.chr * MAX_SIZE
+            hkey  = hkey.unpack('L').first
+            size  = [file.length].pack('L')
+            
+            if RegQueryValueEx(hkey, value, 0, 0, file, size) == 0
+               file = file.nstrip
+               exe  = 0.chr * MAX_SIZE
+               
+               ExpandEnvironmentStrings(file, exe, exe.size)
+               exe = exe.nstrip
+               
+               exe.split(';').each{ |file|
+                  hmodule  = LoadLibraryEx(file, 0, LOAD_LIBRARY_AS_DATAFILE)
+                  event_id = rec[20,4].unpack('L').first
+                  if hmodule != 0
+                     FormatMessage(
+                        FORMAT_MESSAGE_FROM_HMODULE |
+                        FORMAT_MESSAGE_FROM_SYSTEM |
+                        FORMAT_MESSAGE_ARGUMENT_ARRAY,
+                        hmodule,
+                        event_id,
+                        0,
+                        buf,
+                        buf.size,
+                        va_list_ptr 
+                     )
+                     FreeLibrary(hmodule)
+                  end
+               }
+            end
+            
+            RegCloseKey(hkey)
+         end
+         buf.strip
+      end
+      
+      # Private method that retrieves the user name based on data in the
+      # EVENTLOGRECORD buffer.
+      # 
+      def get_user(buf)      
+         return nil if buf[40,4].unpack('L').first <= 0 # UserSidLength
+
+         name        = 0.chr * MAX_SIZE
+         name_size   = [name.size].pack('L')
+         domain      = 0.chr * MAX_SIZE
+         domain_size = [domain.size].pack('L')
+         snu         = 0.chr * 4
+         
+         offset = buf[44,4].unpack('L').first # UserSidOffset
+      
+         val = LookupAccountSid(
+            @server,
+            [buf].pack('P').unpack('L').first + offset,
+            name,
+            name_size,
+            domain,
+            domain_size,
+            snu
+         )
+         
+         # Return nil if the lookup failed
+         return val ? name.nstrip : nil
+      end
+      
+      # Private method that converts a numeric event type into a human
+      # readable string.
+      # 
+      def get_event_type(event)
+         case event
+            when EVENTLOG_ERROR_TYPE
+               'error'
+            when EVENTLOG_WARNING_TYPE
+               'warning'
+            when EVENTLOG_INFORMATION_TYPE
+               'information'
+            when EVENTLOG_AUDIT_SUCCESS
+               'audit_success'
+            when EVENTLOG_AUDIT_FAILURE
+               'audit_failure'
+            else
+               nil
+         end
+      end
+   end
+end