virtualbox 0.6.1 → 0.7.0

data/.yardopts

@@ -1,4 +1,3 @@
 -
 docs/GettingStarted.md
 docs/WhatsNew.md
-TODO

data/Rakefile

@@ -32,7 +32,7 @@ begin
     t.options += ['--title', 'VirtualBox Ruby Library Documentation']
   end
 rescue LoadError
-  puts "Yard not available. Install it with: gem install yard"
+  puts "Yard not available. Install it with: gem install yard bluecloth"
 end
 
 begin

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.7.0

data/lib/virtualbox/abstract_model/attributable.rb

@@ -141,6 +141,7 @@ module VirtualBox
           attributes[name].merge!(options)
 
           # Create the method for reading this attribute
+          define_method("#{name}?") { read_attribute(name) } if options[:boolean]
           define_method(name) { read_attribute(name) }
 
           # Create the writer method for it unless the attribute is readonly,

data/lib/virtualbox/abstract_model/validatable.rb

@@ -3,41 +3,164 @@ module VirtualBox
     # Provides validation methods for a class. Unlike ActiveRecord,
     # validations are instance-level rather than class-level.
     module Validatable
+      # Returns the errors on a model. The structure of this is a hash, keyed
+      # by the field name. The value of each member in the hash is an array of
+      # error messages.
+      #
+      # @return [Hash]
       def errors
         @errors ||= {}
       end
 
+      # Returns the errors on a specific field. This returns nil if there are
+      # no errors, otherwise it returns an array of error messages.
+      def errors_on(field)
+        @errors[field.to_sym]
+      end
+
+      # Adds an error to a field. The error is a message.
       def add_error(field, error)
         errors[field] ||= []
         errors[field].push(error)
       end
 
+      # Clears all the errors from a model.
       def clear_errors
         @errors = {}
       end
 
+      def full_error_messages
+        full_error_messages = Array.new
+        errors.each do |field_name, messages|
+          messages.each do |message|
+            human_field_name = field_name.to_s.gsub('_', ' ').capitalize
+            full_error_messages << "#{human_field_name} #{message}"
+          end
+        end
+        full_error_messages
+      end
+
+      # This method calls the validate method on the model (which any subclass
+      # is expected to implement), and then checks that the validations didn't
+      # add any errors.
+      #
+      # @return [Boolean]
       def valid?
         validate
         errors.empty?
       end
 
-      # Subclasses should override this method.
+      # Subclasses should override this method. Validation can be done any
+      # way an implementer feels. Helper methods such as {#validates_presence_of},
+      # {#validates_inclusion_of}, etc. exist, but they're use isn't required.
+      # {#add_error} can be used to add an error to any field. By convention
+      # this method should return `true` or `false` to signal any errors.
+      #
+      # @return [Boolean]
       def validate
         true
       end
 
-      def validates_presence_of(field)
-        if field.is_a?(Array)
-          field.map { |v| validates_presence_of(v) }.all? { |v| v == true }
-        else
+      # Validates the presence (non-emptiness) of a field or fields. This
+      # validation fails if the specified fields are either blank ("") or
+      # nil.
+      #
+      # Additionally, a custom error message can be specified:
+      #
+      #     validates_presence_of :foo, :bar
+      #     validates_presence_of :baz, :message => "must not be blank!"
+      #
+      # @return [Boolean]
+      def validates_presence_of(*fields)
+        options = __validates_extract_options(fields, {
+          :message => "can't be blank."
+        })
+
+        fields.collect { |field|
+          value = send(field)
+          if value.nil? || value.to_s.empty?
+            add_error(field, options[:message])
+            false
+          else
+            true
+          end
+        }.compact.all? { |v| v == true }
+      end
+
+      # Validates the format of a field with a given regular expression.
+      #
+      #     validates_format_of :foo, :with => /\d+/
+      #
+      def validates_format_of(*fields)
+        options = __validates_extract_options(fields, {
+          :with => nil,
+          :message => "is not properly formatted."
+        })
+
+        fields.collect { |field|
           value = send(field)
-          if value.nil? || value == ""
-            add_error(field, "must not be blank.")
-            return false
+          # Use validates_presence_of if you need it to be set
+          next if value.nil? || value.to_s.empty?
+          if options[:with] && value =~ options[:with]
+            true
           else
-            return true
+            add_error(field, options[:message])
+            false
           end
-        end
+        }.compact.all? { |v| v == true }
+      end
+
+      # Validates the numericality of a specific field.
+      #
+      #     validates_numericality_of :field
+      #
+      def validates_numericality_of(*fields)
+        options = __validates_extract_options(fields, {
+          :message => "is not a number."
+        })
+
+        fields.collect { |field|
+          value = send(field)
+          # Use validates_presence_of if you need it to be set
+          next if value.nil? || value.to_s.empty?
+          if value.is_a?(Numeric) && value.to_s =~ /^\d$/
+            true
+          else
+            add_error(field, options[:message])
+            false
+          end
+        }.compact.all? { |v| v == true }
+      end
+
+      # Validates that a field's value is within a specific range,
+      # array, etc.
+      #
+      #     validates_inclusion_of :foo, :in => [1,2,3]
+      #     validates_inclusion_of :bar, :in => (1..6)
+      #
+      def validates_inclusion_of(*fields)
+        options = __validates_extract_options(fields, {
+          :in => nil,
+          :message => "value %s is not included in the list."
+        })
+
+        fields.collect { |field|
+          value = send(field)
+          # Use validates_presence_of if you need it to be set
+          return if value.nil? || value.to_s.empty?
+          if options[:in] && options[:in].include?(value)
+            true
+          else
+            message = options[:message] % value
+            add_error(field, message)
+            false
+          end
+        }.compact.all? { |v| v == true }
+      end
+
+      # Internal method. Should never be called.
+      def __validates_extract_options(fields, defaults)
+        defaults.merge(fields.last.is_a?(Hash) ? fields.pop : {})
       end
     end
   end

data/lib/virtualbox/abstract_model.rb

@@ -20,7 +20,7 @@ module VirtualBox
     include Relatable
     include Validatable
 
-    class <<self
+    class << self
       # Returns whether or not the class should be reloaded.
       #
       # @return [Boolean]
@@ -237,7 +237,7 @@ module VirtualBox
 
       self.class.attributes.each do |name, options|
         value = read_attribute(name)
-        value = if value.is_a?(AbstractModel) || value.is_a?(COM::AbstractInterface)
+        value = if value.is_a?(AbstractModel) || value.is_a?(COM::AbstractInterface) || value.is_a?(Proxies::Collection)
           "#<#{value.class.name}>"
         else
           value.inspect
@@ -253,4 +253,4 @@ module VirtualBox
       "#<#{self.class} #{values.sort.join(", ")}>".strip
     end
   end
-end
+end

data/lib/virtualbox/appliance.rb

@@ -52,8 +52,11 @@ module VirtualBox
     end
 
     # Adds a VM to the appliance
-    def add_machine(vm)
-      vm.interface.export(interface)
+    def add_machine(vm, options = {})
+      sys_desc = vm.interface.export(interface)
+      options.each do |key, value|
+        sys_desc.add_description(key, value, value)
+      end
     end
   end
 end

data/lib/virtualbox/audio_adapter.rb

@@ -1,11 +1,11 @@
 module VirtualBox
   class AudioAdapter < AbstractModel
     attribute :parent, :readonly => true, :property => false
-    attribute :enabled
+    attribute :enabled, :boolean => true
     attribute :audio_controller
     attribute :audio_driver
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -32,6 +32,14 @@ module VirtualBox
       existing_record!
     end
 
+    def validate
+      super
+
+      validates_inclusion_of :enabled, :in => [true, false]
+      validates_inclusion_of :audio_controller, :in => COM::Util.versioned_interface(:AudioControllerType).map
+      validates_inclusion_of :audio_driver, :in => COM::Util.versioned_interface(:AudioDriverType).map
+    end
+
     def save
       parent.with_open_session do |session|
         machine = session.machine
@@ -41,4 +49,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/bios.rb

@@ -2,10 +2,10 @@ module VirtualBox
   # Represents the BIOS settings of a {VM}.
   class BIOS < AbstractModel
     attribute :parent, :readonly => true, :property => false
-    attribute :acpi_enabled
-    attribute :io_apic_enabled
+    attribute :acpi_enabled, :boolean => true
+    attribute :io_apic_enabled, :boolean => true
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -32,6 +32,12 @@ module VirtualBox
       existing_record!
     end
 
+    def validate
+      super
+
+      validates_inclusion_of :acpi_enabled, :io_apic_enabled, :in => [true, false]
+    end
+
     def save
       parent.with_open_session do |session|
         machine = session.machine
@@ -41,4 +47,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/com/abstract_enum.rb

@@ -5,13 +5,14 @@ module VirtualBox
     class AbstractEnum
       extend Enumerable
 
-      class <<self
+      class << self
         # Defines the mapping of int => symbol for the given Enum.
         # The parameter to this can be an Array or Hash or anything which
         # can be indexed with `[]` and an integer and returns a value of
-        # some sort.
-        def map(value)
-          @map = value
+        # some sort. If value is left nil, it will return the current mapping
+        def map(value = nil)
+          @map = value if value
+          @map
         end
 
         # Returns the symbol associatd with the given key
@@ -39,4 +40,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/com/abstract_implementer.rb

@@ -8,6 +8,7 @@ module VirtualBox
     # Windows (COM) and Unix (XPCOM), which have different calling conventions.
     class AbstractImplementer
       attr_reader :interface
+      attr_reader :lib
 
       # Initializes an implementer for the given {AbstractInterface}. The
       # implementor's other methods, such as {read_property} or
@@ -15,8 +16,9 @@ module VirtualBox
       # the interface.
       #
       # @param [AbstractInterface] interface
-      def initialize(interface)
+      def initialize(interface, lib)
         @interface = interface
+        @lib = lib
       end
 
       # Read a property of the interface.
@@ -40,4 +42,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/com/abstract_interface.rb

@@ -33,8 +33,9 @@ module VirtualBox
     #
     class AbstractInterface
       attr_reader :implementer
+      attr_reader :lib
 
-      class <<self
+      class << self
         # Adds a function to the interface with the given name and function
         # spec. The spec determines the arguments required, the order they
         # are required in, and any out-arguments.
@@ -108,9 +109,10 @@ module VirtualBox
       end
 
       # Initializes the interface with the given implementer
-      def initialize(implementer, *args)
+      def initialize(implementer, lib, *args)
         # Instantiate the implementer and set it
-        @implementer = implementer.new(self, *args)
+        @lib = lib
+        @implementer = implementer.new(self, lib, *args)
       end
 
       # Reads a property with the given name by calling the read_property
@@ -162,4 +164,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/com/base_interface.rb

@@ -0,0 +1,38 @@
+require 'thread'
+
+module VirtualBox
+  module COM
+    class BaseInterface
+      def initialize
+        @task_queue = Queue.new
+
+        @lib_thread = Thread.new(@task_queue) do |queue|
+          while true
+            task, result = queue.pop
+
+            # Run the task, set the return value, and run the waiter
+            # which will simply finish that thread
+            result << task.call
+          end
+        end
+      end
+
+      # This function takes a block and runs it on a thread which is
+      # guaranteed to be the same since the first time this is
+      # called. This is required by the MSCOM implementation and is a
+      # good idea in general so that multiple API calls aren't firing
+      # at once.
+      def on_lib_thread(&task)
+        # If we're already on the lib thread, then just run it!
+        return task.call if Thread.current == @lib_thread
+
+        # Add the task to the queue
+        result = Queue.new
+        @task_queue << [task, result]
+
+        # Pop the result off of the result queue
+        result.pop
+      end
+    end
+  end
+end

data/lib/virtualbox/com/ffi/interface.rb

@@ -8,11 +8,20 @@ module VirtualBox
       # FFI specific types
       NSRESULT_TYPE = :uint
 
+      # Creates all the FFI classes for a given version.
+      def self.for_version(version, &block)
+        @__module = Module.new
+        ::VirtualBox::COM::Util.set_interface_version(version)
+        const_set(::VirtualBox::COM::Util.version_const, @__module)
+        instance_eval(&block)
+        @__module = Kernel
+      end
+
       # Returns a Class which creates an FFI interface to the specified
       # com interface and potentially a parent class as well.
       def self.create_interface(interface, parent=nil)
         klass = Class.new(Interface)
-        const_set(interface, klass)
+        @__module.const_set(interface, klass)
         klass.com_interface(interface, parent)
         klass
       end
@@ -30,7 +39,7 @@ module VirtualBox
         attr_reader :vtbl_parent
         attr_reader :vtbl
 
-        class <<self
+        class << self
           # Sets up the args to the FFI::Struct `layout` method. This
           # method defines all the callbacks necessary for working with
           # FFI and also sets up any layout args to send in. The way the
@@ -39,7 +48,7 @@ module VirtualBox
           # put into the struct in the order defined in the {AbstractInterface}.
           def com_interface(interface, parent=nil)
             # Create the parent class and vtbl class
-            interface = ::VirtualBox::COM::Interface.const_get(interface)
+            interface = ::VirtualBox::COM::Util.versioned_interface(interface)
             define_vtbl_parent_for_interface(interface)
             define_vtbl_for_interface(interface, parent)
           end
@@ -79,7 +88,7 @@ module VirtualBox
           def define_interface_parent(parent)
             return if parent.nil?
 
-            parent_klass = Object.module_eval("::VirtualBox::COM::FFI::#{parent}::Vtbl")
+            parent_klass = Object.module_eval("::VirtualBox::COM::FFI::#{::VirtualBox::COM::Util.version_const}::#{parent}::Vtbl")
             layout_args << [:superklass, parent_klass]
           end
 
@@ -138,4 +147,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/com/ffi/interfaces.rb

@@ -4,39 +4,43 @@ module VirtualBox
       # Creates all the interfaces for the FFI implementation. Eventually this
       # file should be conditionally loaded based on OS, so that Windows users
       # don't have to wait for all this translation to occur.
-      create_interface(:NSISupports)
-      create_interface(:NSIException, :NSISupports)
-      create_interface(:Session, :NSISupports)
-      create_interface(:VirtualBox, :NSISupports)
-      create_interface(:Appliance, :NSISupports)
-      create_interface(:AudioAdapter, :NSISupports)
-      create_interface(:BIOSSettings, :NSISupports)
-      create_interface(:Console, :NSISupports)
-      create_interface(:DHCPServer, :NSISupports)
-      create_interface(:GuestOSType, :NSISupports)
-      create_interface(:Host, :NSISupports)
-      create_interface(:HostNetworkInterface, :NSISupports)
-      create_interface(:Machine, :NSISupports)
-      create_interface(:Medium, :NSISupports)
-      create_interface(:MediumAttachment, :NSISupports)
-      create_interface(:MediumFormat, :NSISupports)
-      create_interface(:NetworkAdapter, :NSISupports)
-      create_interface(:ParallelPort, :NSISupports)
-      create_interface(:Progress, :NSISupports)
-      create_interface(:SerialPort, :NSISupports)
-      create_interface(:SharedFolder, :NSISupports)
-      create_interface(:Snapshot, :NSISupports)
-      create_interface(:StorageController, :NSISupports)
-      create_interface(:SystemProperties, :NSISupports)
-      create_interface(:USBController, :NSISupports)
-      create_interface(:USBDevice, :NSISupports)
-      create_interface(:USBDeviceFilter, :NSISupports)
-      create_interface(:VirtualBoxErrorInfo, :NSIException)
-      create_interface(:VirtualSystemDescription, :NSISupports)
-      create_interface(:VRDPServer, :NSISupports)
+      def self.setup(version)
+        for_version version do
+          create_interface(:NSISupports)
+          create_interface(:NSIException, :NSISupports)
+          create_interface(:Session, :NSISupports)
+          create_interface(:VirtualBox, :NSISupports)
+          create_interface(:Appliance, :NSISupports)
+          create_interface(:AudioAdapter, :NSISupports)
+          create_interface(:BIOSSettings, :NSISupports)
+          create_interface(:Console, :NSISupports)
+          create_interface(:DHCPServer, :NSISupports)
+          create_interface(:GuestOSType, :NSISupports)
+          create_interface(:Host, :NSISupports)
+          create_interface(:HostNetworkInterface, :NSISupports)
+          create_interface(:Machine, :NSISupports)
+          create_interface(:Medium, :NSISupports)
+          create_interface(:MediumAttachment, :NSISupports)
+          create_interface(:MediumFormat, :NSISupports)
+          create_interface(:NetworkAdapter, :NSISupports)
+          create_interface(:ParallelPort, :NSISupports)
+          create_interface(:Progress, :NSISupports)
+          create_interface(:SerialPort, :NSISupports)
+          create_interface(:SharedFolder, :NSISupports)
+          create_interface(:Snapshot, :NSISupports)
+          create_interface(:StorageController, :NSISupports)
+          create_interface(:SystemProperties, :NSISupports)
+          create_interface(:USBController, :NSISupports)
+          create_interface(:USBDevice, :NSISupports)
+          create_interface(:USBDeviceFilter, :NSISupports)
+          create_interface(:VirtualBoxErrorInfo, :NSIException)
+          create_interface(:VirtualSystemDescription, :NSISupports)
+          create_interface(:VRDPServer, :NSISupports)
 
-      create_interface(:HostUSBDevice, :USBDevice)
-      create_interface(:HostUSBDeviceFilter, :USBDeviceFilter)
+          create_interface(:HostUSBDevice, :USBDevice)
+          create_interface(:HostUSBDeviceFilter, :USBDeviceFilter)
+        end
+      end
     end
   end
 end

data/lib/virtualbox/com/ffi/util.rb

@@ -5,7 +5,22 @@ module VirtualBox
       # with the FFI interface. These functions range from converting a
       # function spec to a FFI parameter list to dereferencing pointers.
       class Util
-        class <<self
+        class << self
+          # Finds and returns the `COM::Interface` class associated with the type.
+          # If the class does not exist, a `NameError` will be raised.
+          #
+          # @return [Class]
+          def interface_klass(type)
+            ::VirtualBox::COM::Util.versioned_interface(type)
+          end
+
+          # Finds the versioned interface for the FFI module.
+          #
+          # @return [Class]
+          def versioned_interface(interface)
+            ::VirtualBox::COM::FFI.const_get(::VirtualBox::COM::Util.version_const).const_get(interface)
+          end
+
           # Converts a function spec from {AbstractInterface} to an FFI
           # function spec. This handles custom types (unicode strings,
           # arrays, and out-parameters) and will return a perfectly valid
@@ -33,7 +48,7 @@ module VirtualBox
               elsif item.to_s[0,1] == item.to_s[0,1].upcase
                 begin
                   # Try to get the class from the interfaces
-                  interface = COM::Interface.const_get(item.to_sym)
+                  interface = interface_klass(item.to_sym)
 
                   if interface.superclass == COM::AbstractInterface
                     :pointer
@@ -85,7 +100,10 @@ module VirtualBox
               "vdi" => "VDI",
               "cpu" => "CPU",
               "ram" => "RAM",
-              "hdd" => "HDD"
+              "hdd" => "HDD",
+              "rtc" => "RTC",
+              "utc" => "UTC",
+              "io" => "IO"
             }
 
             parts = string.to_s.split(/_/).collect do |part|
@@ -98,4 +116,4 @@ module VirtualBox
       end
     end
   end
-end
+end