win32-eventlog 0.4.3 → 0.4.4

data/CHANGES

@@ -1,3 +1,12 @@
+= 0.4.4 - 31-Jul-2007
+* The EventLogError class is now EventLog::Error.
+* The MCError class is now MC::Error.
+* Added a Rakefile with tasks for installation and testing.
+* Removed the install.rb file. Installation is now handled by the Rakefile.
+* Fixed some bad test cases in tc_eventlog.rb.
+* Added some more source comments.
+* Updates to the README and MANIFEST file.
+
 = 0.4.3 - 18-Dec-2006
 * Removed the FORMAT_MESSAGE_FROM_SYSTEM flag to the FormatMessage function
   in the get_description private method because it could sometimes return
@@ -143,4 +152,4 @@
 * Minor doc updates and cleanup.
 
 == 0.1.0 - 14-Oct-2003
-* Initial release
+* Initial release

data/MANIFEST

@@ -1,22 +1,17 @@
-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
+* MANIFEST
+* CHANGES
+* README
+* Rakefile
+* 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

@@ -1,60 +1,66 @@
-= What is it?
-An interface to the Windows Event Log.
+= Description
+   The win32-eventlog library provides an interface for reading from and
+   writing to the MS Windows Event Log.
+
+   In addition, you can create your own message event sources using the
+   win32-mc library (provided with this distro), assuming you have the
+   proper tools installed.
 
 = Prerequisites
-Ruby 1.8.2 or later.
-windows-pr 0.5.0 or later.
+   Ruby 1.8.2 or later.
+   windows-pr 0.5.0 or later.
+   
+   The 'mc', 'rc' and 'link' command line tools are required to create and
+   install message sources. You won't need these for simply reading from or
+   writing to an existing event log.
 
 = 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
+   rake test (optional)
+   rake install (non-gem) or rake install_gem (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.
+   This will install both the win32-eventlog and win32-mc libraries. 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.
+   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.
+   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.
+   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.
+   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.
+   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.
+   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
-The code currently only checks the EventMessage file, it does not check the
-CategoryMessage or ParameterMessage files.
+   The code currently only checks the EventMessage file, it does not check the
+   CategoryMessage or ParameterMessage files.
 
 = License
-Ruby's
+   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.
+   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
+   Daniel J. Berger
+   Park Heesob

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+
+desc "Install the win32-eventlog and win32-mc libraries (non-gem)"
+task :install do
+   dest = File.join(Config::CONFIG['sitelibdir'], 'win32')
+   Dir.mkdir(dest) unless File.exists? dest
+   cp 'lib/win32/eventlog.rb', dest, :verbose => true
+   cp 'lib/win32/mc.rb', dest, :verbose => true
+end
+
+desc "Install the win32-eventlog package as a gem"
+task :install_gem do
+   ruby 'win32-eventlog.gemspec'
+   file = Dir["*.gem"].first
+   sh "gem install #{file}"
+end
+
+Rake::TestTask.new do |t|
+   t.libs << 'lib'
+   t.warning = true
+   t.test_files = FileList['test/ts*']
+end

data/lib/win32/eventlog.rb

@@ -15,9 +15,17 @@ class String
    end
 end
 
+# The Win32 module serves as a namespace only.
 module Win32
-   class EventLogError < StandardError; end
+
+   # The EventLog class encapsulates an Event Log source and provides methods
+   # for interacting with that source.
    class EventLog
+   
+      # The EventLog::Error is raised in cases where interaction with the
+      # event log should happen to fail for any reason.
+      class Error < StandardError; end
+      
       include Windows::Error
       include Windows::EventLog
       include Windows::Security
@@ -29,7 +37,7 @@ module Win32
       extend Windows::Error
       extend Windows::Registry
       
-      VERSION = '0.4.3'
+      VERSION = '0.4.4'
       
       # Aliased read flags
       FORWARDS_READ   = EVENTLOG_FORWARDS_READ
@@ -45,12 +53,12 @@ module Win32
       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\\"
       
+      # The EventLogStruct encapsulates a single event log record.
       EventLogStruct = Struct.new('EventLogStruct', :record_number,
          :time_generated, :time_written, :event_id, :event_type, :category,
          :source, :computer, :user, :string_inserts, :description
@@ -101,7 +109,7 @@ module Win32
          
          if @handle == 0
             error = "#{function} failed: " + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          # Ensure the handle is closed at the end of a block
@@ -181,14 +189,14 @@ module Win32
          
          # The key_name must be specified
          unless hash['key_name']
-            raise EventLogError, 'no event_type specified'
+            raise Error, '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
+            raise Error, error
          end
          
          hkey = hkey.unpack('L').first
@@ -208,7 +216,7 @@ module Win32
             if rv != ERROR_SUCCESS
                error = 'RegSetValueEx() failed: ', get_last_error
                RegCloseKey(hkey)
-               raise EventLogError, error
+               raise Error, error
             end
          end
          
@@ -227,7 +235,7 @@ module Win32
             if rv != ERROR_SUCCESS
                error = 'RegSetValueEx() failed: ', get_last_error
                RegCloseKey(hkey)
-               raise EventLogError, error
+               raise Error, error
             end
          end
          
@@ -246,7 +254,7 @@ module Win32
             if rv != ERROR_SUCCESS
                error = 'RegSetValueEx() failed: ', get_last_error
                RegCloseKey(hkey)
-               raise EventLogError, error
+               raise Error, error
             end
          end
          
@@ -263,7 +271,7 @@ module Win32
          if rv != ERROR_SUCCESS
             error = 'RegSetValueEx() failed: ', get_last_error
             RegCloseKey(hkey)
-            raise EventLogError, error
+            raise Error, error
          end
          
          RegCloseKey(hkey)
@@ -271,13 +279,13 @@ module Win32
       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.
+      # a file that already exists or a Error 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
+            raise Error, error
          end
          self
       end
@@ -291,7 +299,7 @@ module Win32
           
          unless ClearEventLog(@handle, backup_file)
             error = 'ClearEventLog() failed: ' + get_last_error
-            raise EventLogError
+            raise Error
          end
          
          self
@@ -326,7 +334,7 @@ module Win32
          
          unless GetOldestEventLogRecord(@handle, rec)
             error = 'GetOldestEventLogRecord() failed: ' + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          rec.unpack('L').first
@@ -340,7 +348,7 @@ module Win32
          unless GetNumberOfEventLogRecords(@handle, total)
             error = 'GetNumberOfEventLogRecords() failed: '
             error += get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          total.unpack('L').first
@@ -350,11 +358,11 @@ module Win32
       # log. Unlike EventLog#tail, this method breaks out of the block after
       # the event.
       # 
-      # Raises an EventLogError if no block is provided.
+      # Raises an Error if no block is provided.
       # 
       def notify_change(&block)
          unless block_given?
-            raise EventLogError, 'block missing for notify_change()'
+            raise Error, 'block missing for notify_change()'
          end
          
          # Reopen the handle because the NotifyChangeEventLog() function will
@@ -363,14 +371,14 @@ module Win32
          
          if @handle == 0
             error = "OpenEventLog() failed: " + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          event = CreateEvent(0, 0, 0, 0)
          
          unless NotifyChangeEventLog(@handle, event)
             error = 'NotifyChangeEventLog() failed: ' + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          wait_result = WaitForSingleObject(event, INFINITE)
@@ -378,7 +386,7 @@ module Win32
          if wait_result == WAIT_FAILED
             error = 'WaitForSingleObject() failed: ' + get_last_error
             CloseHandle(event)
-            raise EventLogError, error
+            raise Error, error
          else
             last = read_last_event
             block.call(last)
@@ -393,7 +401,7 @@ module Win32
       # 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.
+      # Raises an Error 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,
@@ -402,7 +410,7 @@ module Win32
       #
       def tail(frequency = 5)
          unless block_given?
-            raise EventLogError, 'block missing for tail()'
+            raise Error, 'block missing for tail()'
          end
          
          old_total = total_records()       
@@ -578,14 +586,14 @@ module Win32
          
          # The event_type must be specified
          unless hash['event_type']
-            raise EventLogError, 'no event_type specified'
+            raise Error, 'no event_type specified'
          end
          
          handle = RegisterEventSource(@server, hash['source'])
          
          if handle == 0
             error = 'RegisterEventSource() failed: ' + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          if hash['data'].is_a?(String)
@@ -611,7 +619,7 @@ module Win32
          
          unless bool
             error = 'ReportEvent() failed: ' + get_last_error
-            raise EventLogError, error
+            raise Error, error
          end
          
          self

data/lib/win32/mc.rb

@@ -1,7 +1,8 @@
 module Win32
-   class MCError < StandardError; end
    class MC
-      VERSION = '0.1.2'
+      class Error < StandardError; end;
+      
+      VERSION = '0.1.3'
 		
       attr_accessor :mc_file, :res_file, :dll_file
 		
@@ -38,24 +39,24 @@ module Win32
       end
 		
 		# Creates the .res (resource) file from the .rc file generated by the
-		# MC#create_header method.  Raises an MCError if the .rc file is not
+		# MC#create_header method.  Raises an MC::Error if the .rc file is not
 		# found.
       # 
       def create_res_file
          rc_file = File.basename(@mc_file, '.mc') + '.rc'
          unless File.exists?(rc_file)
-            raise MCError, "No .rc file found: #{@rc_file}"
+            raise MC::Error, "No .rc file found: #{@rc_file}"
          end
          system("rc -r -fo #{@res_file} #{rc_file}")
       end
 		
 		# Creates the .dll file from the .res file generated by the
-		# MC#create_res_file method.  Raises an MCError if the .res file is not
+		# MC#create_res_file method.  Raises an MC::Error if the .res file is not
 		# found.
 		# 
       def create_dll_file
          unless File.exists?(@res_file)
-			   raise MCError, "No .res file found: #{@res_file}"
+			   raise MC::Error, "No .res file found: #{@res_file}"
          end
          system("link -dll -noentry -out:#{@dll_file} #{@res_file}")
       end
@@ -93,7 +94,7 @@ if $0 == __FILE__
 	
 	unless mc_file
 		msg = "Usage: ruby mc.rb 'filename.mc'"
-		raise MCError, msg
+		raise MC::Error, msg
 	end
 	
 	m = MC.new(mc_file)

data/test/tc_eventlog.rb

@@ -1,13 +1,10 @@
-###################################################
+##############################################################################
 # tc_eventlog.rb
 #
-# Test case for the win32-eventlog package.
-###################################################
-Dir.chdir('..') if File.basename(Dir.pwd) == 'test'
-$LOAD_PATH.unshift Dir.pwd
-$LOAD_PATH.unshift Dir.pwd + '/lib'
-Dir.chdir('test') rescue nil
-
+# Test case for the win32-eventlog package. You should run this test case
+# via the 'rake test' Rakefile task. This test will take a minute or two
+# to complete.
+#############################################################################
 require 'test/unit'
 require 'win32/eventlog'
 require 'socket'
@@ -26,7 +23,7 @@ class TC_EventLog < Test::Unit::TestCase
    end
  
    def test_version
-      assert_equal('0.4.2', EventLog::VERSION)
+      assert_equal('0.4.4', EventLog::VERSION)
    end
    
    # Use the alias to validate it as well.
@@ -39,7 +36,7 @@ class TC_EventLog < Test::Unit::TestCase
    end
    
    def test_constructor_expected_errors
-      assert_raises(EventLogError){ EventLog.new('System', @hostname, 'foo') }
+      assert_raises(EventLog::Error){ EventLog.new('System', @hostname, 'foo') }
       assert_raises(TypeError){ EventLog.open(1) }
       assert_raises(TypeError){ EventLog.open('System', 1) }
    end
@@ -109,20 +106,19 @@ class TC_EventLog < Test::Unit::TestCase
    
    def test_seek_read
       flags = EventLog::SEEK_READ | EventLog::FORWARDS_READ
-      assert_nothing_raised{ @last = @log.total_records }
+      assert_nothing_raised{ @last = @log.read[-10].record_number }
       assert_nothing_raised{
-         @records = EventLog.read(nil, nil, flags, @last - 10)
+         @records = EventLog.read(nil, nil, flags, @last)
       }
-      assert_equal(11, @records.length)
-      assert_equal(@last, @records.last.record_number)
+      assert_equal(10, @records.length)
    end
    
+   # This test could fail, since a record number + 10 may not actually exist.
    def test_seek_read_backwards
       flags = EventLog::SEEK_READ | EventLog::BACKWARDS_READ
-      assert_nothing_raised{ @records = EventLog.read(nil, nil, flags, 10) }
-      assert_equal(10, @records.length)
-      assert_equal(10, @records.first.record_number)
-      assert_equal(1, @records.last.record_number)
+      assert_nothing_raised{ @last = @log.oldest_record_number + 10 }
+      assert_nothing_raised{ @records = EventLog.read(nil, nil, flags, @last) }
+      assert_equal(11, @records.length)
    end
   
    def test_server
@@ -146,7 +142,7 @@ class TC_EventLog < Test::Unit::TestCase
       assert_respond_to(@log, :backup)
       assert_nothing_raised{ @log.backup(@bakfile) }
       assert(File.exists?(@bakfile))
-      assert_raises(EventLogError){ @log.backup(@bakfile) }
+      assert_raises(EventLog::Error){ @log.backup(@bakfile) }
    end
    
    # Since I don't want to actually clear anyone's event log, I can't really
@@ -181,7 +177,7 @@ class TC_EventLog < Test::Unit::TestCase
    # 
    def test_tail
       assert_respond_to(@log, :tail)
-      assert_raises(EventLogError){ @log.tail } # requires block
+      assert_raises(EventLog::Error){ @log.tail } # requires block
    end
    
    # We can't test that this method actually executes properly since it goes
@@ -189,7 +185,7 @@ class TC_EventLog < Test::Unit::TestCase
    # 
    def test_notify_change
       assert_respond_to(@log, :notify_change)
-      assert_raises(EventLogError){ @log.notify_change } # requires block
+      assert_raises(EventLog::Error){ @log.notify_change } # requires block
    end
    
    # I can't really do more in depth testing for this method since there
@@ -225,4 +221,4 @@ class TC_EventLog < Test::Unit::TestCase
       @records  = nil
       @last     = nil
    end
-end
+end

data/test/tc_mc.rb

@@ -3,23 +3,21 @@
 #
 # Test suite for the win32-mc package.  The tests need to run in a specific
 # order, hence the numerics added to the method names.
+#
+# This test case should be run via the 'rake test' Rakefile task.
 ############################################################################
-Dir.chdir('..') if File.basename(Dir.pwd) == 'test'
-$LOAD_PATH.unshift Dir.pwd
-$LOAD_PATH.unshift Dir.pwd + '/lib'
-Dir.chdir('test') rescue nil
-
 require 'test/unit'
 require 'win32/mc'
 include Win32
 
 class TC_Win32_MC < Test::Unit::TestCase
    def setup
+      Dir.chdir('test') unless File.basename(Dir.pwd) == 'test'
       @mc = MC.new('foo.mc')
    end
    
    def test_01_version
-      assert_equal('0.1.2', MC::VERSION)
+      assert_equal('0.1.3', MC::VERSION)
    end
 
    def test_02_create_header
@@ -46,4 +44,4 @@ class TC_Win32_MC < Test::Unit::TestCase
       @mc = nil
       File.delete('foo.dll') rescue nil
    end
-end
+end

data/test/ts_all.rb

@@ -1,7 +1,5 @@
-Dir.chdir('..') if File.basename(Dir.pwd) == 'test'
-$LOAD_PATH.unshift Dir.pwd
-$LOAD_PATH.unshift Dir.pwd + '/lib'
-Dir.chdir('test') rescue nil
+$LOAD_PATH.unshift(Dir.pwd)
+$LOAD_PATH.unshift(File.join(Dir.pwd, 'test'))
 
 require 'tc_eventlog'
-require 'tc_mc'
+require 'tc_mc'

data/win32-eventlog.gemspec

@@ -2,7 +2,7 @@ require "rubygems"
 
 spec = Gem::Specification.new do |gem|
    gem.name        = "win32-eventlog"
-   gem.version     = "0.4.3"
+   gem.version     = "0.4.4"
    gem.author      = "Daniel J. Berger"
    gem.email       = "djberg96@gmail.com"
    gem.homepage    = "http://www.rubyforge.org/projects/win32utils"
@@ -14,7 +14,7 @@ spec = Gem::Specification.new do |gem|
    gem.files       = Dir["lib/win32/*.rb"] + Dir["test/*"] + Dir["[A-Z]*"]
    gem.files.reject! { |fn| fn.include? "CVS" }
    gem.require_path = "lib"
-   gem.extra_rdoc_files = ["README", "CHANGES", "doc/tutorial.txt"]
+   gem.extra_rdoc_files = ["README", "CHANGES", "MANIFEST", "doc/tutorial.txt"]
    gem.add_dependency("windows-pr", ">= 0.5.0")
 end
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.2
 specification_version: 1
 name: win32-eventlog
 version: !ruby/object:Gem::Version 
-  version: 0.4.3
-date: 2006-12-18 00:00:00 -07:00
+  version: 0.4.4
+date: 2007-07-31 00:00:00 -06:00
 summary: Interface for the MS Windows Event Log.
 require_paths: 
 - lib
@@ -40,10 +40,10 @@ files:
 - CVS
 - doc
 - examples
-- install.rb
 - lib
 - MANIFEST
 - misc
+- Rakefile
 - README
 - test
 - win32-eventlog.gemspec
@@ -55,6 +55,7 @@ rdoc_options: []
 extra_rdoc_files: 
 - README
 - CHANGES
+- MANIFEST
 - doc/tutorial.txt
 executables: []
 

data/install.rb

@@ -1,13 +0,0 @@
-# For those who don't like gems...
-require 'rbconfig'
-require 'ftools'
-include Config
-
-sitelibdir = CONFIG['sitelibdir']
-installdir = sitelibdir + '/win32'
-file1 = 'lib\win32\eventlog.rb'
-file2 = 'lib\win32\mc.rb'
-
-Dir.mkdir(installdir) unless File.exists?(installdir)
-File.copy(file1, installdir, true)
-File.copy(file2, installdir, true)