vixen 0.0.5 → 0.0.6

data/README.md

@@ -5,33 +5,145 @@ Getting Vixen
 $ gem install vixen
 ```
 
+Capabilities
+------------
+
+ * View running VMs
+ * Control power state (on, off, suspend, reset) of VMs
+ * Viewing the current snapshot
+ * Creating snapshots
+
+Limitations
+-----------
+Vixen currently only supports running on Mac OS X or Linux.
+
+Windows support will require two libraries; one each from the 32-bit and 64-bit
+versions of the Windows VMware VIX SDK. These will need to be placed into 
+`ext/windows/i386` and `ext/windows/x86_64` respectively, and `Vixen::Bridge`
+will use [Facter](https://github.com/puppetlabs/facter) to determine which
+operating system and architecture version of the library to load.
+
+
 Using Vixen
 ===========
 
+
+Connecting to a host
+--------------------
+
+If using Vixen on the same machine as the virtual machine host, you can simply
+use `Vixen.local_connect`
+
+```ruby
+require 'vixen'
+
+host = Vixen.local_connect
+```
+
+If using Vixen to connect to a remote host (VMware Server, ESXi, vSphere, etc),
+use `Vixen.connect`
+
 ```ruby
 require 'vixen'
 
-Vixen.local_connect.running_vms.each { |vm| puts "Current Snapshot: #{vm.current_snapshot}" }
+server_type = Vixen::Constants::VixServiceProvider[:vmware_vi_server]
+host = Vixen.connect server_type, <hostname>, <port>, <username>, <password>
 ```
 
+Both of these will return a `Vixen::Model::Host` object.
+
+Vixen::Model::Host
+==================
+
+`Host` currently supports the following actions:
+
+ * `open_vm`
+ * `running_vms`
+ * `paths_of_running_vms`
+
+Currently running virtual machines
+----------------------------------
+
+```ruby
+require 'vixen'
+
+host = Vixen.local_connect
+machines = host.running_vms
+
+machines.each do |vm|
+  puts "Current Snapshot: #{vm.current_snapshot}"
+end
+```
+
+Opening a virtual machine
+-------------------------
+
+Opening a virtual machine does not _start_ the virtual machine, but creates
+an object that you can use to interrogate properties of the virtual machine.
+The virtual machine _could_ be started by using this object, (see 
+`Vixen::Model::VM#power_on`).
+
 Vixen can also be used on virtual machines that are not currently active:
 
 ```ruby
 require 'vixen'
+
+host = Vixen.local_connect
+
 path = '/Users/jeff/Documents/Virtual Machines/win2003sat.vmwarevm/Windows Server 2003 Enterprise x64 Edition.vmx'
-puts Vixen.local_connect.open_vm(path).power_on.current_snapshot.full_name
+
+vm = host.open_vm path
+
+puts vm.current_snapshot
 ```
 
-Capabilities
-------------
+Paths of running virtual machines
+---------------------------------
 
- * View running VMs
- * Control power state (on, off, suspend, reset) of VMs
- * Viewing the current snapshot
+If all you are interested is the path (of the `.vmx` file) of the running
+virtual machines, you may use `paths_of_running_vms`, which is much lighter
+weight than `running_vms`.
 
-Limitations
------------
-Vixen currently only supports running on Mac OS X or Linux.
+```ruby
+require 'vixen'
+
+host = Vixen.local_connect
+
+paths = host.paths_of_running_vms
+
+paths.each do |path|
+  puts "Currently running: #{path}"
+end
+```
+
+Vixen::Model::VM
+================
+
+`VM` currently supports the following actions:
+
+ * `current_snapshot`
+ * `create_snapshot`
+ * Power Operations
+   * `power_on`
+   * `power_off`
+   * `suspend`
+   * `resume`
+   * `reset`
+ * Querying current power state
+   * `powered_off?`
+   * `suspended?`
+   * `powered_on?`
+   * `current_power_states` - a VM may be concurrently have multiple power states
+
+Vixen::Model::Snapshot
+======================
+
+`Snapshot` currently supports the following actions:
+
+ * `display_name` - the short text title given to a snapshot
+ * `description` - the lengthy text, if any, given to a snapshot
+ * `parent` - the parent snapshot, if any
+ * `full_name` - the full name of the snapshot (traverses parent hierarchy)
 
 See Also
 --------

data/lib/vixen/bridge.rb

@@ -45,6 +45,7 @@ module Vixen::Bridge
   attach_function :VixSnapshot_GetParent, [:handle, :pointer], :int
   attach_function :VixVM_PowerOn, [:handle, :int, :handle, :VixEventProc, :pointer], :handle
   attach_function :VixVM_CreateSnapshot, [:handle, :string, :string, :int, :handle, :VixEventProc, :pointer], :handle
+  attach_function :VixJob_CheckCompletion, [:handle, :pointer], :int
 
   def self.connect(hostType, hostname, port, username, password)
     job_handle = VixHandle[:invalid]
@@ -90,6 +91,10 @@ module Vixen::Bridge
     pointer_to :int, &block
   end
 
+  def self.pointer_to_bool(&block)
+    (pointer_to :int, &block) != 0
+  end
+
   def self.wait_for_async_job(operation, &block)
     job_handle = yield
     err = VixJob_Wait job_handle, VixPropertyId[:none]
@@ -131,10 +136,11 @@ module Vixen::Bridge
                                    collect_proc,
                                    nil)
 
-    # FIXME: we seem to go into deadlock without this sleep
-    # I'm not exactly sure why
-    sleep 0.5
-    err = VixJob_Wait job_handle, VixPropertyId[:none]
+    while ( not pointer_to_bool do |bool_pointer|
+      sleep 0.01
+      VixJob_CheckCompletion(job_handle, bool_pointer)
+    end) do
+    end
 
     Vix_ReleaseHandle job_handle
     available_vms

data/vixen.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'vixen'
-  s.version = '0.0.5'
+  s.version = '0.0.6'
   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.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors: