diff options
-rw-r--r-- | lib/wmi-lite/version.rb | 2 | ||||
-rw-r--r-- | lib/wmi-lite/wmi.rb | 62 | ||||
-rw-r--r-- | lib/wmi-lite/wmi_exception.rb | 77 | ||||
-rw-r--r-- | lib/wmi-lite/wmi_instance.rb | 2 | ||||
-rw-r--r-- | spec/functional/wmi_spec.rb | 161 | ||||
-rw-r--r-- | spec/spec_helper.rb | 11 | ||||
-rw-r--r-- | spec/unit/wmi_spec.rb | 230 |
7 files changed, 501 insertions, 44 deletions
diff --git a/lib/wmi-lite/version.rb b/lib/wmi-lite/version.rb index 3de9582..f1f7382 100644 --- a/lib/wmi-lite/version.rb +++ b/lib/wmi-lite/version.rb @@ -1,3 +1,3 @@ module WmiLite - VERSION = '0.1.0.rc.0' + VERSION = '1.0.0.rc.0' end diff --git a/lib/wmi-lite/wmi.rb b/lib/wmi-lite/wmi.rb index 61fd0c3..6c39479 100644 --- a/lib/wmi-lite/wmi.rb +++ b/lib/wmi-lite/wmi.rb @@ -18,31 +18,25 @@ require 'win32ole' if RUBY_PLATFORM =~ /mswin|mingw32|windows/ require 'wmi-lite/wmi_instance' +require 'wmi-lite/wmi_exception' module WmiLite class Wmi def initialize(namespace = nil) - @connection = new_connection(namespace.nil? ? 'root/cimv2' : namespace) + @namespace = namespace.nil? ? 'root/cimv2' : namespace + @connection = nil end def query(wql_query) - results = start_query(wql_query) - - result_set = [] - - results.each do | result | - result_set.push(wmi_result_to_snapshot(result)) - end - - result_set + query_with_context(wql_query) end def instances_of(wmi_class) - query("select * from #{wmi_class}") + query_with_context("select * from #{wmi_class}", wmi_class) end def first_of(wmi_class) - query_result = start_query("select * from #{wmi_class}") + query_result = start_query("select * from #{wmi_class}", wmi_class) first_result = nil query_result.each do | record | first_result = record @@ -53,13 +47,47 @@ module WmiLite private - def start_query(wql_query) - @connection.ExecQuery(wql_query) + def query_with_context(wql_query, diagnostic_class_name = nil) + results = start_query(wql_query, diagnostic_class_name) + + result_set = [] + + results.each do | result | + result_set.push(wmi_result_to_snapshot(result)) + end + + result_set end - def new_connection(namespace) - locator = WIN32OLE.new("WbemScripting.SWbemLocator") - locator.ConnectServer('.', namespace) + def start_query(wql_query, diagnostic_class_name = nil) + result = nil + connect_to_namespace + begin + result = @connection.ExecQuery(wql_query) + raise_if_failed(result) + rescue WIN32OLERuntimeError => native_exception + raise WmiException.new(native_exception, :ExecQuery, @namespace, wql_query, diagnostic_class_name) + end + result + end + + def raise_if_failed(result) + # Attempting to access the count property of the underlying + # COM (OLE) object will trigger an exception if the query + # was unsuccessful. + result.count + end + + def connect_to_namespace + if @connection.nil? + namespace = @namespace.nil? ? 'root/cimv2' : @namespace + locator = WIN32OLE.new("WbemScripting.SWbemLocator") + begin + @connection = locator.ConnectServer('.', namespace) + rescue WIN32OLERuntimeError => native_exception + raise WmiException.new(native_exception, :ConnectServer, @namespace) + end + end end def wmi_result_to_snapshot(wmi_object) diff --git a/lib/wmi-lite/wmi_exception.rb b/lib/wmi-lite/wmi_exception.rb new file mode 100644 index 0000000..9b23247 --- /dev/null +++ b/lib/wmi-lite/wmi_exception.rb @@ -0,0 +1,77 @@ +# +# Author:: Adam Edwards (<adamed@getchef.com>) +# Copyright:: Copyright 2014 Chef Software, Inc. +# License:: Apache License, Version 2.0 +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +module WmiLite + class WmiException < Exception + def initialize(exception, wmi_method_context, namespace, query = nil, class_name = nil) + error_message = exception.message + error_code = translate_error_code(error_message) + + case wmi_method_context + when :ConnectServer + error_message = translate_wmi_connect_error_message(error_message, error_code, namespace) + when :ExecQuery + error_message = translate_query_error_message(error_message, error_code, namespace, query, class_name) + end + + super(error_message) + end + + private + + def translate_error_code(error_message) + error_code = nil + + # Parse the error to get the error status code + error_code_match = error_message.match(/[^\:]+\:\s*([0-9A-Fa-f]{1,8}).*/) + error_code = error_code_match.captures.first if error_code_match + error_code ? error_code : '' + end + + def translate_wmi_connect_error_message(native_message, error_code, namespace) + error_message = "An error occurred connecting to the WMI service for namespace \'#{namespace}\'. The namespace may not be valid, access may not be allowed to the WMI service, or the WMI service may not be available.\n#{native_message}" + + if error_code =~ /8004100E/i + error_message = "The specified namespace name \'#{namespace}\' is not a valid namespace name or does not exist.\n#{native_message}" + end + + error_message + end + + def translate_query_error_message(native_message, error_code, namespace, query, class_name) + error_message = "An error occurred when querying namespace \'#{namespace}\' with query \'#{query}\'.\n#{native_message}" + + error_code = translate_error_code(error_message) + + # Use the status code to generate a more friendly message + case error_code + when /80041010/i + if class_name + error_message = "The specified class \'#{class_name}\' is not valid in the namespace \'#{namespace}\'.\n#{native_message}." + else + error_message = "The specified query \'#{query}\' referenced a class that is not valid in the namespace \'#{namespace}\'\n#{native_message}." + end + when /80041017/i + error_message = "The specified query \'#{query}\' in namespace \'#{namespace}\' is not a syntactically valid query.\n#{native_message}" + end + + error_message + end + end +end + diff --git a/lib/wmi-lite/wmi_instance.rb b/lib/wmi-lite/wmi_instance.rb index a6f7256..ff0e9c6 100644 --- a/lib/wmi-lite/wmi_instance.rb +++ b/lib/wmi-lite/wmi_instance.rb @@ -27,7 +27,7 @@ module WmiLite end def [](key) - @property_map[key] + @property_map[key.downcase] end private diff --git a/spec/functional/wmi_spec.rb b/spec/functional/wmi_spec.rb new file mode 100644 index 0000000..0be3778 --- /dev/null +++ b/spec/functional/wmi_spec.rb @@ -0,0 +1,161 @@ +# +# Author:: Adam Edwards (<adamed@getchef.com>) +# +# Copyright:: 2014, Chef Software, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +require 'spec_helper' + +describe WmiLite::Wmi, :windows_only do + let(:wmi) { WmiLite::Wmi.new(namespace) } + + def validate_wmi_results(results, class_name) + result_collection = cardinality_transform.call(results) + result_collection.each do | result | + # make sure the class name of the instance is what we asked for + expect(result['creationclassname'].downcase).to eql(class_name.downcase) + end + end + + shared_examples_for 'a valid WMI query result' do + it 'should successfully return multiple results' do + query_parameter = wmi_query.nil? ? wmi_class : wmi_query + results = wmi.send(query_method, query_parameter) + validate_wmi_results(results, wmi_class) + end + + describe 'when the namespace is invalid' do + it_behaves_like 'an invalid namespace' + end + end + + shared_examples_for 'an invalid query' do + it 'should raise an exception' do + expect { wmi.send(query_method, wmi_query) }.to raise_error(WmiLite::WmiException) + end + end + + shared_examples_for 'an invalid namespace' do + it 'should raise an exception if an invalid namespace is specified' do + invalid_wmi = WmiLite::Wmi.new('root/notvalid') + expect { invalid_wmi.send(query_method, wmi_query) }.to raise_error(WmiLite::WmiException) + end + end + + shared_examples_for 'a valid WMI query' do + let(:wmi_class) { 'Win32_LogicalDisk' } + it_behaves_like 'a valid WMI query result' + + let(:wmi_class) { 'Win32_ComputerSystem' } + it_behaves_like 'a valid WMI query result' + + let(:wmi_class) { 'Win32_Process' } + it_behaves_like 'a valid WMI query result' + + context 'that return 0 results' do + let(:wmi_class) { 'Win32_TapeDrive' } + it_behaves_like 'a valid WMI query result' + end + end + + context 'when making valid queries' do + let(:namespace) { nil } + let(:wmi_query) { nil } + let(:cardinality_transform) { lambda{|x| x} } + context 'using first_of' do + let(:cardinality_transform) { lambda{|x| x.nil? ? [] : [x] } } + let(:query_method) { :first_of } + it_behaves_like 'a valid WMI query' + end + + context 'using instances_of' do + let(:query_method) { :instances_of } + it_behaves_like 'a valid WMI query' + end + + context 'using query' do + let(:wmi_query) { "select * from #{wmi_class}" } + let(:query_method) { :query } + it_behaves_like 'a valid WMI query' + end + end + + context 'when making invalid queries' do + let(:namespace) { nil } + + let(:wmi_query) { 'invalidclass' } + let(:query_method) { :first_of } + it_behaves_like 'an invalid query' + + let(:query_method) { :instances_of } + it_behaves_like 'an invalid query' + + let(:query_method) { :query } + let(:wmi_query) { 'nosql_4_life' } + it_behaves_like 'an invalid query' + end + + let(:namespace) { nil } + describe 'when querying Win32_Environment' do + it 'should have the same environment variables as the Ruby ENV environment hash' do + results = wmi.instances_of('Win32_Environment') + + variables = {} + + # Skip some environment variables because we can't compare them against what's in ENV. + # Path, pathext, psmodulepath are special, they ares "merged" between the user and system value. + # PROCESSOR_ARCHITECTURE is actually the real processor arch of the system, so #{ENV['processor_architecture']} will + # report X86, while WMI will (correctly) report X64. + # And username is oddly the username of the WMI service, i.e. 'SYSTEM'. + ignore = {'path' => true, 'pathext' => true, 'processor_architecture' => true, 'psmodulepath' => true, 'username' => true} + results.each do | result | + if ! variables.has_key?(result['name']) || result['username'] != '<SYSTEM>' + variables[result['name']] = result['variablevalue'] + end + end + + verified_count = 0 + variables.each_pair do | name, value | + if ignore[name.downcase] != true + + # Turn %SYSTEMROOT% into c:\windows + # so we can compare with what's in ENV + evaluated_value = `echo #{value}`.strip + + expect(evaluated_value).to eql(`echo #{ENV[name]}`.strip) + verified_count += 1 + end + end + + # There are at least 3 variables we could verify in a default + # Windows configuration, make sure we saw some + expect(verified_count).to be >= 3 + end + end + + let(:namespace) { nil } + it 'should ignore case when retrieving WMI properties' do + result = wmi.first_of('Win32_ComputerSystem') + caption_mixed = result['Caption'] + caption_lower = result['caption'] + + expect(caption_mixed.nil?).to eql(false) + expect(caption_lower.nil?).to eql(false) + + expect(caption_mixed.length).to be > 0 + expect(caption_lower.length).to be > 0 + expect(caption_mixed).to eql(caption_lower) + end +end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index b773d8a..ee9e966 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -1,5 +1,12 @@ # $:.unshift File.expand_path('../../lib', __FILE__) require 'rspec' -require 'wmi-lite/wmi' -require 'wmi-lite/wmi_instance' +require 'wmi-lite' + +RSpec.configure do |config| + config.include(RSpec::Matchers) + config.treat_symbols_as_metadata_keys_with_true_values = true + config.filter_run :focus => true + config.filter_run_excluding :windows_only => true if ! (RUBY_PLATFORM =~ /mswin|mingw32|windows/) + config.run_all_when_everything_filtered = true +end diff --git a/spec/unit/wmi_spec.rb b/spec/unit/wmi_spec.rb index cc26262..dbef353 100644 --- a/spec/unit/wmi_spec.rb +++ b/spec/unit/wmi_spec.rb @@ -35,33 +35,30 @@ describe WmiLite::Wmi do let(:wbem_connection) { double 'WIN32OLE', :ExecQuery => native_query_result } def validate_query_result(actual, expected) - expected_result = actual.count == expected.count + expect(actual.count).to eql(expected.count) index = 0 - if expected_result - expected.each do | expected_value | - actual_value = actual[index] - expected_value.invoke == actual_value.wmi_ole_object.invoke - expected_value.properties_.each do | expected_property | - if actual_value[expected_property.name].nil? - expected_result = false - end - if !! actual_value.wmi_ole_object.properties_.find { | actual_property | actual_property == expected_property.name } - expected_result = false - end - if ! expected_result - break - end - end - index += 1 + + expected.each do | expected_value | + actual_value = actual[index] + expected_value.wmi_ole_object.invoke == actual_value.wmi_ole_object.invoke + expected_value.wmi_ole_object.properties_.each do | expected_property | + + expect(actual_value[expected_property.name]).not_to eql(nil) + + names = actual_value.wmi_ole_object.properties_.map { | property | property.name } + + expect(names.include?(expected_property.name)).to eql(true) + end + index += 1 end - - expected_result end before(:each) do + stub_const('WIN32OLE', Class.new) WIN32OLE.stub(:new).with("WbemScripting.SWbemLocator").and_return(wbem_locator) + stub_const('WIN32OLERuntimeError', Class.new(Exception)) end let(:wmi) { WmiLite::Wmi.new } @@ -76,7 +73,7 @@ describe WmiLite::Wmi do expect( result_count ).to eq(0) end - shared_examples_for "the first method" do + shared_examples_for "the first_of method" do let(:wmi_properties1) { { 'cores' => 4, 'name' => 'mycomputer1', 'diskspace' => 400, 'os' => 'windows' } } let(:wmi_properties2) { { 'cores' => 2, 'name' => 'mycomputer2', 'bios' => 'ami', 'os' => 'windows' } } @@ -94,11 +91,198 @@ describe WmiLite::Wmi do it "should get one instance" do results = wmi.first_of('vm') expected_result = WmiLite::Wmi::Instance.new(native_query_result.first) - is_expected = validate_query_result([results], [expected_result.wmi_ole_object]) - expect(is_expected).to eq(true) + validate_query_result([results], [expected_result]) + end + end + + context "when returning more than one instance in the query" do + let(:wmi_query_result) { wmi_query_result2 } + let(:native_query_result) { native_query_result2 } + + it "should get one instance" do + results = wmi.first_of('vm') + expected_result = WmiLite::Wmi::Instance.new(native_query_result.first) + validate_query_result([results], [expected_result]) + end + end + + end + + shared_examples_for "the instances_of method" do + + let(:wmi_properties1) { { 'cores' => 4, 'name' => 'mycomputer1', 'diskspace' => 400, 'os' => 'windows' } } + let(:wmi_properties2) { { 'cores' => 2, 'name' => 'mycomputer2', 'bios' => 'ami', 'os' => 'windows' } } + let(:native_query_result) { [].to_enum } + + it "should not fail with empty query results" do + results = wmi.instances_of('vm') + expect( results ).to eq([]) + end + + context "when returning one instance in the query" do + let(:wmi_query_result) { wmi_query_result1 } + let(:native_query_result) { native_query_result1 } + + it "should get one instance" do + results = wmi.instances_of('vm') + index = 0 + expected_result = results.map do | result | + WmiLite::Wmi::Instance.new(result.wmi_ole_object) + end + validate_query_result(results, expected_result) + end + end + + context "when returning one instance in the query" do + let(:wmi_query_result) { wmi_query_result2 } + let(:native_query_result) { native_query_result2 } + + it "should get one instance" do + results = wmi.instances_of('vm') + index = 0 + expected_result = results.map do | result | + WmiLite::Wmi::Instance.new(result.wmi_ole_object) + end + validate_query_result(results, expected_result) + end + end + + end + + shared_examples_for 'an invalid query' do + let(:unparseable_error) { 'unparseableerror' } + it 'should raise an exception' do + wbem_connection.should_receive(:ExecQuery).and_raise(WIN32OLERuntimeError) + wmi_service = WmiLite::Wmi.new + expect { wmi_service.send(query_method, wmi_query) }.to raise_error(WmiLite::WmiException) + end + + it 'should raise an exception that ends with the original exception message' do + wbem_connection.should_receive(:ExecQuery).and_raise(WIN32OLERuntimeError.new(unparseable_error)) + wmi_service = WmiLite::Wmi.new + error_message = nil + begin + wmi_service.send(query_method, wmi_query) + rescue WmiLite::WmiException => e + error_message = e.message + end + expect(error_message).not_to eql(nil) + expect(e.message.start_with?(unparseable_error)).to eql(false) + expect(e.message.end_with?(unparseable_error)).to eql(true) + end + end + + shared_examples_for 'an invalid namespace' do + let(:unparseable_error) { 'unparseableerror' } + it 'should raise an exception' do + wbem_locator.should_receive(:ConnectServer).and_raise(WIN32OLERuntimeError) + wmi_service = WmiLite::Wmi.new('notavalidnamespace') + expect { wmi_service.send(query_method, wmi_query) }.to raise_error(WmiLite::WmiException) + end + + it 'should raise an exception that starts with the original exception message' do + wbem_locator.should_receive(:ConnectServer).and_raise(WIN32OLERuntimeError.new(unparseable_error)) + wmi_service = WmiLite::Wmi.new + error_message = nil + begin + wmi_service.send(query_method, wmi_query) + rescue WmiLite::WmiException => e + error_message = e.message + end + + expect(error_message).not_to eql(nil) + expect(error_message.start_with?(unparseable_error)).to eql(false) + expect(error_message.end_with?(unparseable_error)).to eql(true) + end + end + + shared_examples_for "the query method" do + + let(:wmi_properties1) { { 'cores' => 4, 'name' => 'mycomputer1', 'diskspace' => 400, 'os' => 'windows' } } + let(:wmi_properties2) { { 'cores' => 2, 'name' => 'mycomputer2', 'bios' => 'ami', 'os' => 'windows' } } + let(:native_query_result) { [].to_enum } + + it "should not fail with empty query results" do + results = wmi.query('vm') + expect( results ).to eq([]) + end + + context "when returning one instance in the query" do + let(:wmi_query_result) { wmi_query_result1 } + let(:native_query_result) { native_query_result1 } + + it "should get one instance" do + results = wmi.query('vm') + index = 0 + expected_result = results.map do | result | + WmiLite::Wmi::Instance.new(result.wmi_ole_object) + end + validate_query_result(results, expected_result) end end + + context "when returning one instance in the query" do + let(:wmi_query_result) { wmi_query_result2 } + let(:native_query_result) { native_query_result2 } + + it "should get one instance" do + results = wmi.query('vm') + index = 0 + expected_result = results.map do | result | + WmiLite::Wmi::Instance.new(result.wmi_ole_object) + end + validate_query_result(results, expected_result) + end + end + + end + + context "when constructing a Ruby class instance" do + it "should not connect to WMI in the constructor" do + WmiLite::Wmi.any_instance.should_not_receive(:connect_to_namespace) + wmi_service_nil_namespace = WmiLite::Wmi.new + wmi_service_explicit_namespace = WmiLite::Wmi.new('root/cimv2') + end + end + + context "when calling query methods" do + it "should only connect to WMI on the first query execution" do + WIN32OLE.should_receive(:new).with("WbemScripting.SWbemLocator").exactly(1).times.and_return(wbem_locator) + wmi_service = WmiLite::Wmi.new + + # Make a lot of queries to be sure the connection is only created once + wmi_service.query('select * from Win32_Process') + wmi_service.query('select * from Win32_Process') + wmi_service.instances_of('Win32_Processor') + wmi_service.instances_of('Win32_Processor') + wmi_service.first_of('Win32_Group') + wmi_service.first_of('Win32_Group') + end + end + + context 'when making invalid queries' do + let(:namespace) { nil } + + let(:wmi_query) { 'invalidclass' } + let(:query_method) { :first_of } + + it_behaves_like 'an invalid query' + it_behaves_like 'an invalid namespace' + + let(:query_method) { :instances_of } + it_behaves_like 'an invalid query' + it_behaves_like 'an invalid namespace' + + let(:query_method) { :query } + let(:wmi_query) { 'nosql_4_life' } + it_behaves_like 'an invalid query' + it_behaves_like 'an invalid namespace' end - it_should_behave_like "the first method" + it_should_behave_like "the first_of method" + + it_should_behave_like "the instances_of method" + + it_should_behave_like "the query method" + end |