virtualbox-ws 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 495f1e85b6ec631b315313c62e9490f16cb34d2c
-  data.tar.gz: d44a6b5accce3381292346837e05b40941af8d7d
+  metadata.gz: b65ace3ebbb598bf587a6776bd4e4e309639103c
+  data.tar.gz: 318b9c8467b43c6b6de9e5e4fb056b6721d9bf80
 SHA512:
-  metadata.gz: ed2bb05225197f7a5c9d8967f4ad6e674d30903b3979e9e8b8a708a8b301caaa7759df7d5a11e2654a2b0223ddfec84cabbbe3b72601e071e7da2e791fb3c053
-  data.tar.gz: deb10227d1943f08cab161fbd18da80888527cb183e1580be082dfa61174ae87eea0bc7b501f6d25b8797bcee777da6941f5f779e32eb6bdeec618ead9f3a24a
+  metadata.gz: aa1237ee6dfd4b17e37b3f681dacd5238397501538438fd30d02092fc6f4fc83e900e164f0cbad6fdd07631a92d3614093f20e88ffdd8888d4376219d9d1e057
+  data.tar.gz: 99d997c9b0e8cf392c3b91f88c88a721b02e1690052f5c8d2fb75634f445f7b0ff9d260efba5eb8e94bbfcb4252e48e0f1c87d0340b2f4e7f304f44bca5a9704

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
-gem 'require_all'
-gem 'savon'
+gemspec

data/Gemfile.lock

@@ -1,3 +1,10 @@
+PATH
+  remote: .
+  specs:
+    virtualbox-ws (0.0.4)
+      require_all
+      savon
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -31,5 +38,4 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  require_all
-  savon
+  virtualbox-ws!

data/README.md

@@ -7,6 +7,8 @@ This library's interface basically resembles the COM interface provided by Virtu
 `add_storage_controller`
 3. Interfaces and methods that are marked as not supported in the webservice in VirtualBox SDK Reference are not
 supported here
+4. WebsessionManager class is used to both connect to VirtualBox SOAP web service and to authenticate on it
+
 
 Documentation
 -------------
@@ -14,49 +16,64 @@ Documentation
 The main source of documentation is the [VirtualBox SDK Reference](http://download.virtualbox.org/virtualbox/SDKRef.pdf)
 
 
+Installation
+-------
+
+```
+gem install virtualbox-ws
+```
+
+
+Configuration
+-------------
+
+You can override any of these configuration defaults:
+
+```
+VBox::WebService.configure do |config|
+  config.vboxweb_host = ENV['VBOXWEB_HOST'] || '127.0.0.1'
+  config.vboxweb_port = ENV['VBOXWEB_PORT'] || '18083'
+  config.vboxweb_user = ENV['VBOXWEB_USER']
+  config.vboxweb_pass = ENV['VBOXWEB_PASS']
+  config.log_level = ENV['VBOXWEB_LOGGING'] || 'ERROR'
+end
+```
+Each of these configuration options can be set as environment variables.
+
+`config.log_level` can be one of `ERROR`, `INFO`, `DEBUG`
+
+
 Usage
 -----
 
 Require the gem
+
 ```
 irb> require 'virtualbox-ws'
  => true 
 ```
 
-First connect to vboxwebsrv service
-```
-irb> VBox::WebService.connect
- => true
-```
+An instance of VBox::WebsessionManager connects to VirtualBox SOAP wen service
 
-By default it connects to `http://127.0.0.1:18083` but host and port parameters can be passed to the connect method
-explicitly
 ```
-irb> VBox::WebService.connect(:host => 'localhost', :port => '18083')
- => true
+irb> web_session = VBox::WebsessionManager.new
+ => #<VBox::WebsessionManager:0x00000005deb4a8 @ref=nil>
 ```
 
-To enable debug logging for SOAP operations a debug flag can be set for connection
-```
-irb > VBox::WebService.connect(:debug => true)
-D, [2013-10-08T18:52:22.839743 #18132] DEBUG -- : HTTPI GET request to localhost (net_http)
- => true 
-```
-To do anything useful on a VirtualBox installation you first have to create an instance of the VirtualBox class which
-according to VirtualBox SDK Reference is "the main interface exposed by the product that provides virtual machine
-management". VirtualBox instance is created upon logging on to the SOAP web service
+The logon method will authenticate you on the web service and create an instance of the VirtualBox class
+which according to VirtualBox SDK Reference is "the main interface exposed by the product that provides virtual machine
+management".
+
 ```
-irb> web_session = VBox::WebsessionManager.new
- => #<VBox::WebsessionManager:0x00000005deb4a8 @ref=nil> 
-irb> virtual_box = web_session.logon(:username => 'user', :password => 'password')
+irb> virtual_box = web_session.logon
  => #<VBox::VirtualBox:0x000000062bc8d8 @ref="47efe040fcc25df7-000000000000001d"> 
-
 ```
 
 Having a VirtualBox instance we can query various VirtualBox installation info as well as create virtual machines...
+
 ```
 irb> virtual_box.version
- => "4.2.18" 
+ => "4.3.0"
 irb> machine = virtual_box.create_machine(:name => 'machine_1')
  => #<VBox::Machine:0x00000005841f98 @ref="47efe040fcc25df7-000000000000001e"> 
 irb> virtual_box.register_machine(:machine => machine)
@@ -68,7 +85,8 @@ irb> virtual_box.register_machine(:machine => machine)
 ```
 
 ...and run virtual machines
+
 ```
-irb> machine.launch_vm_process(:session => web_session.get_session_object, :type => 'headless')
+irb> machine.launch_vm_process(:session => web_session.get_session_object)
  => #<VBox::Progress:0x00000005934040 @ref="47efe040fcc25df7-000000000000001f"> 
 ```

data/lib/core_ext/hash.rb

@@ -1,12 +1,12 @@
 class Hash
-  def referize!(*keys)
-    keys.each do |key|
-      if self[key].is_a?(Array)
-        self[key].map! do |item|
+  def referize!
+    self.each do |key, value|
+      if value.is_a?(Array)
+        value.map! do |item|
           item.respond_to?(:ref) ? item.ref : item
         end
-      elsif self[key].respond_to?(:ref)
-        self[key] = self[key].ref
+      elsif value.respond_to?(:ref)
+        self[key] = value.ref
       end
     end
   end

data/lib/core_ext/string.rb

@@ -2,4 +2,12 @@ class String
   def to_a
     self.split
   end
+
+  def to_underscore
+    self.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr('-', '_').
+        downcase
+  end
 end

data/lib/virtualbox/base.rb

@@ -13,16 +13,128 @@ module VBox
       _this
     end
 
-    def vbox_class
-      VBox::ManagedObjectRef.new(@ref).get_interface_name
+    def ensure_hash(args)
+      raise ArgumentError, 'Method arguments must be a hash' unless args.is_a?(Hash)
     end
 
-    def delete!
-      VBox::ManagedObjectRef.new(@ref).release
+    def self.starts_with_acronym
+      define_method(:starts_with_acronym) {}
     end
 
-    def ensure_hash(args)
-      raise ArgumentError, 'Method arguments must be a hash' unless args.is_a?(Hash)
+    def self.soap_method(method_name, modifier=nil)
+      is_acronym_part = defined?(starts_with_acronym) ? '_' : ''
+      modifier_part = modifier.nil? ? '' : modifier + '_'
+      "i#{is_acronym_part}#{class_name}_#{modifier_part}#{method_name}".to_sym
+    end
+
+    def soap_method(method_name, modifier=nil)
+      self.class.soap_method(method_name, modifier)
+    end
+
+    def self.class_name
+      self.name.split('::').last.to_underscore
+    end
+
+    def class_name
+      self.class.class_name
+    end
+
+    def integerize(value)
+      if value.is_a?(Array)
+        value.map do |item|
+          begin
+            Integer(item)
+          rescue ArgumentError
+            item
+          end
+        end
+      else
+        begin
+          Integer(value)
+        rescue ArgumentError
+          value
+        end
+      end
+    end
+
+    def classify(result, force_array=false)
+      if force_array
+        return [] if result.nil?
+        result = result.to_a
+
+        # Will assume here that in case of force_array all the items
+        # in the array are objects of the same class
+        val = result[0]
+      else
+        val = result
+      end
+
+      # If the result is not a string return it immediately
+      return integerize(result) unless val.is_a?(String)
+
+      # Check for a match
+      return integerize(result) if val.match(/^[0-9a-f]{16}-[0-9a-f]{16}$/).nil?
+
+      # Get VirtualBox interface name
+      class_str = ManagedObjectRef.new(val).get_interface_name
+
+      # ManagedObjectRef.get_interface_name returns nil
+      # for inexisting object reference
+      if class_str.nil?
+        result
+      else
+        if force_array
+          result.to_a.map { |item| VBox.const_get(class_str[1..-1]).new(item) }
+        else
+          VBox.const_get(class_str[1..-1]).new(result)
+        end
+      end
+    end
+
+    def self.vb_attr(name, options={})
+      force_array = options[:force_array]
+      force_tag = options[:force_tag]
+
+      # A special case for VirtualBox methods that have lowercase 'v' in IPv6
+      if name.to_s.start_with?('ipv6') || name.to_s.include?('advertise_default_ipv6_route_enabled')
+        name = name.to_s.gsub('ipv6', 'i_pv6').to_sym
+      end
+
+      define_method(name) do
+        result = WebService.send_request(soap_method(name, 'get'), _this)
+        process_result(result, force_array)
+      end
+
+      define_method("#{name}=") do |value|
+        soap_message = {force_tag ? force_tag : name => value}
+        result = WebService.send_request(soap_method(name, 'set'), _this.merge(soap_message))
+        process_result(result)
+      end if WebService.operations.include?(soap_method(name, 'set'))
+    end
+
+    def self.vb_method(name, options={})
+      force_array = options[:force_array]
+
+      define_method(name) do |meth_args = {}|
+        ensure_hash meth_args
+        meth_args.referize!
+        result = WebService.send_request(soap_method(name), _this.merge(meth_args))
+        process_result(result, force_array)
+      end
+    end
+
+    def process_result(result, force_array=false)
+      if force_array
+        classify(result, true)
+      else
+        if result.is_a?(Array)
+          result.map do |item|
+            item.is_a?(Hash) ? item.update(item) { |_, value| classify(value) } : classify(item)
+          end
+        else
+          classify(result)
+        end
+      end
     end
   end
 end

data/lib/virtualbox/classes/appliance.rb

@@ -1,49 +1,16 @@
 module VBox
   class Appliance < Base
 
-    # Attributes
-
-    def path
-      VBox::WebService.send_request(:i_appliance_get_path, _this)
-    end
-
-    def disks
-      VBox::WebService.send_request(:i_appliance_get_disks, _this.merge)
-    end
-
-    def virtual_system_descriptions
-      virtual_system_descriptions = VBox::WebService.send_request(:i_appliance_get_virtual_system_descriptions, _this)
-      virtual_system_descriptions.map do |virtual_system_description|
-        VBox::VirtualSystemDescription.new(virtual_system_description)
-      end
-    end
-
-    def machines
-      VBox::WebService.send_request(:i_appliance_get_machines, _this.merge)
-    end
-
-    # Methods
-
-    def create_vfs_explorer(args={})
-      ensure_hash args
-      vfs_explorer = VBox::WebService.send_request(:i_appliance_create_vfs_explorer, _this.merge(args))
-      VBox::VFSExplorer.new(vfs_explorer)
-    end
-
-    def interpret
-      VBox::WebService.send_request(:i_appliance_interpret, _this)
-    end
-
-    def read(args={})
-      ensure_hash args
-      progress = VBox::WebService.send_request(:i_appliance_read, _this.merge(args))
-      VBox::Progress.new(progress)
-    end
-
-    def write(args={})
-      ensure_hash args
-      progress = VBox::WebService.send_request(:i_appliance_write, _this.merge(args))
-      VBox::Progress.new(progress)
-    end
+    vb_attr :path
+    vb_attr :disks, :force_array => true
+    vb_attr :virtual_system_descriptions, :force_array => true
+    vb_attr :machines, :force_array => true
+
+    vb_method :create_vfs_explorer
+    vb_method :get_warnings, :force_array => true
+    vb_method :import_machines
+    vb_method :interpret
+    vb_method :read
+    vb_method :write
   end
 end

data/lib/virtualbox/classes/audio_adapter.rb

@@ -1,31 +1,9 @@
 module VBox
   class AudioAdapter < Base
 
-    # Attributes
+    vb_attr :enabled
+    vb_attr :audio_controller
+    vb_attr :audio_driver
 
-    def enabled
-      VBox::WebService.send_request(:i_audio_adapter_get_enabled, _this)
-    end
-
-    def enabled=(enabled)
-      VBox::WebService.send_request(:i_audio_adapter_set_enabled, _this.merge(:enabled => enabled))
-    end
-
-    def audo_controller
-      VBox::WebService.send_request(:i_audio_adapter_get_audo_controller, _this)
-    end
-
-    def audo_controller=(audo_controller)
-      VBox::WebService.send_request(:i_audio_adapter_set_audo_controller,
-                                    _this.merge(:audo_controller => audo_controller))
-    end
-
-    def audo_driver
-      VBox::WebService.send_request(:i_audio_adapter_get_audo_driver, _this)
-    end
-
-    def audo_driver=(audo_driver)
-      VBox::WebService.send_request(:i_audio_adapter_set_audo_driver, _this.merge(:audo_driver => audo_driver))
-    end
   end
 end

data/lib/virtualbox/classes/bandwidth_control.rb

@@ -1,34 +1,12 @@
 module VBox
   class BandwidthControl < Base
 
-    # Attributes
+    vb_attr :num_groups
 
-    def num_groups
-      VBox::WebService.send_request(:i_bandwidth_control_get_num_groups, _this)
-    end
+    vb_method :create_bandwidth_group
+    vb_method :delete_bandwidth_group
+    vb_method :get_all_bandwidth_groups, :force_array => true
+    vb_method :get_bandwidth_group
 
-    # Methods
-
-    def create_bandwidth_group(args={})
-      ensure_hash args
-      VBox::WebService.send_request(:i_bandwidth_contol_create_bandwidth_group, _this.merge(args))
-    end
-
-    def delete_bandwidth_group(args={})
-      ensure_hash args
-      VBox::WebService.send_request(:i_bandwidth_control_delete_bandwidth_group, _this.merge(args))
-    end
-
-    def get_all_bandwidth_groups
-      bandwidth_groups = VBox::WebService.send_request(:i_bandwidth_control_get_all_bandwidth_groups, _this)
-      bandwidth_groups.map do |bandwidth_group|
-        VBox::BandwidthGroup.new(bandwidth_group)
-      end
-    end
-
-    def get_bandwidth_group
-      bandwidth_group = VBox::WebService.send_request(:i_bandwidth_control_get_bandwidth_group, _this)
-      VBox::BandwidthGroup.new(bandwidth_group)
-    end
   end
 end

data/lib/virtualbox/classes/bandwidth_group.rb

@@ -1,27 +1,10 @@
 module VBox
   class BandwidthGroup < Base
 
-    # Attributes
+    vb_attr :name
+    vb_attr :type
+    vb_attr :reference
+    vb_attr :max_bytes_per_sec
 
-    def name
-      VBox::WebService.send_request(:i_bandwidth_group_get_name, _this)
-    end
-
-    def type
-      VBox::WebService.send_request(:i_bandwidth_group_get_type, _this)
-    end
-
-    def reference
-      VBox::WebService.send_request(:i_bandwidth_group_get_reference, _this)
-    end
-
-    def max_bytes_per_sec
-      VBox::WebService.send_request(:i_bandwidth_group_get_max_bytes_per_sec, _this)
-    end
-
-    def max_bytes_per_sec=(max_bytes_per_sec)
-      VBox::WebService.send_request(:i_bandwidth_group_get_max_bytes_per_sec,
-                                    _this.merge(:max_bytes_per_sec => max_bytes_per_sec))
-    end
   end
 end

data/lib/virtualbox/classes/bios_settings.rb

@@ -1,79 +1,18 @@
 module VBox
   class BIOSSettings < Base
 
-    # Attributes
+    starts_with_acronym
+
+    vb_attr :logo_fade_in
+    vb_attr :logo_fade_out
+    vb_attr :logo_display_time
+    vb_attr :logo_image_path
+    vb_attr :boot_menu_mode
+    vb_attr :acpi_enabled, :force_tag => 'ACPIEnabled'
+    vb_attr :ioapic_enabled, :force_tag => 'IOAPICEnabled'
+    vb_attr :time_offset
+    vb_attr :pxe_debug_enabled, :force_tag => 'PXEDebugEnabled'
+    vb_attr :non_volatile_storage_file
 
-    def logo_fade_in
-      VBox::WebService.send_request(:ibios_settings_get_logo_fade_in, _this)
-    end
-
-    def logo_fade_in=(logo_fade_in)
-      VBox::WebService.send_request(:ibios_settings_set_logo_fade_in, _this.merge(:logo_fade_in => logo_fade_in))
-    end
-
-    def logo_fade_out
-      VBox::WebService.send_request(:ibios_settings_get_logo_fade_out, _this)
-    end
-
-    def logo_fade_out=(logo_fade_out)
-      VBox::WebService.send_request(:ibios_settings_set_logo_fade_out, _this.merge(:logo_fade_out => logo_fade_out))
-    end
-
-    def logo_display_time
-      VBox::WebService.send_request(:ibios_settings_get_logo_display_time, _this)
-    end
-
-    def logo_display_time=(logo_display_time)
-      VBox::WebService.send_request(:ibios_settings_set_logo_display_time,
-                                    _this.merge(:logo_display_time => logo_display_time))
-    end
-
-    def logo_image_path
-      VBox::WebService.send_request(:ibios_settings_get_logo_image_path, _this)
-    end
-
-    def logo_image_path=(logo_image_path)
-      VBox::WebService.send_request(:ibios_settings_set_logo_image_path, _this.merge(:logo_image_path => logo_image_path))
-    end
-
-    def boot_menu_mode
-      VBox::WebService.send_request(:ibios_settings_get_boot_menu_mode, _this)
-    end
-
-    def boot_menu_mode=(boot_menu_mode)
-      VBox::WebService.send_request(:ibios_settings_set_boot_menu_mode, _this.merge(:boot_menu_mode => boot_menu_mode))
-    end
-
-    def acpi_enabled
-      VBox::WebService.send_request(:ibios_settings_get_acpi_enabled, _this)
-    end
-
-    def acpi_enabled=(acpi_enabled)
-      VBox::WebService.send_request(:ibios_settings_set_acpi_enabled, _this.merge('ACPIEnabled' => acpi_enabled))
-    end
-
-    def ioapic_enabled
-      VBox::WebService.send_request(:ibios_settings_get_ioapic_enabled, _this)
-    end
-
-    def ioapic_enabled=(ioapic_enabled)
-      VBox::WebService.send_request(:ibios_settings_set_ioapic_enabled, _this.merge('IOAPICEnabled' => ioapic_enabled))
-    end
-
-    def time_offset
-      VBox::WebService.send_request(:ibios_settings_get_time_offset, _this)
-    end
-
-    def time_offset=(time_offset)
-      VBox::WebService.send_request(:ibios_settings_set_time_offset, _this.merge(:time_offset => time_offset))
-    end
-
-    def pxe_debug_enabled
-      VBox::WebService.send_request(:ibios_settings_get_pxe_debug_enabled, _this)
-    end
-
-    def pxe_debug_enabled=(pxe_debug_enabled)
-      VBox::WebService.send_request(:ibios_settings_set_pxe_debug_enabled, _this.merge('PXEDebugEnabled' => pxe_debug_enabled))
-    end
   end
 end