win32-dirmonitor 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 50e164eadb4120514620c9163557cd77668cebe5
+  data.tar.gz: 022e4a74724f9bd61066091b311585124ac4a043
+SHA512:
+  metadata.gz: eac0b85c2ba9bdfb1f963c8f2238421346590e708507cccf1197b9f8f171115bde6f228e2653118dc16e017de726ab2364acc70e159380dff1a6582f47c63814
+  data.tar.gz: 8209e7917136b19b92ee66195a4184a142dcaf5aed18503c2f3bd88b591cc8e4d0e636db3fc35e441013f800ddc19dd2cc38e39f9c282d111acdba3c29c4ea74

data/CHANGES

@@ -0,0 +1,3 @@
+== 1.0.0 - 22-Jan-2014
+* Initial release.
+* This library replaces win32-changejournal.

data/MANIFEST

@@ -0,0 +1,8 @@
+* CHANGES
+* README
+* MANIFEST
+* Rakefile
+* win32-dirmonitor.gemspec
+* lib/win32/dirmonitor.rb
+* examples/example_dirmonitor.rb
+* test/test_win32_dirmonitor.rb

data/README

@@ -0,0 +1,52 @@
+== Description
+  A class for monitoring directories on MS Windows.
+
+== Installation
+  gem install win32-dirmonitor
+
+== Synopsis
+  require 'win32/dirmonitor'
+  include Win32
+
+  # Wait for a change in your home directory and report any changes.
+
+  monitor = Win32::DirMonitor.new(ENV['HOME'])
+
+  # Wait up to 5 minutes for a change.
+  monitor.wait(300){ |struct|
+    puts 'Something changed'
+    puts 'File: ' + struct.file
+    puts 'Action: ' + struct.action
+    struct.changes.each do |change|
+      puts "Change: " + change[0].to_s
+      puts "Old: " + change[1].to_s
+      puts "New: " + change[2].to_s
+    end
+  }
+	
+== Notes
+  This replaces the win32-changejournal library and supplants the
+  win32-changenotify library since it gives details about the changes
+  that occur.
+
+== Future Plans
+  Allow files in subdirectories to be monitored as well.
+
+== Known Bugs  
+  None that I know of. Please log any bug reports on the RubyForge
+  project page at https://github.com/djberg96/win32-dirmonitor.
+
+== License
+  Artistic 2.0
+    
+== Copyright
+  (C) 2014 Daniel J. Berger, All Rights Reserved
+    
+== Warranty
+  This library 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

@@ -0,0 +1,36 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+
+CLEAN.include("**/*.gem", "**/*.rbc", "**/*.rbx")
+
+namespace :gem do
+  desc "Create the win32-dirmonitor gem"
+  task :create => [:clean] do
+    spec = eval(IO.read('win32-dirmonitor.gemspec'))
+    if Gem::VERSION < "2.0"
+      Gem::Builder.new(spec).build
+    else
+      require 'rubygems/package'
+      Gem::Package.build(spec)
+    end
+  end
+
+  desc "Install the win32-clipboard library"
+  task :install => [:create] do
+    file = Dir["*.gem"].first
+    sh "gem install #{file}"
+  end
+end
+
+desc 'Run the example program'
+task :example do |t|
+  ruby '-Ilib examples/example_dirmonitor.rb'
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.warning = true
+  t.verbose = true
+end
+
+task :default => :test

data/examples/example_dirmonitor.rb

@@ -0,0 +1,23 @@
+########################################################################
+# example_changejournal.rb
+#
+# A test script for general futzing.  Modify as you see fit. You can
+# run this test script via the 'rake example' task.
+########################################################################
+require 'win32/dirmonitor'
+
+puts 'VERSION: ' + Win32::DirMonitor::VERSION
+
+monitor = Win32::DirMonitor.new(ENV['HOME'])
+
+# Wait up to 5 minutes for a change journals
+monitor.wait(300){ |struct|
+  puts 'Something changed'
+  puts 'File: ' + struct.file
+  puts 'Action: ' + struct.action
+  struct.changes.each do |change|
+    puts "Change: " + change[0].to_s
+    puts "Old: " + change[1].to_s
+    puts "New: " + change[2].to_s
+  end
+}

data/lib/win32/dirmonitor.rb

@@ -0,0 +1,146 @@
+require 'socket'
+require 'win32ole'
+require 'timeout'
+
+module Win32
+  class DirMonitor
+    class Error < StandardError; end
+
+    # The version of the win32-dirmonitor library
+    VERSION = '1.0.0'
+
+    # The struct yielded to the wait method
+    DirMonitorStruct = Struct.new(
+      'DirMonitorStruct',
+      :file,
+      :action,
+      :changes
+    )
+
+    # The path to be monitored.
+    attr_reader :path
+
+    # The host on which to monitor the path.
+    attr_reader :host
+
+    # Creates a new DirMonitor object which sets the path and hostname
+    # on which the filesystem will be monitored for changes. If no hostname
+    # is provided, then the current host is assumed.
+    #
+    def initialize(path, host = Socket.gethostname)
+      raise ArgumentError unless File.exists?(path)
+      raise TypeError unless path.is_a?(String)
+      raise TypeError unless host.is_a?(String)
+
+      @path = path.tr("/", "\\")
+      @host = host
+      @conn = "winmgmts:{impersonationlevel=impersonate}!//#{host}/root/cimv2"
+    end
+
+    # A event loop that will yield a DirMonitorStruct object whenever there
+    # is a change in a file on the path set in the constructor. The loop will
+    # timeout after the number of seconds provided, or indefinitely if no
+    # argument is provided.
+    #
+    # The DirMonitorStruct contains the following members:
+    #
+    # * file    # The full path of the file that was changed.
+    # * action  # Either create, delete or modify.
+    # * changes # If modified, includes an array of changes.
+    #
+    # If a modification occurs, the 'changes' struct member contains an
+    # array of arrays that describes the change. Each sub-array contains
+    # three members - the item that was modified, the previous value, and
+    # the current value.
+    #
+    # Example:
+    #
+    # mon = Win32::DirMonitor.new("C:/Users/foo")
+    #
+    # # Monitor filesystem for one minute.
+    # mon.wait(60){ |s| p s }
+    #
+    # # Sample struct returned after file was marked
+    # # hidden and read-only:
+    #
+    # #<struct Struct::DirMonitorStruct
+    #    file="c:\\Users\\foo\\test.txt",
+    #    action="modify",
+    #    changes=[
+    #      ["AccessMask", "2032127", "2032057"],
+    #      ["Hidden", "false", "true"],
+    #      ["Writeable", "true", "false"]
+    #    ]
+    #  >
+    #
+    def wait(seconds = nil)
+      raise TypeError unless seconds.is_a?(Numeric) if seconds
+
+      ole    = WIN32OLE.connect(@conn)
+      drive  = @path.split(':').first + ":"
+      folder = @path.split(':').last.gsub("\\", "\\\\\\\\")
+      folder << "\\\\" unless folder[-1] == "\\"
+
+      query = %Q{
+        select * from __instanceOperationEvent
+        within 2
+        where targetInstance isa 'CIM_DataFile'
+        and targetInstance.Drive='#{drive}'
+        and targetInstance.Path='#{folder}'
+      }
+
+      # Asynchronous call. This will let the user break out of it manually.
+      sink  = WIN32OLE.new('WbemScripting.SWbemSink')
+      event = WIN32OLE_EVENT.new(sink)
+
+      ole.execNotificationQueryAsync(sink, query)
+      sleep 0.5
+
+      event.on_event("OnObjectReady"){ |object, context|
+        target = object.TargetInstance
+        struct = DirMonitorStruct.new
+        struct[:file] = target.Name
+
+        case object.Path_.Class.to_s
+        when "__InstanceCreationEvent"
+          struct[:action] = 'create'
+        when "__InstanceDeletionEvent"
+          struct[:action] = 'delete'
+        when "__InstanceModificationEvent"
+          previous = object.PreviousInstance
+          struct[:action] = 'modify'
+          struct[:changes] = []
+
+          target.Properties_.each{ |prop|
+            if prop.Value != previous.send(prop.Name)
+              struct[:changes] << [
+                prop.Name,
+                previous.send(prop.Name).to_s,
+                prop.Value.to_s
+              ]
+            end
+          }
+        end
+
+        yield struct
+      }
+
+      # If an argument is provided, timeout after that many seconds.
+      if seconds
+        begin
+          Timeout.timeout(seconds){
+            loop do
+              WIN32OLE_EVENT.message_loop
+            end
+          }
+        rescue Timeout::Error
+          # Do nothing, return control to user
+        end
+      else
+        loop do
+          WIN32OLE_EVENT.message_loop
+        end
+      end
+    end
+  end
+end

data/test/test_win32_dirmonitor.rb

@@ -0,0 +1,103 @@
+#############################################################################
+# test_win32_dirmonitor.rb
+#
+# Test suite for the win32-dirmonitor library. You should run this
+# via the 'rake test' task.
+#############################################################################
+require 'test-unit'
+require 'win32/dirmonitor'
+include Win32
+
+class TC_Win32_DirMonitor < Test::Unit::TestCase
+  def self.startup
+    Dir.chdir(File.expand_path(File.dirname(__FILE__)))
+    @@file = 'win32_dirmonitor_test.txt'
+  end
+
+  def setup
+    # The thread is used to force an event to happen for the tests
+    @monitor = DirMonitor.new(Dir.pwd)
+    @thread  = Thread.new{
+       sleep 2
+       File.open(@@file, 'w'){ |fh| fh.puts 'Delete me!' }
+    }
+  end
+
+  test "version constant is set to expected value" do
+    assert_equal('1.0.0', DirMonitor::VERSION)
+  end
+
+  test "constructor requires a path argument" do
+    assert_raise(ArgumentError){ DirMonitor.new }
+  end
+
+  test "path and host arguments must be strings" do
+    assert_raise(TypeError){ DirMonitor.new(1) }
+    assert_raise(TypeError){ DirMonitor.new(Dir.pwd, 1) }
+  end
+
+  test "path argument must exist" do
+    assert_raise(ArgumentError){ DirMonitor.new("C:/Bogus/Bogus") }
+  end
+
+  test "wait method yields a frozen DirMonitorStruct" do
+    @thread.join
+    @monitor.wait(2){ |s|
+      assert_kind_of(Struct::DirMonitorStruct, s)
+      assert_equal(['action', 'file', 'changes'], s.members)
+      assert_kind_of(Array, s.changes)
+      assert_kind_of(Array, s.changes.first)
+      assert_true(s.frozen?)
+    }
+  end
+
+  test "wait method basic functionality" do
+    assert_respond_to(@monitor, :wait)
+  end
+
+  # We provide some very short timeouts here - shouldn't slow the tests down
+  test "wait method accepts an optional timeout value" do
+    assert_nothing_raised{ @monitor.wait(0.01){ |s| } }
+  end
+
+  test "wait method accepts a single integer argument only" do
+    assert_raise(ArgumentError){ @monitor.wait(1,1) }
+    assert_raise(TypeError){ @monitor.wait('a') }
+  end
+
+  test "a custom error class is defined" do
+    assert_kind_of(Object, Win32::DirMonitor::Error)
+  end
+
+  test "path attribute basic functionality" do
+    assert_respond_to(@monitor, :path)
+    assert_nothing_raised{ @monitor.path }
+    assert_kind_of(String, @monitor.path)
+  end
+
+  test "path method returns expected value" do
+    assert_equal(Dir.pwd, @monitor.path.tr("\\", "/"))
+  end
+
+  test "host attribute basic functionality" do
+    assert_respond_to(@monitor, :host)
+    assert_nothing_raised{ @monitor.host}
+    assert_kind_of(String, @monitor.host)
+  end
+
+  test "host method returns expected value" do
+    assert_equal(Socket.gethostname, @monitor.host)
+  end
+
+  def teardown
+    @thread.kill if @thread.alive?
+
+    @monitor = nil
+    @flags   = nil
+    @thread  = nil
+  end
+
+  def self.shutdown
+    File.delete(@@file) if File.exists?(@@file)
+  end
+end

data/win32-dirmonitor.gemspec

@@ -0,0 +1,30 @@
+require 'rubygems'
+
+Gem::Specification.new do |spec|
+  spec.name       = 'win32-dirmonitor'
+  spec.version    = '1.0.0'
+  spec.authors    = ['Daniel J. Berger', 'Park Heesob']
+  spec.license    = 'Artistic 2.0'
+  spec.email      = 'djberg96@gmail.com'
+  spec.homepage   = 'https://github.com/djberg96/win32-dirmonitor'
+  spec.summary    = 'A library for monitoring files on MS Windows'
+  spec.test_file  = 'test/test_win32_dirmonitor.rb'
+  spec.files      = Dir['**/*'].reject{ |f| f.include?('git') }
+
+  spec.rubyforge_project = 'win32utils'
+
+  spec.extra_rdoc_files = [
+    'README',
+    'CHANGES',
+    'MANIFEST',
+  ]
+
+  spec.add_development_dependency('test-unit')
+  spec.add_development_dependency('rake')
+
+  spec.description = <<-EOF
+    The win32-dirmonitor library provides a way to asynchronously monitor
+    changes to files in a given directory, and provides detailed information
+    about the changes that occurred.
+  EOF
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: win32-dirmonitor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Daniel J. Berger
+- Park Heesob
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      The win32-dirmonitor library provides a way to asynchronously monitor
+      changes to files in a given directory, and provides detailed information
+      about the changes that occurred.
+email: djberg96@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README
+- CHANGES
+- MANIFEST
+files:
+- CHANGES
+- examples/example_dirmonitor.rb
+- lib/win32/dirmonitor.rb
+- MANIFEST
+- Rakefile
+- README
+- test/test_win32_dirmonitor.rb
+- win32-dirmonitor.gemspec
+homepage: https://github.com/djberg96/win32-dirmonitor
+licenses:
+- Artistic 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: win32utils
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A library for monitoring files on MS Windows
+test_files:
+- test/test_win32_dirmonitor.rb