ruby-wmi 0.2.1 → 0.2.2

data/History.txt

@@ -1,3 +1,16 @@
+== 0.2.2 / 2008-01-11
+
+* 1 major enhancemenet
+  * supports privileges
+    <code>
+      events = WMI::Win32_NTLogEvent.find(
+        :all, :privileges => [WMI::Privilege::Security],
+        :conditions => {:logfile => 'Security', :eventcode => '517'} )
+    </code>
+* minor enhancements
+    * added error handling for invalid queries and class name typos
+    * better documentation
+
 == 0.2.1 / 2007-07-19
 
 * minor enhancements

data/Manifest.txt

@@ -4,11 +4,10 @@ README.txt
 Rakefile
 lib/ruby-wmi.rb
 lib/ruby-wmi/base.rb
-lib/ruby-wmi/cim.rb
+lib/ruby-wmi/constants.rb
 lib/ruby-wmi/core_ext.rb
 lib/ruby-wmi/core_ext/time_ext.rb
 lib/ruby-wmi/core_ext/win32ole_ext.rb
-lib/ruby-wmi/win32.rb
 samples/disk.rb
 samples/logoff.rb
 samples/memory.rb

data/README.txt

@@ -1,24 +1,40 @@
 ruby-wmi
     by Gordon Thiesfeld
     http://ruby-wmi.rubyforge.org/
+    gthiesfeld@gmail.com
 
 == DESCRIPTION:
-  
-    ruby-wmi is an ActiveRecord style interface for Microsoft's Windows Management Instrumentation provider.
+
+  ruby-wmi is an ActiveRecord style interface for Microsoft's Windows
+  Management Instrumentation provider.
+
+  Many of the methods in WMI::Base are borrowed directly, or with some
+  modification from ActiveRecord.
+    http://api.rubyonrails.org/classes/ActiveRecord/Base.html
+
+  The major tool in this library is the #find method.  For more
+  information, see WMI::Base.
+
+  There is also a WMI.sublasses method included for reflection.
 
 == SYNOPSIS:
 
-  # The following code sample kills all processes of a given name, except the oldest (in this case, Notepad)
+  # The following code sample kills all processes of a given name
+  # (in this case, Notepad), except the oldest.
 
     require 'ruby-wmi'
 
-    processes = Win32::Process.find(:all, :conditions => { :name => 'Notepad.exe' })
-    morituri = processes.sort_by{|p| p.CreationDate } #those who are about to die
-    morituri.shift 
+    procs = WMI::Win32_Process.find(:all,
+                                    :conditions => { :name => 'Notepad.exe' }
+                                   )
+    morituri = procs.sort_by{|p| p.CreationDate } #those who are about to die
+    morituri.shift
     morituri.each{|p| p.terminate }
 
 == REQUIREMENTS:
 
+    Windows 2000 or newer
+    Ruby 1.8
 
 == INSTALL:
 

data/Rakefile

@@ -4,15 +4,59 @@ require 'rubygems'
 require 'hoe'
 require './lib/ruby-wmi.rb'
 
-Hoe.new('ruby-wmi', Ruby_wmi::VERSION) do |p|
+class Hoe
+  attr_accessor :download_url
+  attr_accessor :title
+  attr_accessor :tagline
+
+  alias_method :old_define_tasks, :define_tasks
+  def define_tasks
+    old_define_tasks
+
+    desc "Generate webpage"
+    task :generate_web do
+      require 'uv'
+      require 'erubis'
+
+      @samples = Dir['samples/*.rb'].map do |file|
+        html = Uv.parse(  File.read(file), "xhtml", "ruby", false, "lazy")
+        [file, html]
+      end
+
+      input = File.read('web/templates/index.html.erb')
+      eruby = Erubis::Eruby.new(input)    # create Eruby object
+      File.open('web/public/index.html', 'w+'){|f| f.puts eruby.result(binding()) }
+    end
+  end
+end
+
+Hoe.new('ruby-wmi', RubyWMI::VERSION) do |p|
   p.rubyforge_name = 'ruby-wmi'
+  p.tagline = 'WMI queries, easier'
+  p.title = "#{p.name} -- #{p.tagline}"
   p.author = 'Gordon Thiesfeld'
   p.email = 'gthiesfeld@gmail.com'
   p.summary = "ruby-wmi is an ActiveRecord style interface for Microsoft\'s Windows Management Instrumentation provider."
-  # p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
-  # p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
   p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
   p.need_tar = false
+  p.spec_extras = {
+                  :requirements => ['allison', '>= 2.0.2'],
+                  :rdoc_options => ['--title' , p.title ,
+                       '--main' , 'README.txt' ,
+                       '--line-numbers', '--template',  File.join(Gem::GemPathSearcher.new.find('allison').full_gem_path,'lib','allison')]
+                  }
+  p.download_url = 'http://rubyforge.org/projects/ruby-wmi/'
+
 end
 
+
+
+# pscp -r -load rubyforge web/public/images vertiginal@rubyforge.org:/var/www/gforge-projects/ruby-wmi/images
+# needed tasks
+#   * rdoc fixed.
+#   * clobber_webpage
+#   * publish_website
+
 # vim: syntax=Ruby

data/lib/ruby-wmi.rb

@@ -1,11 +1,10 @@
-class Ruby_wmi
-  VERSION = '0.2.1'
+class RubyWMI
+  VERSION = '0.2.2'
 end
 
 $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require 'ruby-wmi/core_ext'
+require 'ruby-wmi/constants'
 require 'ruby-wmi/base'
-require 'ruby-wmi/cim'
-require 'ruby-wmi/win32'

data/lib/ruby-wmi/base.rb

@@ -2,43 +2,84 @@ require 'win32ole'
 
 module WMI
 
-    def subclasses(options ={})
-      Base.set_connection(options)
-      b = Base.connection
-      b.SubclassesOf.map { |subclass| class_name = subclass.Path_.Class }
-    end
-    
-    alias :subclasses_of :subclasses
+  # Generic WMI exception class.
+  class WMIError < StandardError
+  end
+
+  # Invalid Class exception class.
+  class InvalidClass < WMIError
+  end
+
+  # Invalid Query exception class.
+  class InvalidQuery < WMIError
+  end
+
+  # Returns an array conating all the WMI subclasses
+  # on a sytem.  Defaults to localhost
+  #
+  #   WMI.subclasses
+  #   => ["Win32_PrivilegesStatus", "Win32_TSNetworkAdapterSettingError", ...]
+  #
+  #  For a more human readable version of subclasses when using options:
+  #
+  #   WMI.subclasses_of(:host => some_computer)
+  #   => ["Win32_PrivilegesStatus", "Win32_TSNetworkAdapterSettingError", ...]
+  def subclasses(options ={})
+    Base.set_connection(options)
+    b = Base.send(:connection)
+    b.SubclassesOf.map { |subclass| class_name = subclass.Path_.Class }
+  end
+
+
+  alias :subclasses_of :subclasses
+
+  extend self
 
-    def const_missing(name)
-      self.const_set(name, Class.new(self::Base))
-    end
-    extend self
-    
   class Base
-      
+  # Many of the methods in Base are borrowed directly, or with some modification from ActiveRecord
+  #   http://api.rubyonrails.org/classes/ActiveRecord/Base.html
+
     class << self
-      def subclass_name
-        self.name.split('::').last
-      end
 
-      def connection
-        c = WIN32OLE.new("WbemScripting.SWbemLocator")
-        c.ConnectServer(@host,@klass,@credentials[:user],@credentials[:passwd])
-      end
-      
-      def set_connection(options)
-        @host = options[:host] || nil
-        @klass = options[:class] || 'root/cimv2'
-        @credentials = options[:credentials] || {:user => nil,:passwd => nil}
-      end
-      
+      # #find_by_wql currently only works when called through #find
+      # it may stay like that too.  I haven't decided.
       def find_by_wql(query)
         d = connection.ExecQuery(query)
-        d.count # needed to check for errors.  Weird, but it works.
+        begin
+          d.count # needed to check for errors.  Weird, but it works.
+        rescue => error
+          case error.to_s
+          when /Invalid class/i : raise InvalidClass
+          when /Invalid query/i : raise InvalidQuery
+          end
+        end
         d.to_a
       end
 
+      #  WMI::Win32ComputerSystem.find(:all)
+      #    returns an array of Win32ComputerSystem objects
+      #
+      #  WMI::Win32ComputerSystem.find(:first)
+      #    returns a Win32ComputerSystem object
+      #
+      #  options:
+      #
+      #    :conditions
+      #
+      #     Conditions can either be specified as a string, array, or hash representing the WHERE-part of an SQL statement.
+      #     The array form is to be used when the condition input is tainted and requires sanitization. The string form can
+      #     be used for statements that don't involve tainted data. The hash form works much like the array form, except
+      #     only equality and range is possible. Examples:
+      #
+      #       Win32ComputerSystem.find(:all, :conditions => {:drivetype => 3} )  # Hash
+      #       Win32ComputerSystem.find(:all, :conditions => [:drivetype, 3] )   # Array
+      #       Win32ComputerSystem.find(:all, :conditions => 'drivetype = 3' )   # String
+      #
+      #    :host       - computername, defaults to localhost
+      #    :class      - swebm class , defaults to 'root\\cimv2'
+      #    :privileges - see WMI::Privilege for a list of privileges
+      #    :user       - username (domain\\username)
+      #    :password   - password
       def find(arg=:all, options={})
         set_connection options
         case arg
@@ -46,7 +87,7 @@ module WMI
           when :first; find_first(options)
         end
       end
-      
+
       def find_first(options={})
         find_all(options).first
       end
@@ -54,7 +95,26 @@ module WMI
       def find_all(options={})
         find_by_wql(construct_finder_sql(options))
       end
-      
+
+      def set_connection(options)
+        @host = options[:host]
+        @klass = options[:class] || 'root\\cimv2'
+        @user,@password = options[:user], options[:password]
+        @privileges = options[:privileges]
+      end
+
+    private
+
+      def subclass_name
+        self.name.split('::').last
+      end
+
+      def connection
+        @c ||= WIN32OLE.new("WbemScripting.SWbemLocator")
+        @privileges.each { |priv| @c.security_.privileges.add(priv, true) } if @privileges
+        @c.ConnectServer(@host,@klass,@user,@password)
+      end
+
       def construct_finder_sql(options)
         #~ scope = scope(:find)
         sql  = "SELECT #{options[:select] || '*'} "
@@ -71,7 +131,7 @@ module WMI
 
         sql
       end
-      
+
       def add_conditions!(sql, conditions, scope = :auto)
         #~ scope = scope(:find) if :auto == scope
         segments = []
@@ -79,10 +139,10 @@ module WMI
         #~ segments << conditions unless conditions.nil?
         #~ segments << type_condition unless descends_from_active_record?
         segments.compact!
-        sql << "WHERE (#{segments.join(") AND (")}) " unless segments.empty?
+        sql << "WHERE #{segments.join(") AND (")} " unless segments.empty?
         sql.gsub!("\\","\\\\\\")
       end
-      
+
       # Accepts an array, hash, or string of sql conditions and sanitizes
       # them into a valid SQL fragment.
       #   ["name='%s' and group_id='%s'", "foo'bar", 4]  returns  "name='foo''bar' and group_id='4'"
@@ -108,7 +168,13 @@ module WMI
         end.join(' AND ')
 
         #~ replace_bind_variables(conditions, attrs.values)
-      end 
+      end
     end
   end
+
+  private
+
+  def const_missing(name)
+    self.const_set(name, Class.new(self::Base))
+  end
 end

data/lib/ruby-wmi/constants.rb

@@ -0,0 +1,94 @@
+module WMI
+  module Privilege
+    # Required to create a primary token.
+    CreateToken = 1
+
+    # Required to assign the primary token of a process.
+    PrimaryToken = 2
+
+    # Required to lock physical pages in memory.
+    LockMemory = 3
+
+    # Required to increase the quota assigned to a process.
+    IncreaseQuota = 4
+
+    # Required to create a machine account.
+    MachineAccount = 5
+
+    # Identifies its holder as part of the trusted computer base. Some trusted, protected
+    # subsystems are granted this privilege.
+    Tcb = 6
+
+    # Required to perform a number of security-related functions, such as controlling and
+    # viewing audit messages. This privilege identifies its holder as a security operator.
+    #
+    Security = 7
+
+    # Required to take ownership of an object without being granted discretionary access.
+    # This privilege allows the owner value to be set only to those values that the holder
+    # may legitimately assign as the owner of an object.
+    TakeOwnership = 8
+
+    # Required to load or unload a device driver.
+    LoadDriver = 9
+
+    # Required to gather profiling information for the entire system.
+    SystemProfile = 10
+
+    # Required to modify the system time.
+    Systemtime = 11
+
+    # Required to gather profiling information for a single process.
+    ProfileSingleProcess = 12
+
+    # Required to increase the base priority of a process.
+    IncreaseBasePriority = 13
+
+    # Required to create a paging file.
+    CreatePagefile = 14
+
+    # Required to create a permanent object.
+    CreatePermanent = 15
+
+    # Required to perform backup operations.
+    Backup = 16
+
+    # Required to perform restore operations. This privilege enables you to set any valid
+    # user or group security identifier (SID) as the owner of an object.
+    Restore = 17
+
+    # Required to shut down a local system.
+    Shutdown = 18
+
+    # Required to debug a process.
+    Debug = 19
+
+    # Required to generate audit-log entries.
+    Audit = 20
+
+    # Required to modify the nonvolatile RAM of systems that use this type of memory to store
+    # configuration information.
+    SystemEnvironment = 21
+
+    # Required to receive notifications of changes to files or directories. This privilege
+    # also causes the system to skip all traversal access checks. It is enabled by default
+    # for all users.
+    ChangeNotify = 22
+
+    # Required to shut down a system using a network request.
+    RemoteShutdown = 23
+
+    # Required to remove a computer from a docking station.
+    Undock = 24
+
+    # Required to synchronize directory service data.
+    SyncAgent = 25
+
+    # Required to enable computer and user accounts to be trusted for delegation.
+    EnableDelegation = 26
+
+    # Required to perform volume maintenance tasks. Windows 2000, Windows NT 4.0, and Windows
+    # Me/98/95:  This privilege is not available.
+    ManageVolume = 27
+  end
+end

data/samples/memory.rb

@@ -6,9 +6,6 @@ properties = ['Description','MaxCapacity','MemoryDevices','MemoryErrorCorrection
 mem = WMI::Win32_PhysicalMemoryArray.find(:all, :host => 'server1')
 mem.each{|i| puts properties.map{|p| "#{p}: #{i[p]}"}}
 
-mem2 = WMI::Win32_PhysicalMemoryArray.find(:all, {:host => 'server2', :credentials =>
-  {:user => 'domain\\gordon', :passwd => 'password'}
-  }
- )
+mem2 = WMI::Win32_PhysicalMemoryArray.find(:all, {:host => 'server2', :user => 'domain\\gordon', :passwd => 'password'} )
 mem2.each{|i| puts properties.map{|p| "#{p}: #{i[p]}"}}
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-wmi
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors: 
 - Gordon Thiesfeld
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-01-10 00:00:00 -06:00
+date: 2008-01-14 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,7 +21,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.4.0
     version: 
-description: The author was too lazy to write a description
+description: "ruby-wmi is an ActiveRecord style interface for Microsoft's Windows Management Instrumentation provider.  Many of the methods in WMI::Base are borrowed directly, or with some modification from ActiveRecord. http://api.rubyonrails.org/classes/ActiveRecord/Base.html  The major tool in this library is the #find method.  For more information, see WMI::Base.  There is also a WMI.sublasses method included for reflection."
 email: gthiesfeld@gmail.com
 executables: []
 
@@ -38,21 +38,25 @@ files:
 - Rakefile
 - lib/ruby-wmi.rb
 - lib/ruby-wmi/base.rb
-- lib/ruby-wmi/cim.rb
+- lib/ruby-wmi/constants.rb
 - lib/ruby-wmi/core_ext.rb
 - lib/ruby-wmi/core_ext/time_ext.rb
 - lib/ruby-wmi/core_ext/win32ole_ext.rb
-- lib/ruby-wmi/win32.rb
 - samples/disk.rb
 - samples/logoff.rb
 - samples/memory.rb
 - test/test_ruby-wmi.rb
 has_rdoc: true
-homepage: http://www.zenspider.com/ZSS/Products/ruby-wmi/
+homepage: "    by Gordon Thiesfeld"
 post_install_message: 
 rdoc_options: 
+- --title
+- ruby-wmi -- WMI queries, easier
 - --main
 - README.txt
+- --line-numbers
+- --template
+- c:/ruby/ruby186/lib/ruby/gems/1.8/gems/allison-2.0.2/lib/allison
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -67,8 +71,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version 
       version: "0"
   version: 
-requirements: []
-
+requirements: 
+- allison
+- ">= 2.0.2"
 rubyforge_project: ruby-wmi
 rubygems_version: 1.0.1
 signing_key: 

data/lib/ruby-wmi/cim.rb

@@ -1,12 +0,0 @@
-module CIM
-  extend WMI
-  
-  class Base < WMI::Base
-    class << self
-      def subclass_name
-        self.name.gsub('::', '_')
-      end
-    end
-  end
-  
-end

data/lib/ruby-wmi/win32.rb

@@ -1,11 +0,0 @@
-module Win32 
-  extend WMI
-  
-  class Base < WMI::Base
-    class << self
-      def subclass_name
-        self.name.gsub('::', '_')
-      end
-    end
-  end
-end