win32-eventlog 0.5.3 → 0.6.0

data/MANIFEST

@@ -1,16 +1,19 @@
-* MANIFEST
-* CHANGES
-* README
-* Rakefile
-* win32-eventlog.gemspec
-* doc/tutorial.txt
-* examples/example_read.rb
-* examples/example_write.rb
-* examples/example_notify.rb
-* lib/win32/eventlog.rb
-* lib/win32/mc.rb
-* misc/install_msg.rb
-* misc/rubymsg.mc
-* test/foo.mc
-* test/test_eventlog.rb
-* test/test_mc.rb
+* MANIFEST
+* CHANGES
+* README
+* Rakefile
+* win32-eventlog.gemspec
+* doc/tutorial.txt
+* examples/example_read.rb
+* examples/example_write.rb
+* examples/example_notify.rb
+* lib/win32/eventlog.rb
+* lib/win32/mc.rb
+* lib/win32/windows/constants.rb
+* lib/win32/windows/functions.rb
+* lib/win32/windows/structs.rb
+* misc/install_msg.rb
+* misc/rubymsg.mc
+* test/foo.mc
+* test/test_eventlog.rb
+* test/test_mc.rb

data/README

@@ -1,68 +1,78 @@
-== 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
-  windows-pr 0.9.3 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
-  gem install win32-eventlog
-
-=== General Installation Notes
-  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 then run the
-  event_source:install Rake task. 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 test_mc.rb tests are skipped
-  If the tests from the test_mc.rb file are omitted then you either don't
-  have the mc, rc and/or link commands installed or they're not in your
-  system's %PATH%. If you have MSVC++, you should have them somewhere on your
-  system.
-
-== Known Issues
-  None known.
-
-  Please file any bug reports on the project page at
-  http://www.rubyforge.org/projects/win32utils.
-
-== License
-  Artistic 2.0
-
-== 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
+== 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 class (provided with this distro), assuming you have the
+  proper tools installed.
+
+== Prerequisites
+  * ffi
+  * Windows Vista 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
+  gem install win32-eventlog
+
+== Synopsis
+  require 'win32/eventlog'
+  require 'win32/mc' # If you want to create message files.
+
+  Win32::EventLog.read('Application') do |log|
+    p log
+  end
+
+=== General Installation Notes
+  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 then run the
+  event_source:install Rake task. 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 test_mc.rb tests are skipped
+  If the tests from the test_mc.rb file are omitted then you either don't
+  have the mc, rc and/or link commands installed or they're not in your
+  system's %PATH%. If you have MSVC++, you should have them somewhere on your
+  system.
+
+== Known Issues
+  JRuby users may need to increase their heap space.
+
+  Please file any bug reports on the project page at
+  http://github.com/djberg96/win32-eventlog or
+  http://www.rubyforge.org/projects/win32utils.
+
+== License
+  Artistic 2.0
+
+== 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/Rakefile

@@ -8,7 +8,12 @@ namespace :gem do
   desc 'Create the win32-eventlog gem'
   task :create => [:clean] do
     spec = eval(IO.read('win32-eventlog.gemspec'))
-    Gem::Builder.new(spec).build
+    if Gem::VERSION < "2.0"
+      Gem::Builder.new(spec).build
+    else
+      require 'rubygems/package'
+      Gem::Package.build(spec)
+    end
   end
 
   desc 'Install the win32-eventlog gem'

data/doc/tutorial.txt

@@ -1,137 +1,137 @@
-== 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.
-
-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 library, which is a simple wrapper
-for the above commands, and is included with this library.  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 specify 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 format specifier, 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   => '0x00000003L'.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
-
+== 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.
+
+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 library, which is a simple wrapper
+for the above commands, and is included with this library.  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 specify 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 format specifier, 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   => '0x00000003L'.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