virtualbox-com 0.9.6 → 0.9.7

data/.gitignore

@@ -3,6 +3,7 @@ doc/*
 pkg/*
 test/coverage/*
 .bundle/*
+vendor/*
 Gemfile.lock
 test.rb
-*.rbc
+*.rbc

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Mitchell Hashimoto.
+Copyright (c) 2013 Stephane D'Alu / INSA-Lyon, 2010 Mitchell Hashimoto.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -16,4 +16,4 @@ 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.
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# VirtualBox-Com Ruby Gem
+
+The `virtualbox-COM` ruby gem is a library which focus on the
+direct mapping of the VirtualBox API and allows anyone to control
+VirtualBox from ruby code! Create, destroy, start, stop, suspend, and
+resume virtual machines.  Also list virtual machines, list hard
+drives, network devices, etc.
+
+This is a simplified version (focusing on the VirtualBox API) of the 
+unmaintained [virtualbox](https://github.com/mitchellh/virtualbox) gem
+by [Mitchell Hashimoto](https://github.com/mitchellh) from which
+part of this code belongs.
+
+
+## Installation and Requirements
+
+First you need to install [VirtualBox](http://www.virtualbox.org/)
+which is available for Windows, Linux, and OS X. After installation,
+install the gem:
+
+    sudo gem install virtualbox-com
+
+The gem uses the native COM interface which VirtualBox provides to
+communicate with it. The gem uses Ruby-FFI to talk to the VirtualBox 
+dynamic library, and all the mapping as been generated from 
+the `VirtualBox.xidl`.
+
+No configuration should be necessary to use this gem, but if
+the dynamic library is not found, you can set the environment
+variable `VBOX_APP_HOME` to the full library path.
+
+
+## API Documentation
+
+You can refer to the [VirtualBox SDK](https://www.virtualbox.org/sdkref/annotated.html)
+knowning that in this gem
+* classes are not prefixed with the `I` (`IMachine` => `Machine`)
+* methods have been uncamelized (`canShowConsoleWindow` => `can_show_console_window`)
+* when calling a method you only specify the in parameters, all the out (including the default return)
+  are being returned in an array if there is more than one, directly otherwise
+
+
+## Basic Usage
+    require 'virtualbox-com'
+    
+    lib = VirtualBox::COM
+    
+    lib.virtualbox.machines.each {|vm|
+      puts "%s: %s" % [ vm.bame, vm.state ]
+    }
+    
+You can find more examples in the [`examples`](examples) directory
+
+
+## Reporting Bugs or Feature Requests
+
+Please use the [issue tracker](https://github.com/sdalu/virtualbox-com/issues).
+
+
+## TODO
+
+Improve documentation, re-implement a test-suite
+
+
+## Contributing
+
+If you'd like to contribute to VirtualBox, the first step to developing is to
+clone this repo, get [bundler](http://github.com/carlhuda/bundler) if you
+don't have it already, and do the following:
+
+    bundle install --relock
+    rake
+
+This will run the test suite, which should come back all green! Then
+you're good to go!
+
+
+## Special Thanks
+
+These folks went above and beyond with contributions to the virtualbox gem, and
+for that, I have to say "thanks!"
+
+* [Mitchell Hashimoto](https://github.com/mitchellh), 
+  [Kieran Pilkington](https://github.com/KieranP),
+  [Aleksey Palazhchenko](https://github.com/AlekSi)

data/lib/virtualbox/com.rb

@@ -15,6 +15,12 @@ module COM
             raise ModelNotFoundException, name
         end
 
+        def self.fetch(name)
+            self.const_get(name, false)
+        rescue NameError
+            nil
+        end
+
         def self.create(name, *args)
             self.get(name).new(*args)
         end

data/lib/virtualbox/com/model/4.2.rb

@@ -1,9 +1,35 @@
-require_relative '4.2-gen'
+require_relative '4.2-generated'
+require 'set'
 
 module VirtualBox
 module COM
 module Model
 
+
+class Machine < AbstractInterface
+    ONLINE_STATES = Set.new [ :running, 
+                              :paused, 
+                              :stuck,
+                              :teleporting,
+                              :live_snapshotting,
+                              :starting,
+                              :stopping,
+                              :saving,
+                              :restoring,
+                              :teleporting_paused_vm,
+                              :teleporting_in,
+                              :fault_tolerant_syncing,
+                              :deleting_snapshot_online,
+                              :deleting_snapshot_paused,
+                            ]
+
+    def is_online?
+        ONLINE_STATES.include?(state)
+    end
+end
+
+
+
 class Progress < AbstractInterface
     # This method blocks the execution while the operations represented
     # by this {Progress} object execute, but yields a block every `x`
@@ -84,7 +110,7 @@ class EventSource < AbstractInterface
         :on_drag_and_drop_mode_changed    => :DragAndDropModeChangedEvent,
     }
 
-    def getEvent(*args)
+    def get_casted_event(*args)
         if e = get_event(*args)
             (model = MODEL_MAP[e.type]) ? e.cast(model) : e
         end

data/lib/virtualbox/com/util.rb

@@ -35,82 +35,97 @@ module Util
     end
 
     CAMELCASE_SPECIALS = { # Order is important 
-        "fourcc_rgb" => "FOURCC_RGB",
-        "am79c970a"  => "Am79C970A",
-        "am79c973"   => "Am79C973",
-        "i82540em"   => "I82540EM",
-        "i82543gc"   => "I82543GC",
-        "i82545em"   => "I82545EM",
-        "efidual"    => "EFIDUAL",
-        "split2g"    => "Split2G",
-        "cpuid"      => "CPUID",
-        "cdrom"      => "CDROM",
-        "efi32"      => "EFI32",
-        "efi64"      => "EFI64",
-        "piix3"      => "PIIX3",
-        "piix4"      => "PIIX4",
-        "winmm"      => "WinMM",
-        "ac97"       => "AC97",
-        "acpi"       => "ACPI",
-        "alsa"       => "ALSA",
-        "apic"       => "APIC",
-        "bios"       => "BIOS",
-        "csam"       => "CSAM",
-        "dhcp"       => "DHCP",
-        "fifo"       => "FIFO",
-        "ich6"       => "ICH6",
-        "ich9"       => "ICH9",
-        "macs"       => "MACs",
-        "mmpm"       => "MMPM",
-        "patm"       => "PATM",
-        "sata"       => "SATA",
-        "sb16"       => "SB16",
-        "scsi"       => "SCSI",
-        "slip"       => "SLIP",
-        "tftp"       => "TFTP",
-        "vbox"       => "VBox",
-        "vpid"       => "VPID",
-        "vram"       => "VRAM",
-        "vrde"       => "VRDE",
-        "vrdp"       => "VRDP",
-        "api"        => "API",
-        "cpu"        => "CPU",
-        "dns"        => "DNS",
-        "dvd"        => "DVD",
-        "efi"        => "EFI",
-        "esx"        => "ESX",
-        "gid"        => "GID",
-        "hda"        => "HDA",
-        "hdd"        => "HDD",
-        "ide"        => "IDE",
-        "irq"        => "IRQ",
-        "mac"        => "MAC",
-        "nat"        => "NAT",
-        "oss"        => "OSS",
-        "pae"        => "PAE",
-        "pci"        => "PCI",
-        "pid"        => "PID",
-        "png"        => "PNG",
-        "ppp"        => "PPP",
-        "ps2"        => "PS2",
-        "pxe"        => "PXE",
-        "ram"        => "RAM",
-        "rtc"        => "RTC",
-        "sas"        => "SAS",
-        "svc"        => "SVC",
-        "tcp"        => "TCP",
-        "udp"        => "UDP",
-        "uid"        => "UID",
-        "usb"        => "USB",
-        "utc"        => "UTC",
-        "vdi"        => "VDI",
-        "vfs"        => "VFS",
-        "3d"         => "3D",
-        "hw"         => "HW",
-        "io"         => "IO",
-        "ip"         => "IP",
-        "os"         => "OS",
-        "vm"         => "VM",
+        "accelerate_2d" => "accelerate2D",
+        "accelerate_3d" => "accelerate3D",
+        "fourcc_rgb"    => "FOURCC_RGB",
+        "screenshot"    => "ScreenShot",
+        "am79c970a"     => "Am79C970A",
+        "am79c973"      => "Am79C973",
+        "i82540em"      => "I82540EM",
+        "i82543gc"      => "I82543GC",
+        "i82545em"      => "I82545EM",
+        "efidual"       => "EFIDUAL",
+        "split2g"       => "Split2G",
+        "cpuid"         => "CPUID",
+        "cdrom"         => "CDROM",
+        "efi32"         => "EFI32",
+        "efi64"         => "EFI64",
+        "piix3"         => "PIIX3",
+        "piix4"         => "PIIX4",
+        "winmm"         => "WinMM",
+        "ac97"          => "AC97",
+        "acpi"          => "ACPI",
+        "alsa"          => "ALSA",
+        "apic"          => "APIC",
+        "bios"          => "BIOS",
+        "csam"          => "CSAM",
+        "dhcp"          => "DHCP",
+        "fifo"          => "FIFO",
+        "hpet"          => "HPET",
+        "ich6"          => "ICH6",
+        "ich9"          => "ICH9",
+        "ipv6"          => "IPV6",
+        "macs"          => "MACs",
+        "mmpm"          => "MMPM",
+        "patm"          => "PATM",
+        "sata"          => "SATA",
+        "sb16"          => "SB16",
+        "scsi"          => "SCSI",
+        "slip"          => "SLIP",
+        "tftp"          => "TFTP",
+        "uuid"          => "UUID",
+        "vbox"          => "VBox",
+        "vpid"          => "VPID",
+        "vram"          => "VRAM",
+        "vrde"          => "VRDE",
+        "vrdp"          => "VRDP",
+        "acl"           => "ACL",
+        "api"           => "API",
+        "cad"           => "CAD",
+        "cpu"           => "CPU",
+        "dns"           => "DNS",
+        "dvd"           => "DVD",
+        "efi"           => "EFI",
+        "esx"           => "ESX",
+        "gid"           => "GID",
+        "hda"           => "HDA",
+        "hdd"           => "HDD",
+        "hid"           => "HID",
+        "ide"           => "IDE",
+        "irq"           => "IRQ",
+        "iso"           => "ISO",
+        "mac"           => "MAC",
+        "nat"           => "NAT",
+        "oss"           => "OSS",
+        "pae"           => "PAE",
+        "pci"           => "PCI",
+        "pid"           => "PID",
+        "png"           => "PNG",
+        "ppp"           => "PPP",
+        "ps2"           => "PS2",
+        "pxe"           => "PXE",
+        "ram"           => "RAM",
+        "rtc"           => "RTC",
+        "sas"           => "SAS",
+        "svc"           => "SVC",
+        "tcp"           => "TCP",
+        "udp"           => "UDP",
+        "uid"           => "UID",
+        "usb"           => "USB",
+        "utc"           => "UTC",
+        "vdi"           => "VDI",
+        "vfs"           => "VFS",
+        "2d"            => "2D",
+        "3d"            => "3D",
+        "gh"            => "GH",
+        "hg"            => "HG",
+        "hd"            => "HD",
+        "hw"            => "HW",
+        "io"            => "IO",
+        "ip"            => "IP",
+        "os"            => "OS",
+        "vm"            => "VM",
+        "vd"            => "VD",
     }
 
 end

data/lib/virtualbox/com/version.rb

@@ -1,5 +1,5 @@
 module VirtualBox
 module COM
-    VERSION = "0.9.6"
+    VERSION = "0.9.7"
 end
 end

data/lib/virtualbox/com/xpcomc-ffi.rb

@@ -32,26 +32,6 @@ end
 end
 end
 
-module VirtualBox
-module COM
-class AbstractInterface
-    def self.to_ffi
-        :pointer
-    end
-end
-end
-end
-
-
-module VirtualBox
-module COM
-class AbstractEnum
-    def self.to_ffi
-        UINT32
-    end
-end
-end
-end
 
 
 # Load FFI implementation

data/lib/virtualbox/com/xpcomc-ffi/binding.rb

@@ -5,8 +5,20 @@ module XPCOMC
 # The Binding class hold all the FFI infrastructure
 class Binding
     extend ::FFI::Library
+
     attr_reader :object
 
+    def self.init
+        # To simplify code, use typedef for type aliasing
+        typedef :int,     :boolean
+        typedef :pointer, :unicode_string
+        Model.constants.each {|c| m = Model.get(c) 
+            if    m <= AbstractInterface then typedef :pointer, c
+            elsif m <= AbstractEnum      then typedef :uint32,  c
+            end
+        }
+    end
+
 
     # Retrieve a Binding class corresponding to the Model
     # This will avoid polluting the model object with implementation data
@@ -24,6 +36,8 @@ class Binding
     def self.bind(model)
         raise "model already bound" if const_defined?(:Object, false)
 
+#        self.init
+
         # List of functions (name, signature)
         # Defined in the order they appear in the Model definition
         sigs = model.members.inject({}) do |list, spec| 
@@ -32,7 +46,7 @@ class Binding
         const_set(:Sig, sigs)
 
         # Register ffi callbacks
-        sigs.each {|name, sig| callback(name, sig.to_ffi, :uint) }
+        sigs.each {|name, sig| callback(name, sig.to_ffi_callback, :uint) }
 
         # Object layout
         const_set(:Object, Class.new(::FFI::Struct))
@@ -47,7 +61,6 @@ class Binding
 
         # Model
         const_set(:Model, model)
-
         self
     end
 
@@ -78,7 +91,7 @@ class Binding
         if (result & 0x8000_0000) != 0
             raise COMException, :vtbl => name, :code => result
         end
-        sig.retrieve_values(ffi_args)
+        sig.read_values(ffi_args)
     end
 end
 

data/lib/virtualbox/com/xpcomc-ffi/implementer.rb

@@ -33,6 +33,7 @@ class Implementer
         @pointer   = pointer	#  "binding" attribute
     end
 
+    #--[ Required by Model ]-----------------------------------------------
 
     # Cast to another interface.
     # Will raise NoInterfaceException if not supported
@@ -69,13 +70,19 @@ class Implementer
     end
 
 
+    #----------------------------------------------------------------------
+
+    def object
+        binding.object
+    end
+
     #--[ Private ]---------------------------------------------------------
-#    private
+    private
 
     # Lazy initialisation of the binding attribute
     def binding
         @binding ||= begin
-                         name = @interface.class.name.split("::").last
+                         name = @interface.class.name.split('::').last
                          Binding.get(name).new(@pointer)
                      end
     end