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_3_1_X::Appliance, Interface::Version_3_1_X::AudioAdapter, Interface::Version_3_1_X::BIOSSettings, Interface::Version_3_1_X::Console, Interface::Version_3_1_X::DHCPServer, Interface::Version_3_1_X::GuestOSType, Interface::Version_3_1_X::Host, Interface::Version_3_1_X::HostNetworkInterface, Interface::Version_3_1_X::HostUSBDevice, Interface::Version_3_1_X::HostUSBDeviceFilter, Interface::Version_3_1_X::Machine, Interface::Version_3_1_X::Medium, Interface::Version_3_1_X::MediumAttachment, Interface::Version_3_1_X::MediumFormat, Interface::Version_3_1_X::NSIException, Interface::Version_3_1_X::NSISupports, Interface::Version_3_1_X::NetworkAdapter, Interface::Version_3_1_X::ParallelPort, Interface::Version_3_1_X::Progress, Interface::Version_3_1_X::SerialPort, Interface::Version_3_1_X::Session, Interface::Version_3_1_X::SharedFolder, Interface::Version_3_1_X::Snapshot, Interface::Version_3_1_X::StorageController, Interface::Version_3_1_X::SystemProperties, Interface::Version_3_1_X::USBController, Interface::Version_3_1_X::USBDevice, Interface::Version_3_1_X::USBDeviceFilter, Interface::Version_3_1_X::VRDPServer, Interface::Version_3_1_X::VirtualBox, Interface::Version_3_1_X::VirtualBoxErrorInfo, Interface::Version_3_1_X::VirtualSystemDescription, Interface::Version_3_2_X::Appliance, Interface::Version_3_2_X::AudioAdapter, Interface::Version_3_2_X::BIOSSettings, Interface::Version_3_2_X::Console, Interface::Version_3_2_X::DHCPServer, Interface::Version_3_2_X::Guest, Interface::Version_3_2_X::GuestOSType, Interface::Version_3_2_X::Host, Interface::Version_3_2_X::HostNetworkInterface, Interface::Version_3_2_X::HostUSBDevice, Interface::Version_3_2_X::HostUSBDeviceFilter, Interface::Version_3_2_X::Machine, Interface::Version_3_2_X::Medium, Interface::Version_3_2_X::MediumAttachment, Interface::Version_3_2_X::MediumFormat, Interface::Version_3_2_X::NATEngine, Interface::Version_3_2_X::NSIException, Interface::Version_3_2_X::NSISupports, Interface::Version_3_2_X::NetworkAdapter, Interface::Version_3_2_X::ParallelPort, Interface::Version_3_2_X::Progress, Interface::Version_3_2_X::SerialPort, Interface::Version_3_2_X::Session, Interface::Version_3_2_X::SharedFolder, Interface::Version_3_2_X::Snapshot, Interface::Version_3_2_X::StorageController, Interface::Version_3_2_X::SystemProperties, Interface::Version_3_2_X::USBController, Interface::Version_3_2_X::USBDevice, Interface::Version_3_2_X::USBDeviceFilter, Interface::Version_3_2_X::VRDPServer, Interface::Version_3_2_X::VirtualBox, Interface::Version_3_2_X::VirtualBoxErrorInfo, Interface::Version_3_2_X::VirtualSystemDescription, Interface::Version_4_0_X::Appliance, Interface::Version_4_0_X::AudioAdapter, Interface::Version_4_0_X::BIOSSettings, 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::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

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



112
113
114
115
116
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 112

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.



42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 42

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) 


94
95
96
97
98
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 94

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

.member(name) ⇒ Hash

Returns the information for a given member

Returns:

  • (Hash) 


73
74
75
76
77
78
79
80
81
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 73

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) 


86
87
88
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 86

def members
  @members ||= []
end

.properties ⇒ Array

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

Returns:

  • (Array) 


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

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.



56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 56

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.



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

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) 


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

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) 


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

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

#inspect ⇒ Object

Concise inspect



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

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

#member(name) ⇒ Object

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



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

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

#members ⇒ Object

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



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

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.



120
121
122
123
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 120

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.



127
128
129
 
# File 'lib/virtualbox/com/abstract_interface.rb', line 127

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