vixen 0.0.7 → 0.0.8

data/README.md

@@ -123,6 +123,8 @@ Vixen::Model::VM
 
  * `current_snapshot`
  * `create_snapshot`
+ * `revert_to_snapshot`
+ * `remove_snapshot`
  * Power Operations
    * `power_on`
    * `power_off`
@@ -145,7 +147,74 @@ Vixen::Model::Snapshot
  * `parent` - the parent snapshot, if any
  * `full_name` - the full name of the snapshot (traverses parent hierarchy)
 
+Progress Callbacks
+==================
+
+The VIX API allows for progress callbacks which Vixen exposes through the use
+of blocks passed to the method.
+
+```ruby
+require 'rubygems'
+require 'vixen'
+
+#Vixen.logger.level = Logger::DEBUG
+start = Time.now
+
+def elapsed_time(start)
+  "[%s]" % (Time.at(Time.now - start).utc.strftime '%T')
+end
+
+host = Vixen.local_connect
+
+vm = host.open_vm '/Users/jeff/Desktop/centos-5.8-pe-2.5.3-vmware/centos-5.8-pe-2.5.3-vmware.vmx' do |*args|
+  print "\r#{elapsed_time(start)} waiting for my vm to open"
+  $stdout.flush
+end
+
+vm.resume do |*args|
+  print "\r#{elapsed_time(start)} resuming..."
+  $stdout.flush
+end
+puts
+
+previous_snapshot = vm.current_snapshot
+
+puts "#{elapsed_time(start)} previous_snapshot: #{previous_snapshot}"
+
+snapshot_name = "vixen-created #{Time.now}"
+new_snapshot = vm.create_snapshot snapshot_name do |*args|
+  print "\r#{elapsed_time(start)} creating snapshot: #{snapshot_name}"
+  $stdout.flush
+end
+puts
+
+vm.revert_to_snapshot previous_snapshot do |*args|
+  print "\r#{elapsed_time(start)} reverting to #{previous_snapshot}..."
+  $stdout.flush
+end
+puts
+
+vm.suspend do |*args|
+  print "\r#{elapsed_time(start)} suspending..."
+  $stdout.flush
+end
+puts
+```
+
+produces output like
+
+```shell
+$ ruby vixen-example.rb          
+[00:00:00] waiting for my vm to open
+[00:00:02] resuming...
+[00:00:02] previous_snapshot: vixen-created
+[00:02:18] creating snapshot: vixen-created Tue Nov 20 02:18:04 -0800 2012
+[00:02:33] reverting to vixen-created...
+[00:02:36] reverting to vixen-created...
+[00:02:38] suspending...
+```
+
 See Also
---------
+========
 
  * [Official VMware VIX 1.12 documentation](http://www.vmware.com/support/developer/vix-api/vix112_reference/)

data/lib/vixen.rb

@@ -4,12 +4,12 @@ module Vixen
 
   @@logger = nil
 
-  def self.local_connect(login = nil, password = nil)
-    connect Vixen::Constants::VixServiceProvider[:vmware_workstation], nil, 0, login, password
+  def self.local_connect(login = nil, password = nil, &block)
+    connect Vixen::Constants::VixServiceProvider[:vmware_workstation], nil, 0, login, password, &block
   end
 
-  def self.connect(host_type, hostname, port, username, password)
-    handle = Vixen::Bridge.connect(host_type, hostname, port, username, password)
+  def self.connect(host_type, hostname, port, username, password, &block)
+    handle = Vixen::Bridge.connect(host_type, hostname, port, username, password, &block)
     Vixen::Model::Host.new(handle)
   end
 

data/lib/vixen/bridge.rb

@@ -42,11 +42,30 @@ module Vixen::Bridge
   attach_function :VixVM_GetCurrentSnapshot, [:handle, :pointer], :int
   attach_function :VixSnapshot_GetParent, [:handle, :pointer], :int
   attach_function :VixVM_PowerOn, [:handle, :int, :handle, :VixEventProc, :pointer], :handle
+  attach_function :VixVM_PowerOff, [:handle, :int, :VixEventProc, :pointer], :handle
+  attach_function :VixVM_Reset, [:handle, :int, :VixEventProc, :pointer], :handle
+  attach_function :VixVM_Suspend, [:handle, :int, :VixEventProc, :pointer], :handle
   attach_function :VixVM_CreateSnapshot, [:handle, :string, :string, :int, :handle, :VixEventProc, :pointer], :handle
+  attach_function :VixVM_RevertToSnapshot, [:handle, :handle, :int, :handle, :VixEventProc, :pointer], :handle
+  attach_function :VixVM_RemoveSnapshot, [:handle, :handle, :int, :VixEventProc, :pointer], :handle
   attach_function :VixJob_CheckCompletion, [:handle, :pointer], :int
   attach_function :Vix_GetHandleType, [:handle], :int
 
-  def self.connect(hostType, hostname, port, username, password)
+  @@all_my_blocks = []
+
+  def self.safe_proc_from_block(&block)
+    return nil unless block_given?
+    Proc.new do |*args|
+      begin
+        block.call args
+      rescue
+        puts STDERR, $!
+      end
+    end
+  end
+
+  def self.connect(hostType, hostname, port, username, password, &block)
+    progress_proc = safe_proc_from_block &block
     hostname = "https://%s%s/sdk" % [hostname, port == 0 ? '' : ":#{port}"] if hostname
     Vixen.logger.info "connecting to %s with username %s" % [hostname.inspect, username.inspect]
     job = Vixen::Model::Job.new(VixHost_Connect(VixApiVersion[:api_version],
@@ -57,10 +76,11 @@ module Vixen::Bridge
                                  password,
                                  0,
                                  VixHandle[:invalid],
-                                 nil,
+                                 progress_proc,
                                  nil))
+    spin_until_job_complete("connect to host", job)
     pointer_to_handle do |host_handle_pointer|
-      Vixen.logger.debug "waiting for connection to complete"
+      Vixen.logger.debug "getting handle from connection job"
       VixJob_Wait job.handle, VixPropertyId[:job_result_handle],
                   :pointer, host_handle_pointer,
                   :int, VixPropertyId[:none]
@@ -93,10 +113,11 @@ module Vixen::Bridge
     (pointer_to :int, &block) != 0
   end
 
-  def self.wait_for_async_job(operation, &block)
+  def self.wait_for_async_job(operation, initial_sleep_time = 0.1, sleep_increment = 0.02, &block)
     job = Vixen::Model::Job.new(yield)
     Vixen.logger.debug "Waiting for async %s job (%s)" %
       [operation, job.handle]
+    spin_until_job_complete(operation, job, initial_sleep_time, sleep_increment)
     err = VixJob_Wait job.handle, VixPropertyId[:none]
     unless err == VixError[:ok]
       Vixen.logger.error "While executing %s VIX API returned error: %s: %s" %
@@ -106,10 +127,11 @@ module Vixen::Bridge
     end
   end
 
-  def self.wait_for_async_handle_creation_job(operation, pointer_to_handle, &block)
+  def self.wait_for_async_handle_creation_job(operation, pointer_to_handle, initial_sleep_time = 0.1, sleep_increment = 0.02, &block)
     job = Vixen::Model::Job.new(yield)
     Vixen.logger.debug "Waiting for async %s job (%s) to create a new handle" %
       [operation, job.handle]
+    spin_until_job_complete(operation, job, initial_sleep_time, sleep_increment)
     err = VixJob_Wait job.handle, VixPropertyId[:job_result_handle],
                 :pointer, pointer_to_handle,
                 :int, VixPropertyId[:none]
@@ -122,15 +144,20 @@ module Vixen::Bridge
     err
   end
 
-  def self.spin_until_job_complete(operation, job)
+  def self.spin_until_job_complete(operation, job, initial_sleep_time = 0.1, sleep_increment = 0.02)
+    sleep_time = initial_sleep_time
     while ( not pointer_to_bool do |bool_pointer|
       Vixen.logger.debug "sleeping waiting for %s job (%s) to complete" %
         [operation, job.handle]
-      sleep 0.01
+      sleep sleep_time
+      sleep_time += sleep_increment
       Vixen.logger.debug "checking completion of %s job (%s)" %
         [operation, job.handle]
-      thr = Thread.start { VixJob_CheckCompletion(job.handle, bool_pointer) }
-      thr.value
+      thr = Thread.start { sleep 0.01; VixJob_CheckCompletion(job.handle, bool_pointer) }
+      Vixen.logger.debug "waiting for thread to complete"
+      x = thr.value
+      Vixen.logger.debug "thread completed with #{x}"
+      x
     end) do
     end
   end
@@ -138,7 +165,7 @@ module Vixen::Bridge
   def self.running_vms(host_handle, &block)
     available_vms = []
 
-    collect_proc = Proc.new do |job_handle, event_type, more_event_info, client_data|
+    collect_proc = safe_proc_from_block do |job_handle, event_type, more_event_info, client_data|
       if event_type == VixEventType[:find_item]
         path = get_string_property more_event_info, VixPropertyId[:found_item_location]
         if path
@@ -176,27 +203,44 @@ module Vixen::Bridge
     Vix_ReleaseHandle handle
   end
 
-  def self.open_vm(host_handle, vm_path)
+  def self.open_vm(host_handle, vm_path, &block)
+    progress_proc = safe_proc_from_block &block
     vm_handle = pointer_to_handle do |vm_handle_pointer|
       wait_for_async_handle_creation_job "open vm", vm_handle_pointer do
         Vixen.logger.info "opening %s" % vm_path
         VixHost_OpenVM host_handle, vm_path, VixVMOpenOptions[:normal],
-                       VixHandle[:invalid], nil, nil
+                       VixHandle[:invalid], progress_proc, nil
       end
     end
   end
 
-  def self.create_snapshot(vm_handle, name, description)
+  def self.create_snapshot(vm_handle, name, description, &block)
+    progress_proc = safe_proc_from_block &block
     snapshot_handle = pointer_to_handle do |snapshot_handle_pointer|
-      wait_for_async_handle_creation_job "create snapshot", snapshot_handle_pointer do
+      wait_for_async_handle_creation_job "create snapshot", snapshot_handle_pointer, 1, 0.2 do
         Vixen.logger.info "creating %s snapshot" % name
         VixVM_CreateSnapshot vm_handle, name, description,
                              VixCreateSnapshotOptions[:include_memory],
-                             VixHandle[:invalid], nil, nil
+                             VixHandle[:invalid], progress_proc, nil
       end
     end
   end
 
+  def self.revert_to_snapshot(vm, snapshot, &block)
+    progress_proc = safe_proc_from_block &block
+    wait_for_async_job(("revert to %s snapshot" % snapshot.display_name), 1, 0.2) do
+      VixVM_RevertToSnapshot vm.handle, snapshot.handle, VixVMPowerOptions[:normal],
+                             VixHandle[:invalid], progress_proc, nil
+    end
+  end
+
+  def self.remove_snapshot(vm, snapshot, &block)
+    progress_proc = safe_proc_from_block &block
+    wait_for_async_job(("remove %s snapshot" % snapshot.display_name), 1, 0.2) do
+      VixVM_RemoveSnapshot vm.handle, snapshot.handle, 0, progress_proc, nil
+    end
+  end
+
   def self.current_snapshot(vm_handle)
     pointer_to_handle do |snapshot_handle_pointer|
       Vixen.logger.debug "retrieving current snapshot"
@@ -218,7 +262,7 @@ module Vixen::Bridge
                         :pointer, string_pointer,
                         :int, VixPropertyId[:none])
     end
-    value = string.read_string.force_encoding("UTF-8").dup
+    value = string.read_string.dup
     Vix_FreeBuffer(string)
     return value
   end
@@ -232,31 +276,61 @@ module Vixen::Bridge
     end
   end
 
-  def self.power_on(vm_handle)
+  def self.power_on(vm_handle, &block)
+    progress_proc = safe_proc_from_block &block
     wait_for_async_job "power on VM" do
       Vixen.logger.debug "powering on vm (%s)" % vm_handle
-      VixVM_PowerOn vm_handle, VixVMPowerOptions[:normal], VixHandle[:invalid], nil, nil
+      VixVM_PowerOn vm_handle, VixVMPowerOptions[:normal], VixHandle[:invalid], progress_proc, nil
+    end
+  end
+
+  def self.power_off_using_guest(vm_handle, &block)
+    begin
+      progress_proc = safe_proc_from_block &block
+      wait_for_async_job "power off VM using tools" do
+        Vixen.logger.debug "powering off vm (%s)" % vm_handle
+        VixVM_PowerOff vm_handle, VixVMPowerOptions[:from_guest], progress_proc, nil
+      end
+      true
+    rescue
+      false
     end
   end
 
-  def self.power_off(vm_handle)
+  def self.power_off(vm_handle, &block)
+    progress_proc = safe_proc_from_block &block
     wait_for_async_job "power off VM" do
       Vixen.logger.debug "powering off vm (%s)" % vm_handle
-      VixVM_PowerOff vm_handle, VixVMPowerOptions[:normal], nil, nil
+      VixVM_PowerOff vm_handle, VixVMPowerOptions[:normal], progress_proc, nil
+    end
+  end
+
+  def self.reset_using_guest(vm_handle, &block)
+    begin
+      progress_proc = safe_proc_from_block &block
+      wait_for_async_job "reset VM using tools" do
+        Vixen.logger.debug "resetting vm (%s)" % vm_handle
+        VixVM_Reset vm_handle, VixVMPowerOptions[:from_guest], progress_proc, nil
+      end
+      true
+    rescue
+      false
     end
   end
 
-  def self.reset(vm_handle)
+  def self.reset(vm_handle, &block)
+    progress_proc = safe_proc_from_block &block
     wait_for_async_job "reset VM" do
       Vixen.logger.debug "resetting vm (%s)" % vm_handle
-      VixVM_Reset vm_handle, VixVMPowerOptions[:normal], nil, nil
+      VixVM_Reset vm_handle, VixVMPowerOptions[:normal], progress_proc, nil
     end
   end
 
-  def self.suspend(vm_handle)
+  def self.suspend(vm_handle, &block)
+    progress_proc = safe_proc_from_block &block
     wait_for_async_job "suspend VM" do
       Vixen.logger.debug "suspending vm (%s)" % vm_handle
-      VixVM_Suspend vm_handle, VixVMPowerOptions[:normal], nil, nil
+      VixVM_Suspend vm_handle, VixVMPowerOptions[:normal], progress_proc, nil
     end
   end
 

data/lib/vixen/model/vm.rb

@@ -7,32 +7,56 @@ class Vixen::Model::VM < Vixen::Model::Base
     Vixen::Model::Snapshot.new(Vixen::Bridge.current_snapshot(handle))
   end
 
-  def create_snapshot(name, description)
-    Vixen::Model::Snapshot.new(Vixen::Bridge.create_snapshot handle, name, description)
+  def create_snapshot(name, description="", &block)
+    Vixen::Model::Snapshot.new(Vixen::Bridge.create_snapshot handle, name, description, &block)
   end
 
-  def power_on
+  def revert_to_snapshot(snapshot, &block)
+    Vixen::Bridge.revert_to_snapshot self, snapshot, &block
+  end
+
+  def remove_snapshot(snapshot, &block)
+    Vixen::Bridge.remove_snaphost self, snapshot, &block
+  end
+
+  def power_on(&block)
     return self if powered_on? or powering_on? or resuming? or resetting?
-    Vixen::Bridge.power_on handle
+    Vixen::Bridge.power_on handle, &block
     self
   end
 
-  def resume
-    power_on
+  def resume(&block)
+    power_on &block
   end
 
-  def suspend
-    Vixen::Bridge.suspend handle
+  def suspend(&block)
+    Vixen::Bridge.suspend handle, &block
     self
   end
 
-  def power_off
-    Vixen::Bridge.power_off handle
+  def power_off(opts={}, &block)
+    hard_power_off = opts[:hard] || :if_necessary
+    case hard_power_off
+    when :if_necessary
+      Vixen::Bridge.power_off_using_guest(handle, &block) || Vixen::Bridge.power_off(handle, &block)
+    when :always
+      Vixen::Bridge.power_off(handle, &block)
+    else
+      Vixen::Bridge.power_off_using_guest(handle, &block)
+    end
     self
   end
 
-  def reset
-    Vixen::Bridge.reset handle
+  def reset(opts={}, &block)
+    hard_reset = opts[:hard] || :if_necessary
+    case hard_reset
+    when :if_necessary
+      Vixen::Bridge.reset_using_guest(handle, &block) || Vixen::Bridge.reset(handle, &block)
+    when :always
+      Vixen::Bridge.reset(handle, &block)
+    else
+      Vixen::Bridge.reset_using_guest(handle, &block)
+    end
     self
   end
 

data/vixen-example.rb

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'vixen'
+
+#Vixen.logger.level = Logger::DEBUG
+start = Time.now
+
+def elapsed_time(start)
+  "[%s]" % (Time.at(Time.now - start).utc.strftime '%T')
+end
+
+host = Vixen.local_connect
+
+vm = host.open_vm '/Users/jeff/Desktop/centos-5.8-pe-2.5.3-vmware/centos-5.8-pe-2.5.3-vmware.vmx' do |*args|
+  print "\r#{elapsed_time(start)} waiting for my vm to open"
+  $stdout.flush
+end
+
+vm.resume do |*args|
+  print "\r#{elapsed_time(start)} resuming..."
+  $stdout.flush
+end
+puts
+
+previous_snapshot = vm.current_snapshot
+
+puts "#{elapsed_time(start)} previous_snapshot: #{previous_snapshot}"
+
+snapshot_name = "vixen-created #{Time.now}"
+new_snapshot = vm.create_snapshot snapshot_name do |*args|
+  print "\r#{elapsed_time(start)} creating snapshot: #{snapshot_name}"
+  $stdout.flush
+end
+puts
+
+vm.revert_to_snapshot previous_snapshot do |*args|
+  print "\r#{elapsed_time(start)} reverting to #{previous_snapshot}..."
+  $stdout.flush
+end
+puts
+
+vm.remove_snapshot new_snapshot do |*args|
+  print "\r#{elapsed_time(start)} deleting snapshot: #{new_snapshot}"
+  $stdout.flush
+end
+
+vm.suspend do |*args|
+  print "\r#{elapsed_time(start)} suspending..."
+  $stdout.flush
+end
+puts
+

data/vixen.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'vixen'
-  s.version = '0.0.7'
+  s.version = '0.0.8'
   s.summary = 'Ruby bindings for VMware VIX API'
   s.description = <<-EOF
   Vixen is an easy way to interact with VMware virtual machines from Ruby. 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vixen
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -66,6 +66,7 @@ files:
 - lib/vixen/model/job.rb
 - lib/vixen/model/snapshot.rb
 - lib/vixen/model/vm.rb
+- vixen-example.rb
 - vixen.gemspec
 homepage: https://github.com/jeffweiss/vixen
 licenses: