velir_virtualbox 0.8.4

data/lib/virtualbox/ext/byte_normalizer.rb

@@ -0,0 +1,17 @@
+module VirtualBox::ByteNormalizer
+  # So that this is only defined once (suppress warnings)
+  if !defined?(THOUSAND)
+    THOUSAND = 1024.0
+    BYTE = 1.0
+    KILOBYTE = BYTE * THOUSAND
+    MEGABYTE = KILOBYTE * THOUSAND
+  end
+
+  def bytes_to_megabytes(b)
+    b / MEGABYTE
+  end
+
+  def megabytes_to_bytes(mb)
+    mb * MEGABYTE
+  end
+end

data/lib/virtualbox/ext/glob_loader.rb

@@ -0,0 +1,35 @@
+require 'virtualbox/ext/platform'
+
+module VirtualBox
+  # Eases the processes of loading specific files then globbing
+  # the rest from a specified directory.
+  module GlobLoader
+    # Glob requires all ruby files in a directory, optionally loading select
+    # files initially (since others may depend on them).
+    #
+    # @param [String] dir The directory to glob
+    # @param [Array<String>] initial_files Initial files (relative to `dir`)
+    #   to load
+    def self.glob_require(dir, initial_files=[])
+      # Note: The paths below both are "downcased" because on Windows, some
+      # expand to "c:\" and some expand to "C:\" and cause the same file to
+      # be loaded twice. Uck.
+
+      require_files = []
+      initial_files.each do |file|
+        require_files << File.expand_path(file, dir)
+      end
+
+      # Glob require the rest
+      Dir[File.join(dir, "**", "*.rb")].each do |f|
+        require_files << File.expand_path(f)
+      end
+
+      # Iterate over the files to require, manipulating them if necessary
+      require_files.each do |file|
+        file = file.downcase if Platform.windows?
+        require file
+      end
+    end
+  end
+end

data/lib/virtualbox/ext/logger.rb

@@ -0,0 +1,38 @@
+require 'logger'
+
+module VirtualBox
+  # Provides logger functionality for VirtualBox. This class is available on most
+  # VirtualBox classes through mixins. To access the logger, simply call the {logger}
+  # method. This returns a standard Ruby logger which can be modified.
+  module Logger
+    @@logger = nil
+    @@logger_output = nil
+
+    # Make the logger available both on a class and instance level
+    # once included.
+    def self.included(base)
+      base.extend self
+    end
+
+    # Sets up the output stream for the logger. This should be called before any
+    # calls to {logger}. If the logger has already been instantiated, then a new
+    # logger will be created on the next call with the new output setup.
+    def logger_output=(value)
+      @@logger_output = value
+      @@logger = nil
+    end
+
+    # Accesses the logger. If logger output is specified and this is the first load,
+    # then the logger will be properly setup to point to that output. Logging
+    # levels should also be set once the logger is created. The logger is a standard
+    # Ruby `Logger`.
+    #
+    # The VirtualBox gem can get very verybose very quickly, so choose a log level
+    # which suits the granularity needed.
+    #
+    # @return [Logger]
+    def logger
+      @@logger ||= ::Logger.new(@@logger_output)
+    end
+  end
+end

data/lib/virtualbox/ext/platform.rb

@@ -0,0 +1,31 @@
+require "rbconfig"
+
+module VirtualBox
+  class Platform
+    class << self
+      def mac?
+        platform.include?("darwin")
+      end
+
+      def windows?
+        platform.include?("mswin") || platform.include?("mingw") || platform.include?("cygwin")
+      end
+
+      def linux?
+        platform.include?("linux")
+      end
+
+      def solaris?
+        platform.include?("solaris")
+      end
+
+      def jruby?
+        RbConfig::CONFIG["ruby_install_name"] == "jruby"
+      end
+
+      def platform
+        RbConfig::CONFIG["host_os"].downcase
+      end
+    end
+  end
+end

data/lib/virtualbox/ext/subclass_listing.rb

@@ -0,0 +1,24 @@
+# From: http://snippets.dzone.com/posts/show/2992
+module VirtualBox::SubclassListing
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def subclasses(direct = false)
+      classes = []
+      if direct
+        ObjectSpace.each_object(Class) do |c|
+          next unless c.superclass == self
+          classes << c
+        end
+      else
+        ObjectSpace.each_object(Class) do |c|
+          next unless c.ancestors.include?(self) and (c != self)
+          classes << c
+        end
+      end
+      classes
+    end
+  end
+end

data/lib/virtualbox/extra_data.rb

@@ -0,0 +1,127 @@
+module VirtualBox
+  # Represents "extra data" which can be set on a specific
+  # virtual machine or on VirtualBox as a whole. Extra data is persistent
+  # key-value storage which is available as a way to store any information
+  # wanted. VirtualBox uses it for storing statistics and settings. You can
+  # use it for anything!
+  #
+  # # Extra Data on a Virtual Machine
+  #
+  # Setting extra data on a virtual machine is easy. All {VM} objects have a
+  # `extra_data` relationship which is just a simple ruby hash, so you can treat
+  # it like one! Once the data is set, simply saving the VM will save the
+  # extra data. An example below:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     vm.extra_data["ruby-accessed"]  = "yes, yes it was"
+  #     vm.save
+  #
+  # Now, let's say you open up the VM again some other time:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     puts vm.extra_data["ruby-accessed"]
+  #
+  # It acts just like a hash!
+  #
+  # # Global Extra Data
+  #
+  # Extra data doesn't need to be tied to a specific virtual machine. It can also
+  # exist globally. Setting global extra-data is just as easy:
+  #
+  #     VirtualBox::ExtraData.global["some-key"] = "some value"
+  #     VirtualBox::ExtraData.global.save
+  #
+  class ExtraData < Hash
+    include AbstractModel::Dirty
+
+    attr_accessor :parent
+    attr_reader :interface
+
+    @@global_data = nil
+
+    class << self
+      # Gets the global extra data. This will "cache" the data for
+      # future use unless you set the `reload` paramter to true.
+      #
+      # @param [Boolean] reload If true, will reload new global data.
+      # @return [Array<ExtraData>]
+      def global(reload=false)
+        if !@@global_data || reload
+          @@global_data = Global.global.extra_data
+        end
+
+        @@global_data
+      end
+
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<ExtraData>]
+      def populate_relationship(caller, interface)
+        data = new(caller, interface)
+
+        interface.get_extra_data_keys.each do |key|
+          data[key] = interface.get_extra_data(key)
+        end
+
+        data.clear_dirty!
+        data
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.save
+      end
+    end
+
+    # Initializes an extra data object.
+    #
+    # @param [Hash] data Initial attributes to populate.
+    def initialize(parent, interface)
+      @parent = parent
+      @interface = interface
+    end
+
+    # Set an extradata key-value pair. Overrides ruby hash implementation
+    # to set dirty state. Otherwise that, behaves the same way.
+    def []=(key,value)
+      set_dirty!(key, self[key], value)
+      super
+    end
+
+    # Saves extra data. This method does the same thing for both new
+    # and existing extra data, since virtualbox will overwrite old data or
+    # create it if it doesn't exist.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      changes.each do |key, value|
+        interface.set_extra_data(key.to_s, value[1].to_s)
+
+        clear_dirty!(key)
+
+        if value[1].nil?
+          # Remove the key from the hash altogether
+          hash_delete(key.to_s)
+        end
+      end
+    end
+
+    # Alias away the old delete method so its still accessible somehow
+    alias :hash_delete :delete
+
+    # Deletes the specified extra data.
+    #
+    # @param [String] key The extra data key to delete
+    def delete(key)
+      interface.set_extra_data(key.to_s, nil)
+      hash_delete(key.to_s)
+    end
+  end
+end

data/lib/virtualbox/forwarded_port.rb

@@ -0,0 +1,222 @@
+module VirtualBox
+  # When a VM uses NAT as its NIC type, VirtualBox acts like its
+  # own private router for all virtual machines. Because of this,
+  # the host machine can't access services within the guest machine.
+  # To get around this, NAT supports port forwarding, which allows the
+  # guest machine services to be forwarded to some port on the host
+  # machine. Port forwarding is done completely through {ExtraData}, but
+  # is a complicated enough procedure that this class was made to
+  # faciliate it.
+  #
+  # **Note:** After changing any forwarded ports, the entire VirtualBox
+  # process must be restarted completely for them to take effect. When
+  # working with the ruby library, this isn't so much of an issue, but
+  # if you have any VMs running, they must all be shut down and restarted.
+  #
+  # # Adding a new Forwarded Port
+  #
+  # Since forwarded ports rely on being part of a {VM}, we're going to
+  # assume that `vm` points to a {VM} which has already been found.
+  #
+  #     port = VirtualBox::ForwardedPort.new
+  #     port.name = "apache" # This can be anything
+  #     port.guestport = 80
+  #     port.hostport = 8080
+  #     vm.forwarded_ports << port
+  #     port.save # Or vm.save
+  #
+  # # Modifying an Existing Forwarded Port
+  #
+  # This is assuming that `vm` is a local variable storing a {VM} object
+  # which has already been found.
+  #
+  #     vm.forwarded_ports.first.hostport = 1919
+  #     vm.save
+  #
+  # # Deleting a Forwarded Port
+  #
+  # To delete a forwarded port, you simply destroy it like any other model:
+  #
+  #     vm.forwarded_ports.first.destroy
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the model are exposed using standard ruby instance
+  # methods which are generated on the fly. Because of this, they are not listed
+  # below as available instance methods.
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below.
+  #
+  # Relationships are also accessed like attributes but can't be set. Instead,
+  # they are typically references to other objects such as an {AttachedDevice} which
+  # in turn have their own attributes which can be modified.
+  #
+  # ## Attributes
+  #
+  # This is copied directly from the class header, but lists all available
+  # attributes. If you don't understand what this means, read {Attributable}.
+  #
+  #     attribute :parent, :readonly => true
+  #     attribute :name
+  #     attribute :instance, :default => "0"
+  #     attribute :device, :default => "pcnet"
+  #     attribute :protocol, :default => "TCP"
+  #     attribute :guestport
+  #     attribute :hostport
+  #
+  class ForwardedPort < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :name
+    attribute :instance, :default => "0"
+    attribute :device, :default => "pcnet"
+    attribute :protocol, :default => "TCP"
+    attribute :guestport
+    attribute :hostport
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<ForwardedPort>]
+      def populate_relationship(caller, data)
+        relation = Proxies::Collection.new(caller)
+
+        caller.extra_data.each do |key, value|
+          next unless key =~ /^(VBoxInternal\/Devices\/(.+?)\/(.+?)\/LUN#0\/Config\/(.+?)\/)Protocol$/i
+
+          port = new({
+            :parent => caller,
+            :parent_collection => relation,
+            :name => $4.to_s,
+            :instance => $3.to_s,
+            :device => $2.to_s,
+            :protocol => value,
+            :guestport => caller.extra_data["#{$1.to_s}GuestPort"],
+            :hostport => caller.extra_data["#{$1.to_s}HostPort"]
+          })
+
+          port.existing_record!
+
+          relation.push(port)
+        end
+
+        relation
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.dup.each do |fp|
+          fp.save
+        end
+      end
+    end
+
+    # @param [Hash] data The initial attributes to populate.
+    def initialize(data={})
+      super()
+      populate_attributes(data) if !data.empty?
+    end
+
+    # Validates a forwarded port.
+    def validate
+      super
+
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :guestport
+      validates_presence_of :hostport
+    end
+
+    # Retrieves the device for the forwarded port. This tries to "do the
+    # right thing" depending on the first NIC of the VM parent by either
+    # setting the forwarded port type to "pcnet" or "e1000." If the device
+    # was already set manually, this method will simply return that value
+    # instead.
+    #
+    # @return [String] Device type for the forwarded port
+    def device
+      # Return the current or default value if it is:
+      #  * an existing record, since it was already mucked with, no need to
+      #    modify it again
+      #  * device setting changed, since we should return what the user set
+      #    it to
+      #  * If the parent is nil, since we can't infer the type without a parent
+      return read_attribute(:device) if !new_record? || device_changed? || parent.nil?
+
+      device_map = {
+        :Am79C970A => "pcnet",
+        :Am79C973 => "pcnet",
+        :I82540EM => "e1000",
+        :I82543GC => "e1000",
+        :I82545EM => "e1000"
+      }
+
+      return device_map[parent.network_adapters[0].adapter_type]
+    end
+
+    # Saves the forwarded port.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      destroy if !new_record? && name_changed?
+
+      parent.extra_data["#{key_prefix}Protocol"] = protocol
+      parent.extra_data["#{key_prefix}GuestPort"] = guestport
+      parent.extra_data["#{key_prefix}HostPort"] = hostport
+      result = parent.extra_data.save
+
+      clear_dirty!
+      existing_record!
+
+      result
+    end
+
+    # Destroys the port forwarding mapping.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy
+      results = []
+
+      if !new_record?
+        results << parent.extra_data.delete("#{key_prefix(true)}Protocol")
+        results << parent.extra_data.delete("#{key_prefix(true)}GuestPort")
+        results << parent.extra_data.delete("#{key_prefix(true)}HostPort")
+
+        # Remove it from any collection
+        parent_collection.delete(self, true) if parent_collection
+
+        new_record!
+      end
+
+      results.empty? || results.all? { |o| o == true }
+    end
+
+    # Relationship callback when added to a collection. This is automatically
+    # called by any relationship collection when this object is added.
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+    end
+
+    # Returns the prefix to be used for the extra data key. Forwarded ports
+    # are created by simply setting {ExtraData} on a {VM}. This class hides most
+    # of the inner workings of it, but it requires a common prefix. This method
+    # generates that.
+    #
+    # @return [String]
+    def key_prefix(old_name=false)
+      name_value = old_name && name_changed? ? name_was : name
+      "VBoxInternal\/Devices\/#{device}\/#{instance}\/LUN#0\/Config\/#{name_value}\/"
+    end
+  end
+end