xenapi 0.2.7

data/.yardopts

@@ -0,0 +1,2 @@
+lib/**/*.rb -
+LICENSE HISTORY

data/HISTORY

@@ -0,0 +1,45 @@
+= XenApi History
+
+=== 0.2.7 - 2011-05-09
+* Add specific Exceptions for Xen API method errors. These are kept under XenApi::Errors.
+* Massive internal cleanup and documentation
+
+=== 0.2.6 - 2011-05-06
+* [Enhancement]: Changed XenApi::Client#after_login to return self. Allows for adding
+  an #after_login block while creating the XenApi::Client such as
+
+    client = XenApi::Client.new("http://192.168.1.2").after_login do |c|
+      c.event.register(['vm'])
+    end
+
+=== 0.2.5 - 2010-02-16
+* [BugFix]: Fix issues with API calls which are passed arrays as their arguments
+
+=== 0.2.4 - 2010-02-16
+* [BugFix]: Fix undef of clone method on Dispatcher
+
+=== 0.2.3 - 2010-02-16
+* [BugFix]: Reattempted calls would fail after a re-login occurred
+
+=== 0.2.2 - 2010-02-16
+* Prevent the Ruby :clone method from masking the API method
+
+=== 0.2.1 - 2010-02-15
+* Allow for calling the after_login with the client object
+
+=== 0.2.0 - 2010-02-15
+* Add after_login callback
+* Expose Session as xenapi_session
+
+=== 0.1.2 - 2010-02-15
+* Prevent explosions when an empty path is provided to the XMLRPC::Client
+
+=== 0.1.1 - 2010-02-15
+* Codename: I find your lack of tests disturbing
+* Correct async => Async
+
+=== 0.1.0 - 2010-02-15
+* Added support for 'async' prefixed requests
+
+=== 0.0.0 - 2010-02-11
+* Initial Release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Geoff Garside
+
+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/README.rdoc

@@ -0,0 +1,28 @@
+= XenApi
+
+Xen API XMLRPC Client library for working with XenServers
+
+== Quick Example
+
+In this quick example we connect, login and invoke an API method.
+
+  client = XenApi::Client.new('http://xenapi.test')
+  client.login_with_password('root', 'password')
+  client.VM.get_all
+
+This will likely be enough information to get you on your feet with
+the API, for more details see {XenApi::Client}.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Geoff Garside. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,63 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "xenapi"
+    gem.summary = %Q{Xen API XMLRPC Client}
+    gem.description = %Q{Xen API XMLRPC Client library for working with XenServers}
+    gem.email = "geoff+xenapi@geoffgarside.co.uk"
+    gem.homepage = "http://github.com/geoffgarside/xenapi"
+    gem.authors = ["Geoff Garside"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "xenapi #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new { |y| y.options += %w(--no-private) }
+  YARD::Rake::YardocTask.new('yard:dev') { |y| y.options += %w(--protected --private) }
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.7

data/lib/xen_api.rb

@@ -0,0 +1 @@
+require 'xenapi'

data/lib/xenapi.rb

@@ -0,0 +1,6 @@
+module XenApi #:nodoc:
+  autoload :Client,         File.expand_path('../xenapi/client',            __FILE__)
+  autoload :Errors,         File.expand_path('../xenapi/errors',            __FILE__)
+  autoload :Dispatcher,     File.expand_path('../xenapi/dispatcher',        __FILE__)
+  autoload :AsyncDispatch,  File.expand_path('../xenapi/async_dispatcher',  __FILE__)
+end

data/lib/xenapi/async_dispatcher.rb

@@ -0,0 +1,36 @@
+module XenApi #:nodoc:
+  # @private
+  # This class helps to provide the ability for the +XenApi::Client+
+  # to accept +async+ method calls. Calls are similar to synchronous
+  # method calls except that the names are prefixed with 'Async'.
+  #
+  #   client = XenApi::Client.new('http://xenapi.test/')
+  #   client.async            #=> AsyncDispatcher instance
+  #   client.async.VM         #=> Dispatcher instance for 'Async.VM'
+  #   client.async.VM.start() #=> Performs XMLRPC 'Async.VM.start' call
+  #
+  # further calls on instances of this object will create a +Dispatcher+
+  # instance which then handle actual method calls.
+  class AsyncDispatcher
+    # @param [Client] client XenApi::Client instance
+    # @param [Symbol] sender XenApi::Client method to call when prefix method is invoked
+    def initialize(client, sender)
+      @client = client
+      @sender = sender
+    end
+
+    # @see Object#inspect
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    # Create a new +Dispatcher+ instance to handle the +Async.meth+ prefix.
+    #
+    # @param [String,Symbol] meth Method prefix name
+    # @param [...] args Method arguments
+    # @return [Dispatcher] dispatcher instance to handle the +Async.meth+ prefix
+    def method_missing(meth, *args)
+      Dispatcher.new(@client, "Async.#{meth}", @sender)
+    end
+  end  
+end

data/lib/xenapi/client.rb

@@ -0,0 +1,258 @@
+require 'uri'
+require 'xmlrpc/client'
+
+module XenApi #:nodoc:
+  # This class permits the invocation of XMLRPC API calls
+  # through a ruby-like interface
+  #
+  #   client = XenApi::Client.new('http://xenapi.test')
+  #   client.login_with_password('root', 'password')
+  #   client.VM.get_all
+  #
+  # == Authenticating with the API
+  # Authentication with the API takes place through the API
+  # +session+ class, usually using the +login_with_password+
+  # method. The +Client+ handles this method specially to
+  # enable it to retain the session identifier to pass to
+  # invoked methods and perform reauthentication should the
+  # session become stale.
+  #
+  #   client = XenApi::Client.new('http://xenapi.test')
+  #   client.login_with_password('root', 'password')
+  #
+  # It is worth noting that only +login*+ matching methods
+  # are specially passed through to the +session+ class.
+  #
+  # == Running code after API login
+  # The +Client+ provides the ability for running code
+  # after the client has successfully authenticated with
+  # the API. This is useful for either logging authentication
+  # or for registering for certain information from the API.
+  #
+  # The best example of this is when needing to make use of
+  # the Xen API +event+ class for asynchronous event handling.
+  # To use the API +event+ class you first have to register
+  # your interest in a specific set of event types.
+  #
+  #   client = XenApi::Client.new('http://xenapi.test')
+  #   client.after_login do |c|
+  #     c.event.register %w(vm) # register for 'vm' events
+  #   end
+  #
+  # == Asynchronous Methods
+  # To call asynchronous methods on the Xen XMLRPC API you
+  # first call +Async+ on the +Client+ instance followed by
+  # the normal method name.
+  # For example:
+  #
+  #   client = XenApi::Client.new('http://xenapi.test')
+  #   client.login_with_password('root', 'password')
+  #   client.Async.VM.get_all
+  #   client.async.VM.get_all
+  #
+  # Calling either +Async+ or +async+ will work as the
+  # capitalised form will always be sent when calling
+  # a method asynchronously.
+  class Client
+    # The +LoginRequired+ exception is raised when
+    # an API request requires login and no login
+    # credentials have yet been provided.
+    #
+    # If you don't perform a login before receiving this
+    # exception then you will want to catch it, log into
+    # the API and then retry your request.
+    class LoginRequired < RuntimeError; end
+
+    # The +SessionInvalid+ exception is raised when the
+    # API session has become stale or is otherwise invalid.
+    #
+    # Internally this exception will be handled a number of
+    # times before being raised up to the calling code.
+    class SessionInvalid < RuntimeError; end
+
+    # The +ResponseMissingStatusField+ exception is raised
+    # when the XMLRPC response is missing the +Status+ field.
+    # This typically indicates an unrecoverable error with
+    # the API itself.
+    class ResponseMissingStatusField < RuntimeError; end
+
+    # The +ResponseMissingValueField+ exception is raised
+    # when the XMLRPC response is missing the +Value+ field.
+    # This typically indicates an unrecoverable error with
+    # the API itself.
+    class ResponseMissingValueField < RuntimeError; end
+
+    # The +ResponseMissingErrorDescriptionField+ exception
+    # is raised when an error is returned in the XMLRPC
+    # response, but the type of error cannot be determined
+    # due to the lack of the +ErrorDescription+ field.
+    class ResponseMissingErrorDescriptionField < RuntimeError; end
+
+    # @see Object#inspect
+    def inspect
+      "#<#{self.class} #{@uri}>"
+    end
+
+    # @param [String] uri URL to the Xen API endpoint
+    # @param [Integer] timeout Maximum number of seconds to wait for an API response
+    def initialize(uri, timeout = 10)
+      @timeout = timeout
+      @uri = URI.parse(uri)
+      @uri.path = '/' if @uri.path == ''
+    end
+
+    # @overload after_login
+    #   Adds a block to be called after successful login to the XenAPI.
+    #   @note The block will be called whenever the receiver has to authenticate
+    #     with the XenAPI. This includes the first time the receiver recieves a
+    #     +login_*+ method call and any time the session becomes invalid.
+    #   @yield client
+    #   @yieldparam [optional, Client] client Client instance
+    # @overload after_login
+    #   Calls the created block, this is primarily for internal use only
+    # @return [Client] receiver
+    def after_login(&block)
+      if block
+        @after_login = block
+      elsif @after_login
+        case @after_login.arity
+        when 1
+          @after_login.call(self)
+        else
+          @after_login.call
+        end
+      end
+      self
+    end
+
+    # Returns the current session identifier.
+    #
+    # @return [String] session identifier
+    def xenapi_session
+      @session
+    end
+
+    # Handle API method calls.
+    #
+    # If the method called starts with +login+ then the method is
+    # assumed to be part of the +session+ namespace and will be
+    # called directly. For example +login_with_password+
+    #
+    #   client = XenApi::Client.new('http://xenapi.test/')
+    #   client.login_with_password('root', 'password)
+    #
+    # If the method called is +async+ then an +AsyncDispatcher+
+    # will be created to handle the asynchronous API method call.
+    #
+    #   client = XenApi::Client.new('http://xenapi.test/')
+    #   client.async.host.get_servertime(ref)
+    #
+    # The final case will create a +Dispatcher+ to handle the
+    # subsequent method call such as.
+    #
+    #   client = XenApi::Client.new('http://xenapi.test/')
+    #   client.host.get_servertime(ref)
+    #
+    # @note +meth+ names are not validated
+    #
+    # @param [String,Symbol] meth Method name
+    # @param [...] args Method args
+    # @return [true,AsyncDispatcher,Dispatcher]
+    def method_missing(meth, *args)
+      case meth.to_s
+      when /^login/
+        _login(meth, *args)
+      when /^async/i
+        AsyncDispatcher.new(self, :_call)
+      else
+        Dispatcher.new(self, meth, :_call)
+      end
+    end
+    protected
+      # @param [String,Symbol] meth API method to call
+      # @param [Array] args Arguments to pass to the method call
+      # @raise [SessionInvalid] Reauthentication failed
+      # @raise [LoginRequired] Authentication required, unable to login automatically
+      # @raise [EOFError] XMLRPC::Client exception
+      # @raise [Errno::EPIPE] XMLRPC::Client exception
+      def _call(meth, *args)
+        begin
+          _do_call(meth, args.dup.unshift(@session))
+        rescue SessionInvalid
+          _relogin_attempts = (_relogin_attempts || 0) + 1
+          _relogin
+          retry unless _relogin_attempts > 2
+          raise
+        rescue EOFError
+          _eof_retries = (_eof_retries || 0) + 1
+          @client = nil
+          retry unless _eof_retries > 1
+          raise
+        rescue Errno::EPIPE
+          _epipe_retries = (_epipe_retries || 0) + 1
+          @client = nil
+          retry unless _epipe_retries > 1
+          raise
+        end
+      end
+    private
+      # Reauthenticate with the API
+      # @raise [LoginRequired] Missing authentication credentials
+      def _relogin
+        raise LoginRequired if @login_meth.nil? || @login_args.nil? || @login_args.empty?
+        _login(@login_meth, *@login_args)
+      end
+
+      # Login to the API
+      #
+      # @note Will call the +after_login+ block if login is successful
+      #
+      # @param [String,Symbol] meth Login method name
+      # @param [...] args Arguments to pass to the login method
+      # @return [Boolean] true
+      # @raise [Exception] any exception raised by +_do_call+ or +after_login+
+      def _login(meth, *args)
+        begin
+          @session = _do_call("session.#{meth}", args)
+          @login_meth = meth
+          @login_args = args
+          after_login
+          true
+        rescue Exception => e
+          raise e
+        end
+      end
+
+      # Return or initialize new +XMLRPC::Client+
+      #
+      # @return [XMLRPC::Client] XMLRPC client instance
+      def _client
+        @client ||= XMLRPC::Client.new(@uri.host, @uri.path, @uri.port, nil, nil, nil, nil, @uri.port == 443, @timeout)
+      end
+
+      # Perform XMLRPC method call.
+      #
+      # @param [String,Symbol] meth XMLRPC method to call
+      # @param [Array] args XMLRPC method arguments
+      # @param [Integer] attempts Number of times to retry the call, presently unused
+      # @return [Object] method return value
+      # @raise [ResponseMissingStatusField] XMLRPC response does not have a +Status+ field
+      # @raise [ResponseMissingValueField] XMLRPC response does not have a +Value+ field
+      # @raise [ResponseMissingErrorDescriptionField] API response error missing +ErrorDescription+ field
+      # @raise [SessionInvalid] API session has expired
+      # @raise [Errors::GenericError] API method specific error
+      def _do_call(meth, args, attempts = 3)
+        r = _client.call(meth, *args)
+        raise ResponseMissingStatusField unless r.has_key?('Status')
+
+        if r['Status'] == 'Success'
+          return r['Value'] if r.has_key?('Value')
+          raise ResponseMissingValueField
+        else
+          raise ResponseMissingErrorDescriptionField unless r.has_key?('ErrorDescription')
+          raise SessionInvalid if r['ErrorDescription'][0] == 'SESSION_INVALID'
+          raise Errors.exception_class_from_desc(r['ErrorDescription'].shift), r['ErrorDescription'].inspect
+        end
+      end
+  end
+end

data/lib/xenapi/dispatcher.rb

@@ -0,0 +1,48 @@
+module XenApi #:nodoc:
+  # @private
+  # This class helps to provide XMLRPC method dispatching.
+  #
+  # Calls made to the top level +XenApi::Client+ instance
+  # will generate instances of this class to provide scoping
+  # of methods by their prefix. All Xen API method calls are
+  # two level, the first level specifies a namespace or prefix
+  # for the second level method call. Taking +VM.start+ as
+  # an example, +VM+ is the namespace prefix and +start+ is
+  # the method name.
+  #
+  # Calling Xen API XMLRPC methods therefore consists of
+  # first creating a +Dispatcher+ instance with the prefix
+  # name and then calling a method on the +Dispatcher+
+  # instance to create the XMLRPC method name to be called
+  # by the +XenApi::Client+ instance.
+  #
+  #   client = XenApi::Client.new('http://xenapi.test/')
+  #   client.VM             #=> Dispatcher instance for 'VM'
+  #   client.VM.start()     #=> Performs XMLRPC 'VM.start' call
+  class Dispatcher
+    undef :clone  # to allow for VM.clone calls
+
+    # @param [Client] client XenApi::Client instance
+    # @param [String] prefix Method prefix name
+    # @param [Symbol] sender XenApi::Client method to call when prefix method is invoked
+    def initialize(client, prefix, sender)
+      @client = client
+      @prefix = prefix
+      @sender = sender
+    end
+
+    # @see Object#inspect
+    def inspect
+      "#<#{self.class} #{@prefix}>"
+    end
+
+    # Calls a method on +XenApi::Client+ to perform the XMLRPC method
+    #
+    # @param [String,Symbol] meth Method name to be combined with the receivers +prefix+
+    # @param [...] args Method arguments
+    # @return [Object] XMLRPC response value
+    def method_missing(meth, *args)
+      @client.send(@sender, "#{@prefix}.#{meth}", *args)
+    end
+  end
+end

data/lib/xenapi/errors.rb

@@ -0,0 +1,451 @@
+module XenApi #:nodoc:
+  module Errors #:nodoc:
+    # Generic errror case, all XenApi exceptions inherit from this for ease of catching
+    class GenericError < RuntimeError; end
+
+    # The bootloader returned an error.
+    #
+    # Raised by
+    # - VM.start
+    # - VM.start_on
+    class BootloaderFailed < GenericError; end
+
+    # The device is not currently attached
+    #
+    # Raised by
+    # - VBD.unplug
+    class DeviceAlreadyDetached < GenericError; end
+
+    # The VM rejected the attempt to detach the device.
+    #
+    # Raised by
+    # - VBD.unplug
+    class DeviceDetachRejected < GenericError; end
+
+    # Some events have been lost from the queue and cannot be retrieved.
+    #
+    # Raised by
+    # - event.next
+    class EventsLost < GenericError; end
+
+    # This operation cannot be performed because it would invalidate VM
+    # failover planning such that the system would be unable to guarantee
+    # to restart protected VMs after a Host failure.
+    #
+    # Raised by
+    # - VM.set_memory_static_max
+    class HAOperationWouldBreakFailoverPlan < GenericError; end
+
+    # The host name is invalid
+    #
+    # Raised by
+    # - host.set_hostname_live
+    class HostNameInvalid < GenericError; end
+
+    # Not enough host memory is available to perform this operation
+    #
+    # Raised by
+    # - VM.assert_can_boot_here
+    class HostNotEnoughFreeMemory < GenericError; end
+
+    # You tried to create a VLAN or tunnel on top of a tunnel access
+    # PIF - use the underlying transport PIF instead.
+    #
+    # Raised by
+    # - tunnel.create
+    class IsTunnelAccessPIF < GenericError; end
+
+    # The host joining the pool cannot contain any shared storage.
+    #
+    # Raised by
+    # - pool.join
+    class JoiningHostCannotContainSharedSRs < GenericError; end
+
+    # This operation is not allowed under your license.
+    # Please contact your support representative.
+    #
+    # Raised by
+    # - VM.start
+    class LicenceRestriction < GenericError; end
+
+    # There was an error processing your license. Please contact
+    # your support representative.
+    #
+    # Raised by
+    # - host.license_apply
+    class LicenseProcessingError < GenericError; end
+
+    # There were no hosts available to complete the specified operation.
+    #
+    # Raised by
+    # - VM.start
+    class NoHostsAvailable < GenericError; end
+
+    # This operation needs the OpenVSwitch networking backend to be
+    # enabled on all hosts in the pool.
+    #
+    # Raised by
+    # - tunnel.create
+    class OpenvswitchNotActive < GenericError; end
+
+    # You attempted an operation that was not allowed.
+    #
+    # Raised by
+    # - task.cancel
+    # - VM.checkpoint
+    # - VM.clean_reboot
+    # - VM.clean_shutdown
+    # - VM.clone
+    # - VM.copy
+    # - VM.hard_reboot
+    # - VM.hard_shutdown
+    # - VM.pause
+    # - VM.pool_migrate
+    # - VM.provision
+    # - VM.resume
+    # - VM.resume_on
+    # - VM.revert
+    # - VM.snapshot
+    # - VM.snapshot_with_quiesce
+    # - VM.start
+    # - VM.start_on
+    # - VM.suspend
+    # - VM.unpause
+    class OperationNotAllowed < GenericError; end
+
+    # Another operation involving the object is currently in progress
+    #
+    # Raised by
+    # - VM.clean_reboot
+    # - VM.clean_shutdown
+    # - VM.hard_reboot
+    # - VM.hard_shutdown
+    # - VM.pause
+    # - VM.pool_migrate
+    # - VM.start
+    # - VM.start_on
+    # - VM.suspend
+    class OtherOperationInProgress < GenericError; end
+
+    # You tried to destroy a PIF, but it represents an aspect of the physical
+    # host configuration, and so cannot be destroyed. The parameter echoes the
+    # PIF handle you gave.
+    #
+    # Raised by
+    # - PIF.destroy
+    # @deprecated the PIF.destroy method is deprecated in XenServer 4.1 and replaced
+    # by VLAN.destroy and Bond.destroy
+    class PIFIsPhysical < GenericError; end
+
+    # Operation cannot proceed while a tunnel exists on this interface.
+    #
+    # Raised by
+    # - PIF.forget
+    class PIFTunnelStillExists < GenericError; end
+
+    # The credentials given by the user are incorrect, so access has been
+    # denied, and you have not been issued a session handle.
+    #
+    # Raised by
+    # - session.login_with_password
+    class SessionAuthenticationFailed < GenericError; end
+
+    # This session is not registered to receive events. You must call
+    # event.register before event.next. The session handle you are
+    # using is echoed.
+    #
+    # Raised by
+    # - event.next
+    class SessionNotRegistered < GenericError; end
+
+    # The SR is full. Requested new size exceeds the maximum size
+    #
+    # Raised by
+    # - VM.checkpoint
+    # - VM.clone
+    # - VM.copy
+    # - VM.provision
+    # - VM.revert
+    # - VM.snapshot
+    # - VM.snapshot_with_quiesce
+    class SRFull < GenericError; end
+
+    # The SR is still connected to a host via a PBD. It cannot be destroyed.
+    #
+    # Raised by
+    # - SR.destroy
+    # - SR.forget
+    class SRHasPDB < GenericError; end
+
+    # The SR backend does not support the operation (check the SR's allowed operations)
+    #
+    # Raised by
+    # - VDI.introduce
+    # - VDI.update
+    class SROperationNotSupported < GenericError; end
+
+    # The SR could not be connected because the driver was not recognised.
+    #
+    # Raised by
+    # - PBD.plug
+    # - SR.create
+    class SRUnknownDriver < GenericError; end
+
+    # The tunnel transport PIF has no IP configuration set.
+    #
+    # Raised by
+    # - PIF.plug
+    # - tunnel.create
+    class TransportPIFNotConfigured < GenericError; end
+
+    # The requested bootloader is unknown
+    #
+    # Raised by
+    # - VM.start
+    # - VM.start_on
+    class UnknownBootloader < GenericError; end
+
+    # Operation could not be performed because the drive is empty
+    #
+    # Raised by
+    # - VBD.eject
+    class VBDIsEmpty < GenericError; end
+
+    # Operation could not be performed because the drive is not empty
+    #
+    # Raised by
+    # - VBD.insert
+    class VBDNotEmpty < GenericError; end
+
+    # Media could not be ejected because it is not removable
+    #
+    # Raised by
+    # - VBD.eject
+    # - VBD.insert
+    class VBDNotRemovableMedia < GenericError; end
+
+    # You tried to create a VLAN, but the tag you gave was invalid --
+    # it must be between 0 and 4094. The parameter echoes the VLAN tag you gave.
+    #
+    # Raised by
+    # - PIF.create_VLAN (deprecated)
+    # - pool.create_VLAN (deprecated)
+    # - pool.create_VLAN_from_PIF
+    class VlanTagInvalid < GenericError; end
+
+    # You attempted an operation on a VM that was not in an appropriate
+    # power state at the time; for example, you attempted to start a VM
+    # that was already running. The parameters returned are the VM's
+    # handle, and the expected and actual VM state at the time of the call.
+    #
+    # Raised by
+    # - VM.checkpoint
+    # - VM.clean_reboot
+    # - VM.clean_shutdown
+    # - VM.checkpoint
+    # - VM.clean_reboot
+    # - VM.clean_shutdown
+    # - VM.clone
+    # - VM.copy
+    # - VM.hard_reboot
+    # - VM.hard_shutdown
+    # - VM.pause
+    # - VM.pool_migrate
+    # - VM.provision
+    # - VM.resume
+    # - VM.resume_on
+    # - VM.revert
+    # - VM.send_sysrq
+    # - VM.send_trigger
+    # - VM.snapshot
+    # - VM.snapshot_with_quiesce
+    # - VM.start
+    # - VM.start_on
+    # - VM.suspend
+    # - VM.unpause
+    class VMBadPowerState < GenericError; end
+
+    # An error occured while restoring the memory image of the
+    # specified virtual machine
+    #
+    # Raised by
+    # - VM.checkpoint
+    class VMCheckpointResumeFailed < GenericError; end
+
+    # An error occured while saving the memory image of the
+    # specified virtual machine
+    #
+    # Raised by
+    # - VM.checkpoint
+    class VMCheckpointSuspendFailed < GenericError; end
+
+    # HVM is required for this operation
+    #
+    # Raised by
+    # - VM.start
+    class VMHvmRequired < GenericError; end
+
+    # The operation attempted is not valid for a template VM
+    #
+    # Raised by
+    # - VM.clean_reboot
+    # - VM.clean_shutdown
+    # - VM.hard_reboot
+    # - VM.hard_shutdown
+    # - VM.pause
+    # - VM.pool_migrate
+    # - VM.resume
+    # - VM.resume_on
+    # - VM.start
+    # - VM.start_on
+    # - VM.suspend
+    # - VM.unpause
+    class VMIsTemplate < GenericError; end
+
+    # An error occurred during the migration process.
+    #
+    # Raised by
+    # - VM.pool_migrate
+    class VMMigrateFailed < GenericError; end
+
+    # You attempted an operation on a VM which requires PV drivers
+    # to be installed but the drivers were not detected.
+    #
+    # Raised by
+    # -VM.pool_migrate
+    class VMMissingPVDrivers < GenericError; end
+
+    # You attempted to run a VM on a host which doesn't have access to an SR
+    # needed by the VM. The VM has at least one VBD attached to a VDI in the SR
+    #
+    # Raised by
+    # - VM.assert_can_boot_here
+    class VMRequiresSR < GenericError; end
+
+    # An error occured while reverting the specified virtual machine
+    # to the specified snapshot
+    #
+    # Raised by
+    # - VM.revert
+    class VMRevertFailed < GenericError; end
+
+    # The quiesced-snapshot operation failed for an unexpected reason
+    #
+    # Raised by
+    # - VM.snapshot_with_quiesce
+    class VMSnapshotWithQuiesceFailed < GenericError; end
+
+    # The VSS plug-in is not installed on this virtual machine
+    #
+    # Raised by
+    # - VM.snapshot_with_quiesce
+    class VMSnapshotWithQuiesceNotSupported < GenericError; end
+
+    # The VSS plug-in cannot be contacted
+    #
+    # Raised by
+    # - VM.snapshot_with_quiesce
+    class VMSnapshotWithQuiescePluginDoesNotRespond < GenericError; end
+
+    # The VSS plug-in has timed out
+    #
+    # Raised by
+    # - VM.snapshot_with_quiesce
+    class VMSnapshotWithQuiesceTimeout < GenericError; end
+
+    # Returns the class for the exception appropriate for the error description given
+    #
+    # @param [String] desc ErrorDescription value from the API
+    # @return [Class] Appropriate exception class for the given description
+    def self.exception_class_from_desc(desc)
+      case desc
+      when 'BOOTLOADER_FAILED'
+        BootloaderFailed
+      when 'DEVICE_ALREADY_DETACHED'
+        DeviceAlreadyDetached
+      when 'DEVICE_DETACH_REJECTED'
+        DeviceDetachRejected
+      when 'EVENTS_LOST'
+        EventsLost
+      when 'HA_OPERATION_WOULD_BREAK_FAILOVER_PLAN'
+        HAOperationWouldBreakFailoverPlan
+      when 'HOST_NAME_INVALID'
+        HostNameInvalid
+      when 'HOST_NOT_ENOUGH_FREE_MEMORY'
+        HostNotEnoughFreeMemory
+      when 'IS_TUNNEL_ACCESS_PIF'
+        IsTunnelAccessPIF
+      when 'JOINING_HOST_CANNOT_CONTAIN_SHARED_SRS'
+        JoiningHostCannotContainSharedSRs
+      when 'LICENCE_RESTRICTION'
+        LicenceRestriction
+      when 'LICENSE_PROCESSING_ERROR'
+        LicenseProcessingError
+      when 'NO_HOSTS_AVAILABLE'
+        NoHostsAvailable
+      when 'OPENVSWITCH_NOT_ACTIVE'
+        OpenvswitchNotActive
+      when 'OPERATION_NOT_ALLOWED'
+        OperationNotAllowed
+      when 'OTHER_OPERATION_IN_PROGRESS'
+        OtherOperationInProgress
+      when 'PIF_IS_PHYSICAL'
+        PIFIsPhysical
+      when 'PIF_TUNNEL_STILL_EXISTS'
+        PIFTunnelStillExists
+      when 'SESSION_AUTHENTICATION_FAILED'
+        SessionAuthenticationFailed
+      when 'SESSION_NOT_REGISTERED'
+        SessionNotRegistered
+      when 'SR_FULL'
+        SRFull
+      when 'SR_HAS_PDB'
+        SRHasPDB
+      when 'SR_OPERATION_NOT_SUPPORTED'
+        SROperationNotSupported
+      when 'SR_UNKNOWN_DRIVER'
+        SRUnknownDriver
+      when 'TRANSPORT_PIF_NOT_CONFIGURED'
+        TransportPIFNotConfigured
+      when 'UNKNOWN_BOOTLOADER'
+        UnknownBootloader
+      when 'VBD_IS_EMPTY'
+        VBDIsEmpty
+      when 'VBD_NOT_EMPTY'
+        VBDNotEmpty
+      when 'VBD_NOT_REMOVABLE_MEDIA'
+        VBDNotRemovableMedia
+      when 'VLAN_TAG_INVALID'
+        VlanTagInvalid
+      when 'VM_BAD_POWER_STATE'
+        VMBadPowerState
+      when 'VM_CHECKPOINT_RESUME_FAILED'
+        VMCheckpointResumeFailed
+      when 'VM_CHECKPOINT_SUSPEND_FAILED'
+        VMCheckpointSuspendFailed
+      when 'VM_HVM_REQUIRED'
+        VMHVMRequired
+      when 'VM_IS_TEMPLATE'
+        VMIsTemplate
+      when 'VM_MIGRATE_FAILED'
+        VMMigrateFailed
+      when 'VM_MISSING_PV_DRIVERS'
+        VMMissingPVDrivers
+      when 'VM_REQUIRES_SR'
+        VMRequiresSR
+      when 'VM_REVERT_FAILED'
+        VMRevertFailed
+      when 'VM_SNAPSHOT_WITH_QUIESCE_FAILED'
+        VMSnapshotWithQuiesceFailed
+      when 'VM_SNAPSHOT_WITH_QUIESCE_NOT_SUPPORTED'
+        VMSnapshotWithQuiesceNotSupported
+      when 'VM_SNAPSHOT_WITH_QUIESCE_PLUGIN_DOES_NOT_RESPOND'
+        VMSnapshotWithQuiescePluginDoesNotRespond
+      when 'VM_SNAPSHOT_WITH_QUIESCE_TIMEOUT'
+        VMSnapshotWithQuiesceTimeout      
+      else
+        GenericError
+      end
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'xenapi'
+
+class Test::Unit::TestCase
+end

data/test/test_xenapi.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestXenapi < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/xenapi.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{xenapi}
+  s.version = "0.2.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Geoff Garside"]
+  s.date = %q{2011-05-09}
+  s.description = %q{Xen API XMLRPC Client library for working with XenServers}
+  s.email = %q{geoff+xenapi@geoffgarside.co.uk}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".yardopts",
+    "HISTORY",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/xen_api.rb",
+    "lib/xenapi.rb",
+    "lib/xenapi/async_dispatcher.rb",
+    "lib/xenapi/client.rb",
+    "lib/xenapi/dispatcher.rb",
+    "lib/xenapi/errors.rb",
+    "test/helper.rb",
+    "test/test_xenapi.rb",
+    "xenapi.gemspec"
+  ]
+  s.homepage = %q{http://github.com/geoffgarside/xenapi}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.7.2}
+  s.summary = %q{Xen API XMLRPC Client}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+  end
+end
+

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification 
+name: xenapi
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 7
+  version: 0.2.7
+platform: ruby
+authors: 
+- Geoff Garside
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-09 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Xen API XMLRPC Client library for working with XenServers
+email: geoff+xenapi@geoffgarside.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .yardopts
+- HISTORY
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/xen_api.rb
+- lib/xenapi.rb
+- lib/xenapi/async_dispatcher.rb
+- lib/xenapi/client.rb
+- lib/xenapi/dispatcher.rb
+- lib/xenapi/errors.rb
+- test/helper.rb
+- test/test_xenapi.rb
+- xenapi.gemspec
+homepage: http://github.com/geoffgarside/xenapi
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Xen API XMLRPC Client
+test_files: []
+