Class: VirtualBox::COM::AbstractInterface

Inherits:
Object
  • Object
show all
Defined in:
lib/virtualbox/com/abstract_interface.rb

Overview

Base class for a COM (component object model) interface class. This abstraction is necessary to maintain a common ground between Windows COM usage and the VirtualBox C API for unix based systems.

# Defining an Interface

Defining an interface is done by subclassing AbstractInterface and using the provided class methods to define the COM methods and properties. A small example class is shown below:

class Time < AbstractInterface
  function :now, [[:out, :uint]]
  property :hour, :uint
end

# Accessing an Interface

Interfaces are never accessed directly. Instead, an InterfaceRunner should be used. Depending on the OS of the running system, the VirtualBox gem will automatically either load the MSCOM interface (on Windows) or the XPCOM interface (on Unix). One loaded, interfaces can simply be accessed:

# Assume `time` was retrieved already
puts time.foo.to_s
time.hour = 20
x = time.now

The above example shows how the properties and functions can be used with a given interface.

Direct Known Subclasses

Interface::Version_4_0_X::Appliance, Interface::Version_4_0_X::AudioAdapter, Interface::Version_4_0_X::BIOSSettings, Interface::Version_4_0_X::BandwidthControl, Interface::Version_4_0_X::BandwidthGroup, Interface::Version_4_0_X::Console, Interface::Version_4_0_X::DHCPServer, Interface::Version_4_0_X::EventSource, Interface::Version_4_0_X::Guest, Interface::Version_4_0_X::GuestOSType, Interface::Version_4_0_X::Host, Interface::Version_4_0_X::HostNetworkInterface, Interface::Version_4_0_X::HostUSBDevice, Interface::Version_4_0_X::HostUSBDeviceFilter, Interface::Version_4_0_X::Machine, Interface::Version_4_0_X::Medium, Interface::Version_4_0_X::MediumAttachment, Interface::Version_4_0_X::MediumFormat, Interface::Version_4_0_X::NATEngine, Interface::Version_4_0_X::NSIException, Interface::Version_4_0_X::NSISupports, Interface::Version_4_0_X::NetworkAdapter, Interface::Version_4_0_X::ParallelPort, Interface::Version_4_0_X::PciDeviceAttachment, Interface::Version_4_0_X::Progress, Interface::Version_4_0_X::SerialPort, Interface::Version_4_0_X::Session, Interface::Version_4_0_X::SharedFolder, Interface::Version_4_0_X::Snapshot, Interface::Version_4_0_X::StorageController, Interface::Version_4_0_X::SystemProperties, Interface::Version_4_0_X::USBController, Interface::Version_4_0_X::USBDevice, Interface::Version_4_0_X::USBDeviceFilter, Interface::Version_4_0_X::VRDEServer, Interface::Version_4_0_X::VirtualBox, Interface::Version_4_0_X::VirtualBoxErrorInfo, Interface::Version_4_0_X::VirtualSystemDescription, Interface::Version_4_1_X::AdditionsFacility, Interface::Version_4_1_X::Appliance, Interface::Version_4_1_X::AudioAdapter, Interface::Version_4_1_X::BIOSSettings, Interface::Version_4_1_X::BandwidthControl, Interface::Version_4_1_X::BandwidthGroup, Interface::Version_4_1_X::Console, Interface::Version_4_1_X::DHCPServer, Interface::Version_4_1_X::EventSource, Interface::Version_4_1_X::Guest, Interface::Version_4_1_X::GuestDirEntry, Interface::Version_4_1_X::GuestOSType, Interface::Version_4_1_X::Host, Interface::Version_4_1_X::HostNetworkInterface, Interface::Version_4_1_X::HostUSBDevice, Interface::Version_4_1_X::HostUSBDeviceFilter, Interface::Version_4_1_X::Machine, Interface::Version_4_1_X::Medium, Interface::Version_4_1_X::MediumAttachment, Interface::Version_4_1_X::MediumFormat, Interface::Version_4_1_X::NATEngine, Interface::Version_4_1_X::NSIException, Interface::Version_4_1_X::NSISupports, Interface::Version_4_1_X::NetworkAdapter, Interface::Version_4_1_X::ParallelPort, Interface::Version_4_1_X::PciDeviceAttachment, Interface::Version_4_1_X::Progress, Interface::Version_4_1_X::SerialPort, Interface::Version_4_1_X::Session, Interface::Version_4_1_X::SharedFolder, Interface::Version_4_1_X::Snapshot, Interface::Version_4_1_X::StorageController, Interface::Version_4_1_X::StorageDeviceChangedEvent, Interface::Version_4_1_X::SystemProperties, Interface::Version_4_1_X::USBController, Interface::Version_4_1_X::USBDevice, Interface::Version_4_1_X::USBDeviceFilter, Interface::Version_4_1_X::VRDEServer, Interface::Version_4_1_X::VirtualBox, Interface::Version_4_1_X::VirtualBoxErrorInfo, Interface::Version_4_1_X::VirtualSystemDescription

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(implementer, lib, *args) ⇒ AbstractInterface

Initializes the interface with the given implementer



123
124
125
126
127
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 123

def initialize(implementer, lib, *args)
  # Instantiate the implementer and set it
  @lib = lib
  @implementer = implementer.new(self, lib, *args)
end

Instance Attribute Details

#implementer ⇒ Object (readonly)

Returns the value of attribute implementer.



35
36
37
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 35

def implementer
  @implementer
end

#lib ⇒ Object (readonly)

Returns the value of attribute lib.



36
37
38
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 36

def lib
  @lib
end

Class Method Details

.function(name, type, spec, opts = {}) ⇒ Object

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.



53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 53

def function(name, type, spec, opts={})
  members << [name, {
    :type => :function,
    :value_type => type,
    :spec => spec,
    :opts => opts
  }]

  # Define the method to call the function
  define_method(name) { |*args| call_function(name, *args) }
end

.functions ⇒ Array

Returns the functions of the interface as an array in the order they were defined.

Returns:

  • (Array) 


105
106
107
108
109
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 105

def functions
  members.find_all do |data|
    data[1][:type] == :function
  end
end

.get_parent ⇒ Object

Returns the parent.



46
47
48
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 46

def get_parent
  defined?(@parent) ? @parent : :NSISupports
end

.member(name) ⇒ Hash

Returns the information for a given member

Returns:

  • (Hash) 


84
85
86
87
88
89
90
91
92
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 84

def member(name)
  members.each do |current_name, opts|
    if name == current_name
      return opts
    end
  end

  nil
end

.members ⇒ Array

Returns the members of the interface as an array.

Returns:

  • (Array) 


97
98
99
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 97

def members
  @members ||= []
end

.parent(type = nil) ⇒ Object

This sets the parent class type. This defaults to NSISupports, but can be explicitly set to nil (no parent) if necessary.



41
42
43
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 41

def parent(type=nil)
  @parent = type
end

.properties ⇒ Array

Returns the properties of the interface as an array in the order they were defined.

Returns:

  • (Array) 


115
116
117
118
119
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 115

def properties
  members.find_all do |data|
    data[1][:type] == :property
  end
end

.property(name, type, opts = {}) ⇒ Object

Adds a property to the interface with the given name, type, and options.



67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 67

def property(name, type, opts={})
  members << [name, {
    :type => :property,
    :value_type => type,
    :opts => opts
  }]

  # Define the method to read the property
  define_method(name) { read_property(name) }

  # Define method to write the property
  define_method("#{name}=".to_sym) { |value| write_property(name, value) } unless opts[:readonly]
end

Instance Method Details

#call_function(name, *args) ⇒ Object

Calls a function with the given name by calling call_function on the implementer.



144
145
146
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 144

def call_function(name, *args)
  @implementer.call_function(name, args, member(name))
end

#has_function?(name) ⇒ Boolean

Returns a boolean if a given function exists or not

Returns:

  • (Boolean) 


149
150
151
152
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 149

def has_function?(name)
  info = member(name)
  !info.nil? && info[:type] == :function
end

#has_property?(name) ⇒ Boolean

Returns a boolean if a given property exists or not.

Returns:

  • (Boolean) 


155
156
157
158
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 155

def has_property?(name)
  info = member(name)
  !info.nil? && info[:type] == :property
end

#inspect ⇒ Object

Concise inspect



173
174
175
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 173

def inspect
  "#<#{self.class.name}>"
end

#member(name) ⇒ Object

Returns the member of the interface specified by name. This simply calls member



162
163
164
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 162

def member(name)
  self.class.member(name)
end

#members ⇒ Object

Returns the members of the interface as an array. This simply calls members.



168
169
170
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 168

def members
  self.class.members
end

#read_property(name) ⇒ Object

Reads a property with the given name by calling the read_property method on the implementer.



131
132
133
134
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 131

def read_property(name)
  # Just call it on the implementer
  @implementer.read_property(name, member(name))
end

#write_property(name, value) ⇒ Object

Writes a property with the given name and value by calling the ‘write_property` method on the implementer.



138
139
140
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 138

def write_property(name, value)
  @implementer.write_property(name, value, member(name))
end