virtualbox-com 0.9.6

data/.gitignore

@@ -0,0 +1,8 @@
+doc/*
+.yardoc/*
+pkg/*
+test/coverage/*
+.bundle/*
+Gemfile.lock
+test.rb
+*.rbc

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gemspec
+
+# Gems required for development only.
+group :development do
+  gem "ffi"
+  gem "nokogiri"
+end

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 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
+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/Rakefile

@@ -0,0 +1,8 @@
+# -*- ruby -*-
+require "rbconfig"
+require "rubygems"
+require "bundler/setup"
+
+Bundler::GemHelper.install_tasks
+
+

data/Readme.md

@@ -0,0 +1,59 @@
+# VirtualBox-Com Ruby Gem
+
+This is a simplified version of the unmaintained virtualbox gem
+by [Mitchell Hashimoto](https://github.com/mitchellh)
+
+The VirtualBox::COM ruby gem is a library which 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.
+
+## 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 with VirtualBox provides to
+communicate with VirtualBox. The gem uses Ruby-FFI to talk to a
+dynamic library. No configuration should be necessary.
+
+## Basic Usage
+
+    require 'virtualbox-com'
+    
+    lib = VirtualBox::COM
+    
+    puts lib.virtualbox.machines[0].name
+    puts lib.virtualbox.find_machine('Windows').groups
+
+## Known Issues or Uncompleted Features
+
+All the classes are generated from the VirtualBox.xidl
+
+## Reporting Bugs or Feature Requests
+
+Please use the [issue tracker](https://github.com/sdalu/virtualbox-com/issues).
+
+## 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/examples/simple.rb

@@ -0,0 +1,43 @@
+require 'bundler/setup'
+require 'virtualbox-com'
+
+# Shortcut
+lib = VirtualBox::COM
+
+# Name of the first VM
+puts lib.virtualbox.machines[0].name
+
+# Groups of the VM named 'Windows'
+puts lib.virtualbox.find_machine('Windows').groups
+
+# Register a passive listener
+begin 
+    s = VirtualBox::COM.virtualbox.event_source
+    l = s.create_listener
+    # Listen on all events with a passive listener
+    s.register_listener(l, [ :any ], false)
+    while true do
+        # Get event
+        if e = s.get_event(l, 1000)
+            case e.type
+            when :on_guest_property_changed
+                # If GuestProperyChanged cast the event to the
+                # model having the most information
+                n = e.cast(:GuestPropertyChangedEvent)
+                puts "GuestProperty: #{n.machine_id} / #{n.name} / #{n.value}"
+            else
+                # Display event type
+                puts "Event: #{e.type}"
+            end
+
+            # If event is waitable, acknowlege we have finished with it
+            if e.waitable
+                e.source.event_processed(l, e)
+            end
+        end
+    end
+rescue VirtualBox::COM::ObjectNotFoundException
+    # Could just be because we weren't able to collect data fast
+    # enough, so VirtualBox unregistered our listener
+    retry 
+end

data/lib/virtualbox-com.rb

@@ -0,0 +1 @@
+require_relative 'virtualbox/com.rb'

data/lib/virtualbox/com.rb

@@ -0,0 +1,51 @@
+module VirtualBox
+module COM
+    # Versions of Virtualbox that are supported
+    SUPPORTED_VERSIONS = {
+        "4.2" => [ "3b2f08eb-b810-4715-bee0-bb06b9880ad2",
+                   "12f4dcdb-12b2-4ec1-b7cd-ddd9f6c5bf4d" ],
+    }
+
+    # The Model module will hold all the model descriptions that will
+    # be loaded according to the VirtualBox version
+    module Model
+        def self.get(name)
+            self.const_get(name, false)
+        rescue NameError
+            raise ModelNotFoundException, name
+        end
+
+        def self.create(name, *args)
+            self.get(name).new(*args)
+        end
+    end
+
+    # Information about VirtualBox version
+    def self.supported? ; !version.nil? 	 		   ; end
+    def self.version    ; virtualbox.version_normalized rescue nil ; end
+    def self.revision   ; virtualbox.revision.to_s      rescue nil ; end
+
+    # Helpers for inclusion
+    def virtualbox ; COM.virtualbox ; end
+    def session    ; COM.session    ; end
+end
+end
+
+
+# Exceptions
+require_relative 'com/exceptions'
+
+# Abstract class for model definitions
+require_relative 'com/abstract_enum'
+require_relative 'com/abstract_interface'
+
+# Classes
+require_relative 'com/iid'
+
+# Implementation
+# It needs to add the following to VirtualBox::COM
+#  - Methods: virtualbox, session
+#  - Class  : Implementer
+#  - Types  : INT8, INT16, INT32, INT64, UINT8, UINT16, UINT32, UINT64,
+#             WSTRING, BOOL
+require_relative 'com/xpcomc-ffi'

data/lib/virtualbox/com/abstract_enum.rb

@@ -0,0 +1,51 @@
+require_relative "abstract_model"
+
+module VirtualBox
+module COM
+
+# Represents a C enum type. Provides functionality to easily convert
+# an int value to its proper symbol within the enum.
+class AbstractEnum < AbstractModel
+    extend Enumerable
+
+    # Defines the mapping of int => symbol for the given Enum.
+    # The parameter to this can be an Array or Hash or anything which
+    # respond to `each` and yield a key/value pair.
+    # If a value appear more than once, only the first is kept
+    # If value is left nil, it will return the current mapping
+    def self.map(value = nil)
+        if value
+            m, r = {}, {}
+            if Array === value
+            then value.each_index {|i|   m[value[i]] = i; r[i] = value[i] }
+            else value.each       {|k,v| m[k] = v;        r[v] ||= k      }
+            end            
+            @map, @reverse_map = m, r
+        end
+        
+        @map
+    end
+
+    # Returns the symbol associated with the given key
+    def self.[](index)
+        case index
+        when Symbol then @map[index]
+        else             @reverse_map[index]
+        end
+    end
+
+    # Returns the index associated with a value
+    def self.index(key)
+        @map[key]
+    end
+
+    # Iterate over the enum, yielding each item to a block.
+    def self.each
+        @map.each do |key, value|
+            yield key
+        end
+    end
+end
+
+end
+end

data/lib/virtualbox/com/abstract_interface.rb

@@ -0,0 +1,144 @@
+require_relative "abstract_model"
+
+module VirtualBox
+module COM
+
+#
+# # Defining an Interface
+#
+# Defining an interface is done by subclassing AbstractInterface and
+# using the provided class methods to define the COM methods and
+# properties. A small example class is shown below:
+#
+#     class Time < AbstractInterface
+#       function :now, [[:out, :uint]]
+#       property :hour, :uint
+#     end
+#
+# # Accessing an Interface
+#
+#
+#     # Assume `time` was retrieved already
+#     puts time.foo.to_s
+#     time.hour = 20
+#     x = time.now
+#
+# The above example shows how the properties and functions can be used
+# with a given interface.
+#
+class AbstractInterface < AbstractModel
+    attr_reader :implementer
+
+    class << self
+
+        # Extends the current model with another one.
+        # Note that redefining functions or properties is not supported.
+        def extends(model)
+            Model.get(model).members.each do |spec|
+                if h.include?(spec.name)
+                    raise "redefining of #{spec.name} is not supported"
+                end
+                h[spec.name] = spec
+            end
+        rescue ModelNotFoundException
+            raise "trying to extend an unknown model (#{model})"
+        end
+
+        # Adds a function to the interface
+        def function(name, type, args, opts={})
+            h[name] = Spec::Function.new(name, type, args, opts)
+        end
+
+        # Adds a property to the interface
+        def property(name, type, opts={})
+            h[name] = Spec::Property.new(name, type, opts)
+        end
+
+        # Perform final setup
+        def setup
+            members.each {|spec| name = spec.name
+                case spec
+                when Spec::Function
+                    define_method(name) { |*args| 
+                        @implementer.call_function(spec, *args) 
+                    } unless spec.hide?
+                when Spec::Property
+                    define_method(name) {
+                        @implementer.read_property(spec)
+                    } unless spec.hide?
+                    define_method(:"#{name}=") { |value|
+                        @implementer.write_property(spec, value)
+                    } unless spec.hide? || spec.readonly?
+                end
+            }
+        end
+
+        # Get a member by name
+        def member(name)
+            h[name]
+        end
+
+        # List of members (Spec::*)
+        def members
+            h.values
+        end
+
+        # List of functions (Spec::Function)
+        def functions
+            members.select {|s| s.kind_of?(Spec::Function) }
+        end
+
+        # List if properties (Spec::Property)
+        def properties
+            members.select {|s| s.kind_of?(Spec::Property) }
+        end
+
+        
+        private
+        def h ; @h ||= {} ; end
+    end
+
+
+    # Initializes the interface with the given implementer
+    def initialize(*args)
+        @args = args
+        @implementer = Implementer.new(self, *args)
+    end
+    
+
+    # Cast to another model
+    def cast(name)
+        @implementer.cast(name, *@args)
+    end
+
+    # Reads a property with the given name 
+    def read_property(name)
+        spec = self.class.member(name)
+        raise "#{name} is not a property" unless spec.kind_of?(Spec::Property)
+        @implementer.read_property(spec)
+    end
+
+    # Writes a property with the given name 
+    def write_property(name, value)
+        spec = self.class.member(name)
+        raise "#{name} is not a property" unless spec.kind_of?(Spec::Property)
+        raise "property #{name} is readonly" if spec.readonly?
+        @implementer.write_property(spec, value)
+    end
+
+    # Calls a function with the given name 
+    def call_function(name, *args)
+        spec = self.class.member(name)
+        raise "#{name} is not a function" unless spec.kind_of?(Spec::Function)
+        @implementer.call_function(spec, args)
+    end
+
+
+    # Concise inspect
+    def inspect
+        "#<#{self.class.name}>"
+    end
+end
+
+end
+end

data/lib/virtualbox/com/abstract_model.rb

@@ -0,0 +1,14 @@
+module VirtualBox
+module COM
+
+class AbstractModel
+    def self.iid(str)
+        const_set(:IID, IID.new(str))
+    end
+        
+    def self.setup(opts={})
+    end
+end
+
+end
+end

data/lib/virtualbox/com/exceptions.rb

@@ -0,0 +1,32 @@
+module VirtualBox
+module COM
+
+class ModelNotFoundException < ::Exception; end
+
+class COMException < ::Exception
+    attr_accessor :data
+
+    def initialize(data={})
+        @data = data
+        super("Error in API call to #{data[:function]}: #{data[:code]}")
+    end
+end
+
+class NotImplementedException      < COMException; end
+class ObjectNotFoundException      < COMException; end
+class InvalidVMStateException      < COMException; end
+class VMErrorException             < COMException; end
+class FileErrorException           < COMException; end
+class SubsystemException           < COMException; end
+class PDMException                 < COMException; end
+class InvalidObjectStateException  < COMException; end
+class HostErrorException           < COMException; end
+class NotSupportedException        < COMException; end
+class XMLErrorException            < COMException; end
+class InvalidSessionStateException < COMException; end
+class ObjectInUseException         < COMException; end
+class InvalidArgException          < COMException; end
+class NoInterfaceException         < COMException; end
+
+end
+end