virtualbox-ws 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c19d181323956fc9c6a21c66e82471f872f5f09c
-  data.tar.gz: 14ef98271b843289e6d4fcbdc893971ba941a8f9
+  metadata.gz: 80c77a12b207c590f0452020f4d1496c7daff5c9
+  data.tar.gz: aa3690fe67150ea512f352c4834afc940d57a6ba
 SHA512:
-  metadata.gz: 2244297783f0448236657edd24e391d0c70fb68b1d8437a37dfbc14374d7f5c0c235cfd118440532cb4a323edfd2c6c6b8ed0841968c6ad2afb6bd640ee95145
-  data.tar.gz: db8aa2318dbefec7af12b7e18b1d1b98675d471976f5c3d502373f2ffb729fb0e49ec21390f5d2cdaf8d6d9fea712a0f390e192b9d1ac996071521577cd311c5
+  metadata.gz: 76c36a515aa156137702111ae583e4d9b8a16412cdacbd83569834dbff027df21c8592a62058687fb31735b1bdd366436e24d098c0d3763fe6b4261c45887f5a
+  data.tar.gz: c1af9e63a2446c9f2119edacd8fb54c4697061280c239bad9727b45e4d3183f55dde51ca46b04a74213ae441bba33390b5934522a8b256c72e466a3c3e67203e

data/.gitignore

@@ -1 +1,3 @@
-.idea
+.idea
+tests/*
+*.gem

data/Gemfile

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

data/Gemfile.lock

@@ -13,6 +13,7 @@ GEM
     nokogiri (1.5.10)
     nori (2.3.0)
     rack (1.5.2)
+    require_all (1.3.1)
     rubyntlm (0.3.4)
     savon (2.3.0)
       akami (~> 1.2.0)
@@ -30,4 +31,5 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  require_all
   savon

data/LICENSE.md

@@ -0,0 +1,5 @@
+Copyright (C) 2013 Andriy Yurchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,39 +1,74 @@
+This library is an attempt to create an object-oriented wrapper in Ruby for VirtualBox SOAP Web Service.
+This library's interface basically resembles the COM interface provided by VirtualBox and described in
+[VirtualBox SDK Reference](http://download.virtualbox.org/virtualbox/SDKRef.pdf) with some exceptions:
+
+1. All classes have the leading 'I' removed so `IGuestSession` becomes `GuestSession`
+2. All methods' and attributes' names are converted from camel case to underscore so `addStorageController` becomes
+`add_storage_controller`
+3. Interfaces and methods that are marked as not supported in the webservice in VirtualBox SDK Reference are not
+supported here
+
+Documentation
+-------------
+
+The main source of documentation is the [VirtualBox SDK Reference](http://download.virtualbox.org/virtualbox/SDKRef.pdf)
+
+
 Usage
 -----
 
+Require the gem
+```
+irb> require 'virtualbox-ws'
+ => true 
+```
+
 First connect to vboxwebsrv service
 ```
-irb> VirtualBoxWS.connect
+irb> VBox::WebService.connect
  => true
 ```
+
 By default it connects to `http://127.0.0.1:18083` but host and port parameters can be passed to the connect method
 explicitly
-
-To operate on the VirtualBox Web Service you need to logon to it.
 ```
-irb> web_session = VirtualBoxWS::IWebsessionManager.new
- => #<VirtualBoxWS::IWebsessionManager:0x0000000383b9b0 @_this={}>
-irb> key = web_session.logon(:username => 'john', :password => 'doe')
- => "deb9086e1f72ddbf-0000000000000002"
+irb> VBox::WebService.connect(:host => 'localhost', :port => '18083')
+ => true
+```
+
+To enable debug logging for SOAP operations a debug flag can be set for connection
 ```
-Having a key we can now create an instance of IVirtualBox class, which is basically the entry point for the whole
-VirtualBox operations scope.
+irb > VBox::WebService.connect(:debug => true)
+D, [2013-10-08T18:52:22.839743 #18132] DEBUG -- : HTTPI GET request to localhost (net_http)
+ => true 
 ```
-irb> i_virtualbox = VirtualBoxWS::IVirtualBox.new(key)
- => #<VirtualBoxWS::IVirtualBox:0x0000000352a028 @_this={:_this=>"deb9086e1f72ddbf-0000000000000002"}>
+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
 ```
-Now having an IVirtualBox we are ready to do something useful. The following will create a very basic virtual machine
+irb> web_session = VBox::WebsessionManager.new
+ => #<VBox::WebsessionManager:0x00000005deb4a8 @ref=nil> 
+irb> virtual_box = web_session.logon(:username => 'user', :password => 'password')
+ => #<VBox::VirtualBox:0x000000062bc8d8 @ref="47efe040fcc25df7-000000000000001d"> 
+
 ```
-irb> machine = i_virtualbox.create_machine(:name => 'JohnDoe')
- => "deb9086e1f72ddbf-0000000000000003"
-irb> i_virtualbox.register_machine(:machine => machine)
- => nil
+
+Having a VirtualBox instance we can query various VirtualBox installation info as well as create virtual machines...
 ```
-To start the machine we've just created we first need to create an instance of IMachine passing it our machine's
-object reference. After that we are able to execute launch_vm_process on this instance
+irb> virtual_box.version
+ => "4.2.18" 
+irb> machine = virtual_box.create_machine(:name => 'machine_1')
+ => #<VBox::Machine:0x00000005841f98 @ref="47efe040fcc25df7-000000000000001e"> 
+irb> virtual_box.register_machine(:machine => machine)
+ => nil     
+2.0.0p247 :013 > machine.memory_size
+ => "128" 
+2.0.0p247 :014 > machine.cpu_count
+ => "1"
 ```
-irb> i_machine = VirtualBoxWS::IMachine.new(machine)
- => #<VirtualBoxWS::IMachine:0x000000047fdee8 @_this={:_this=>"deb9086e1f72ddbf-0000000000000003"}>
-irb> i_machine.launch_vm_process(:session => web_session.get_session_object, :type => 'gui')
- => "deb9086e1f72ddbf-0000000000000004"
+
+...and run virtual machines
 ```
+irb> machine.launch_vm_process(:session => web_session.get_session_object, :type => 'headless')
+ => #<VBox::Progress:0x00000005934040 @ref="47efe040fcc25df7-000000000000001f"> 
+```

data/lib/core_ext/string.rb

@@ -0,0 +1,5 @@
+class String
+  def to_a
+    self.split
+  end
+end

data/lib/virtualbox-ws.rb

@@ -1,6 +1,2 @@
-require File.expand_path(File.dirname(__FILE__) + '/virtualbox/connection')
-require File.expand_path(File.dirname(__FILE__) + '/virtualbox/i_base')
-require File.expand_path(File.dirname(__FILE__) + '/virtualbox/enumerations')
-
-classes_dir = File.expand_path(File.dirname(__FILE__)) + '/virtualbox/classes/*.rb'
-Dir[classes_dir].each { |file| require file }
+require 'require_all'
+require_rel 'virtualbox'

data/lib/virtualbox/base.rb

@@ -0,0 +1,31 @@
+require_rel '/../core_ext/string.rb'
+
+
+module VBox
+
+  attr_reader :ref
+
+  class Base
+    def initialize(obj_ref)
+      @ref = obj_ref
+    end
+
+    def _this
+      _this = {}
+      _this[:_this] = @ref unless @ref.nil?
+      _this
+    end
+
+    def vbox_class
+      VBox::ManagedObjectRef.new(@ref).get_interface_name
+    end
+
+    def delete!
+      VBox::ManagedObjectRef.new(@ref).release
+    end
+
+    def ensure_hash(args)
+      raise ArgumentError, 'Method arguments must be a hash' unless args.is_a?(Hash)
+    end
+  end
+end

data/lib/virtualbox/classes/additions_facility.rb

@@ -0,0 +1,28 @@
+module VBox
+  class AdditionsFacility < Base
+
+    attr_reader :ref
+
+    # Attributes
+
+    def class_type
+      VBox::WebService.send_request(:i_additions_facility_get_class_type, _this)
+    end
+
+    def last_updated
+      VBox::WebService.send_request(:i_additions_facility_get_last_updated, _this)
+    end
+
+    def name
+      VBox::WebService.send_request(:i_additions_facility_get_name, _this)
+    end
+
+    def status
+      VBox::WebService.send_request(:i_additions_facility_get_status, _this)
+    end
+
+    def type
+      VBox::WebService.send_request(:i_additions_facility_get_type, _this)
+    end
+  end
+end

data/lib/virtualbox/classes/appliance.rb

@@ -0,0 +1,51 @@
+module VBox
+  class Appliance < Base
+
+    attr_reader :ref
+
+    # 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
+  end
+end

data/lib/virtualbox/classes/audio_adapter.rb

@@ -0,0 +1,33 @@
+module VBox
+  class AudioAdapter < Base
+
+    attr_reader :ref
+
+    # Attributes
+
+    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

@@ -0,0 +1,36 @@
+module VBox
+  class BandwidthControl < Base
+
+    attr_reader :ref
+
+    # Attributes
+
+    def num_groups
+      VBox::WebService.send_request(:i_bandwidth_control_get_num_groups, _this)
+    end
+
+    # 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

@@ -0,0 +1,29 @@
+module VBox
+  class BandwidthGroup < Base
+
+    attr_reader :ref
+
+    # Attributes
+
+    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

@@ -0,0 +1,81 @@
+module VBox
+  class BIOSSettings < Base
+
+    attr_reader :ref
+
+    # Attributes
+
+    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