win32-changenotify 0.5.0

data/CHANGES

@@ -0,0 +1,56 @@
+== 0.5.0 - 9-Aug-2007
+* Now pure Ruby!
+* Now requires the win32-event library.
+* The constructor now accepts a block. If provided, it yields itself
+  and automatically closes itself when the block terminates.
+* Removed the ChangeNotify#reset method. It was never especially useful,
+  and now it's useless because of the way we wait for events (see below).
+* Added a Rakefile with tasks for installation and testing.
+* The code now uses completion ports internally, which greatly improves the
+  number of simultaneous events it can detect and report. See the 'Known
+  Issues' in the README for details on potential misses, however.
+* Some internal reorganization, with the C related code now moved into a
+  separate directory.
+* Doc, test, and example program updates.
+
+== 0.4.2 - 22-Nov-2006
+* Fixed bugs caused by changes to the Ruby internals with regards to question
+  marks and instance variables.  Thanks go to an anonymous user for the spot.
+* Minor documentation updates.
+
+== 0.4.1 - 2-Jan-2006
+* Code cleanup
+
+== 0.4.0 - 20-Apr-2005
+* ChangeNotify#wait now returns an array of ChangeNotifyStruct's, rather than
+  a single struct, because multiple notifications can occur for a single
+  event.
+* Example program and test suite updates.
+* Removed the changenotify.rd file.
+
+== 0.3.1 - 4-Feb-2005
+* Fixed a bug in ChangeNotify#wait where the timeout was not set to the
+  proper default if a timeout was not specified by the user.  Thanks go
+  to CT for the spot.
+* Made this document rdoc friendly.
+* Corrected the release date for 0.3.0.
+
+== 0.3.0 - 25-Jan-2005
+* The ChangeNotify#wait method now yields a ChangeNotifyStruct if a block is
+  provided.  This struct contains more detail on what changes occurred.
+* Added the ChangeNotify#path, ChangeNotify#recursive? and ChangeNotify#filter
+  methods.
+* The ChangeNotify.new method no longer accepts a block.  See the developer's
+  notes if you want the nitty gritty details.
+* Added more code to the extconf.rb file.  This was needed to set the
+  _WIN32_WINNT macro properly.
+* Moved the 'examples' directory to the toplevel.
+* Test suite and documentation updates.
+
+== 0.2.0 - 17-Jul-2004
+* Now uses the newer allocation framework.  This means that, as of this
+  releas, this package requires Ruby 1.8.0 or later.
+* Moved the test.rb file to doc/examples.
+
+== 0.1.0 - 7-May-2004
+* Initial release

data/MANIFEST

@@ -0,0 +1,12 @@
+* CHANGES
+* README
+* MANIFEST
+* Rakefile
+* win32-changenotify.gemspec
+* doc/changenotify.txt
+* examples/test.rb
+* ext/extconf.rb
+* ext/win32/changenotify.c
+* ext/win32/changenotify.h
+* lib/win32/changenotify.rb
+* test/tc_changenotify.rb

data/README

@@ -0,0 +1,100 @@
+= Description
+	A class for monitoring events related to files and directories.  This
+	package is deprecated in favor of win32-changejournal on NTFS filesystems.
+
+= Prerequisites
+   * Ruby 1.8.0 or later
+   * win32-ipc 0.4.0 or later
+
+= Installation
+   rake test (optional)
+   rake install (non-gem) OR rake install_gem (gem)
+
+= Synopsis
+   require 'win32/changenotify'
+   include Win32
+	
+   # Indefinitely wait for a change in 'C:\some\path' and any of its
+   # subdirectories.  Print the file and action affected.
+	
+   filter = ChangeNotify::FILE_NAME | ChangeNotify::DIR_NAME
+   path   = 'C:\some\path'
+   
+   cn = ChangeNotify.new(path, true, filter)
+
+   cn.wait{ |arr|
+      arr.each{ |info|
+         p info.file_name
+         p info.action
+      }
+   }
+   
+   cn.close
+   
+   # OR
+   
+   ChangeNotify.new(path, true, filter) do |events|
+   	events.each{ |event|
+   		p event.file_name
+   		p event.action
+   	}
+   end
+
+= Notes
+   The Win32::ChangeNotify class is a subclass of Win32::Ipc, and thus has
+   all of its methods available as well.
+	
+   This library is deprecated in favor of win32-changejournal on NTFS
+   filesystems.
+   
+   For additional documentation please see the 'changenotify.txt' file under
+   the 'doc' directory.
+   
+= Pure Ruby vs C Extension
+	The C code we used for this library prior to 0.5.0 is still available in
+	CVS for this project, but is not distributed with official releases. Note
+	that it does NOT contain the completion port approach we use in 0.5.0 and
+	later and is actually less reliable (in terms of how many simultaneous
+	events it can pickup) as a result.
+	
+= Known Issues
+   Despite the improvements yielded as a result of using completion ports,
+   it's still possible that events could be missed. To be more precise,
+   any events that occur in the fraction of a second between the call to
+   GetQueuedCompletionStatus() and ReadDirectoryChangesW() in the wait loop
+   will not get picked up. As a general rule, the faster your system is,
+   the less likely you are to encounter this scenario.
+   
+   We do not believe it is possible to resolve this issue without native
+   thread support. We are, however, open to suggestions. :)
+
+= Acknowledgements
+   This class was originally based on the Win32::ChangeNotify Perl module by
+   Christopher Madsen.
+	
+= Future Plans
+   Probably none. This library is deprecated in favor of win32-changejournal.
+   However, that library only works on NTFS filesystems, so this package will
+   be maintained as well.
+   
+   That being said, I'm always open to improvements, so feel free to submit
+   ideas and patches.
+	
+= Known Bugs  
+   None that I know of. Please log any other bug reports on the RubyForge
+   project page at http://www.rubyforge.net/projects/win32utils
+   
+= License
+   Ruby's
+    
+= Copyright
+   (C) 2003-2007 Daniel J. Berger, All Rights Reserved
+    
+= 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
+   Park Heesob
+   Daniel J. Berger

data/Rakefile

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

data/lib/win32/changenotify.rb

@@ -0,0 +1,263 @@
+require 'win32/event'
+require 'windows/nio'
+require 'windows/file'
+require 'windows/directory'
+require 'windows/unicode'
+require 'windows/msvcrt/buffer'
+
+module Win32
+   class ChangeNotify < Ipc
+      include Windows::NIO
+      include Windows::File
+      include Windows::Directory
+      include Windows::Unicode
+      include Windows::MSVCRT::Buffer
+      
+      # The version of this library
+      VERSION = '0.5.0'
+      
+      # Aliased constants
+ 
+      # Filter: Attribute changes
+      ATTRIBUTES = FILE_NOTIFY_CHANGE_ATTRIBUTES
+      
+      # Filter: Directory name changes
+      DIR_NAME = FILE_NOTIFY_CHANGE_DIR_NAME
+      
+      # Filter: File name changes   
+      FILE_NAME = FILE_NOTIFY_CHANGE_FILE_NAME
+      
+      # Filter: Write changes  
+      LAST_WRITE = FILE_NOTIFY_CHANGE_LAST_WRITE
+      
+      # Filter: File security changes 
+      SECURITY = FILE_NOTIFY_CHANGE_SECURITY
+      
+      # Filter: File size changes
+      SIZE = FILE_NOTIFY_CHANGE_SIZE
+      
+      # Private constants
+     
+      # File was added
+      FILE_ACTION_ADDED = 0x00000001
+      
+      # File was deleted 
+      FILE_ACTION_REMOVED = 0x00000002
+      
+      # File was modified  
+      FILE_ACTION_MODIFIED = 0x00000003
+        
+      # File was renamed, old (original) name  
+      FILE_ACTION_RENAMED_OLD_NAME = 0x00000004
+      
+      # File was renamed, new (current) name  
+      FILE_ACTION_RENAMED_NEW_NAME = 0x00000005
+      
+      # Yielded by the ChangeNotify#wait method
+      ChangeNotifyStruct = Struct.new('ChangeNotifyStruct', :action, :file_name)
+      
+      # The path that was provided to the constructor
+      attr_reader :path
+      
+      # The value of the filter (OR'd constants) passed to the constructor
+      attr_reader :filter
+      
+      # Returns a new ChangeNotify object and places a monitor on +path+.
+      # The +path+ argument may be a file or a directory. 
+      # 
+      # If +recursive is true and +path+ is a directory, then the monitor
+      # applies to all subdirectories of +path+.
+      # 
+      # The +filter+ tells the monitor what to watch for, such as file
+      # changes, attribute changes, etc.
+      # 
+      # If the +event+ option is specified, it must be a Win32::Event object.
+      # It is then set as the event that will be set to the signaled state
+      # when a notification has been completed.
+      # 
+      # Yields itself if a block is provided, and automatically closes itself
+      # when the block terminates.
+      #
+      def initialize(path, recursive, filter, event=nil)
+         @path      = path
+         @recursive = recursive
+         @filter    = filter
+         @overlap   = 0.chr * 20 # OVERLAPPED struct
+
+         # Because Win32API doesn't do type checking, we do it expicitly here.
+         raise TypeError unless path.is_a?(String)
+         raise TypeError unless [true, false].include?(recursive)
+         raise TypeError unless filter.is_a?(Fixnum)
+
+         if event
+            raise TypeError unless event.respond_to?(:handle)
+            @handle = event.handle
+         else
+            event = Win32::Event.new
+            @handle = event.handle
+         end
+         
+         @event = event
+         
+         @overlap[16,4] = [@handle].pack('L') # hEvent member
+         
+         super(@handle)
+         
+         if block_given?
+            begin
+               yield self
+            ensure
+               close
+            end
+         end        
+      end
+      
+      # Returns whether or not the ChangeNotify object is monitoring
+      # subdirectories of the path being monitored.
+      #  
+      def recursive?
+         @recursive
+      end
+      
+      alias ipc_wait wait
+
+      # Waits up to 'seconds' for a notification to occur, or infinitely
+      # if no value is specified.
+      # 
+      # Yields an array of ChangeNotifyStruct's that contains two
+      # members: file_name and action.
+      #
+      def wait(seconds = INFINITE)
+         seconds *= 1000 unless seconds == INFINITE
+        
+         fni    = 0.chr * 65536 # FILE_NOTIFY_INFORMATION struct buffer   
+         rbytes = [0].pack('L')
+         qbytes = [0].pack('L')
+
+         subtree    = @recursive ? 1 : 0
+         dir_handle = get_dir_handle(@path)        
+         comp_key   = [12345].pack('L')
+               
+         comp_port = CreateIoCompletionPort(dir_handle, 0, comp_key, 0)
+         
+         if comp_port == 0
+            raise Error, get_last_error
+         end
+
+         bool = ReadDirectoryChangesW(
+            dir_handle,
+            fni,
+            fni.size,
+            subtree,
+            @filter,
+            rbytes,
+            @overlap,
+            0
+         )
+         
+         unless bool
+            raise Error, get_last_error
+         end
+         
+         while true
+            bool = GetQueuedCompletionStatus(
+               comp_port,
+               qbytes,
+               comp_key,
+               @overlap,
+               seconds
+            )
+            
+            unless bool
+               raise Error, get_last_error
+            end
+            
+            @signaled = true
+            @event.signaled = true
+           
+            break if comp_key.unpack('L').first == 0
+                     
+            yield get_file_action(fni) if block_given?
+                       
+            bool = ReadDirectoryChangesW(
+               dir_handle,
+               fni,
+               fni.size,
+               subtree,
+               @filter,
+               rbytes,
+               @overlap,
+               0
+            )
+            
+            unless bool
+               raise Error, get_last_error
+            end
+         end
+         
+         CloseHandle(dir_handle)
+      end
+      
+      private
+      
+      def get_file_action(fni2)
+         fni = fni2.dup
+         array  = []       
+        
+         while true               
+            int_action = fni[4,4].unpack('L')[0]
+           
+            str_action = 'unknown'
+        
+            case int_action
+               when FILE_ACTION_ADDED
+                  str_action = 'added'
+               when FILE_ACTION_REMOVED
+                  str_action = 'removed'
+               when FILE_ACTION_MODIFIED
+                  str_action = 'modified'
+               when FILE_ACTION_RENAMED_OLD_NAME
+                  str_action = 'renamed old name'
+               when FILE_ACTION_RENAMED_NEW_NAME
+                  str_action = 'renamed new name'
+            end
+           
+            len  = fni[8,4].unpack('L').first # FileNameLength struct member
+            file = fni[12,len] + "\0\0"       # FileName struct member + null
+            buf  = 0.chr * 260
+           
+            WideCharToMultiByte(CP_ACP, 0, file, -1, buf, 260, 0, 0)
+           
+            file = File.join(@path, buf.unpack('A*')[0])
+        
+            struct = ChangeNotifyStruct.new(str_action, file)
+            array.push(struct)
+            break if fni[0,4].unpack('L')[0] == 0
+            fni = fni[fni[0,4].unpack('L').first .. -1] # Next offset
+            break if fni.nil?
+         end
+        
+         array
+      end
+      
+      # Returns a HANDLE to the directory +path+ created via CreateFile().
+      # 
+      def get_dir_handle(path)
+         handle = CreateFile(
+            path,
+            FILE_LIST_DIRECTORY,
+            FILE_SHARE_READ|FILE_SHARE_WRITE|FILE_SHARE_DELETE,
+            0,
+            OPEN_EXISTING,
+            FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OVERLAPPED,
+            0
+         )
+         
+         if handle == INVALID_HANDLE_VALUE
+            raise Error, get_last_error
+         end
+         
+         handle
+      end
+   end
+end

data/test/tc_changenotify.rb

@@ -0,0 +1,70 @@
+#############################################################################
+# tc_changenotify.rb
+#
+# Test suite for the win32-changenotify package. You should run this
+# test via the 'rake test' task.
+#############################################################################
+require 'test/unit'
+require 'win32/changenotify'
+include Win32
+
+class TC_ChangeNotify < Test::Unit::TestCase
+   def setup
+      @filter = ChangeNotify::FILE_NAME | ChangeNotify::DIR_NAME
+      @cn = ChangeNotify.new("c:\\", false, @filter)
+   end
+	
+   def test_version
+      assert_equal('0.5.0', ChangeNotify::VERSION)
+   end
+	
+   def test_path
+      assert_respond_to(@cn, :path)
+      assert_equal("c:\\", @cn.path)
+   end
+   
+   def test_recursive
+      assert_respond_to(@cn, :recursive?)
+      assert_equal(false, @cn.recursive?)
+   end
+   
+   def test_filter
+      assert_respond_to(@cn, :filter)
+      assert_equal(@filter, @cn.filter)
+   end
+
+   # The errors here are expected because of the timeout.
+   def test_wait
+      assert_respond_to(@cn, :wait)
+      assert_raises(ChangeNotify::Error){ @cn.wait(0.001) }
+      assert_raises(ChangeNotify::Error){ @cn.wait(0.001){} }
+   end
+	
+   def test_wait_any
+      assert_respond_to(@cn, :wait_any)
+   end
+	
+   def test_wait_all
+      assert_respond_to(@cn, :wait_all)
+   end
+   
+   def test_expected_errors
+      assert_raises(TypeError){
+         ChangeNotify.new(1, true, @filter)
+      }
+      assert_raises(TypeError){
+         ChangeNotify.new("C:\\", 'foo', @filter)
+      }
+      assert_raises(TypeError){
+         ChangeNotify.new("C:\\", false, "foo")
+      }
+      assert_raises(TypeError){
+         ChangeNotify.new(1, true, @filter, 'bogus')
+      }
+   end
+	
+   def teardown
+      @cn = nil
+      @filter = nil
+   end
+end

data/win32-changenotify.gemspec

@@ -0,0 +1,24 @@
+require 'rubygems'
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = 'win32-changenotify'
+   gem.version     = '0.5.0'
+   gem.author      = 'Daniel J. Berger'
+   gem.email       = 'djberg96@gmail.com'
+   gem.homepage    = 'http://www.rubyforge.org/projects/win32utils'
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = 'A way to monitor files and directories on MS Windows'
+   gem.description = 'A way to monitor files and directories on MS Windows'
+   gem.test_file   = 'test/tc_changenotify.rb'
+   gem.has_rdoc    = true
+   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 = ['MANIFEST', 'README', 'CHANGES']
+   gem.add_dependency('windows-pr', '>= 0.7.0')
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: win32-changenotify
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+date: 2007-08-09 00:00:00 -06:00
+summary: A way to monitor files and directories on MS Windows
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: A way to monitor files and directories on MS Windows
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/win32/changenotify.rb
+- test/CVS
+- test/tc_changenotify.rb
+- CHANGES
+- CVS
+- doc
+- examples
+- ext
+- lib
+- MANIFEST
+- Rakefile
+- README
+- test
+- win32-changenotify.gemspec
+test_files: 
+- test/tc_changenotify.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- MANIFEST
+- README
+- CHANGES
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: windows-pr
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.7.0
+    version: