Class: DBus::ProxyObject

Inherits:
Object
  • Object
show all
Defined in:
lib/dbus/proxy_object.rb

Overview

D-Bus proxy object class

Class representing a remote object in an external application. Typically, calling a method on an instance of a ProxyObject sends a message over the bus so that the method is executed remotely on the correctponding object.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(bus, dest, path, api: ApiOptions::CURRENT) ⇒ ProxyObject

Creates a new proxy object living on the given bus at destination dest on the given path.



36
37
38
39
40
41
 
# File 'lib/dbus/proxy_object.rb', line 36

def initialize(bus, dest, path, api: ApiOptions::CURRENT)
  @bus, @destination, @path = bus, dest, path
  @interfaces = Hash.new
  @subnodes = Array.new
  @api = api
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &reply_handler) ⇒ Object (private)

Handles all unkown methods, mostly to route method calls to the default interface.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/dbus/proxy_object.rb', line 128

def method_missing(name, *args, &reply_handler)
  if @default_iface and has_iface?(@default_iface)
    begin
      @interfaces[@default_iface].method(name).call(*args, &reply_handler)
    rescue NameError => e
      # interesting, foo.method("unknown")
      # raises NameError, not NoMethodError
      raise unless e.to_s =~ /undefined method `#{name}'/
      # BTW e.exception("...") would preserve the class.
      raise NoMethodError,"undefined method `#{name}' for DBus interface `#{@default_iface}' on object `#{@path}'"
    end
  else
    # TODO distinguish:
    # - di not specified
    #TODO
    # - di is specified but not found in introspection data
    raise NoMethodError, "undefined method `#{name}' for DBus interface `#{@default_iface}' on object `#{@path}'"
  end
end

Instance Attribute Details

#api ⇒ ApiOptions (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



32
33
34
 
# File 'lib/dbus/proxy_object.rb', line 32

def api
  @api
end

#bus ⇒ Object (readonly)

The bus the object is reachable via.



27
28
29
 
# File 'lib/dbus/proxy_object.rb', line 27

def bus
  @bus
end

#default_iface ⇒ String

Returns The name of the default interface of the object.

Returns:

  • (String) —

    The name of the default interface of the object.



29
30
31
 
# File 'lib/dbus/proxy_object.rb', line 29

def default_iface
  @default_iface
end

#destination ⇒ Object (readonly)

The (remote) destination of the object.



23
24
25
 
# File 'lib/dbus/proxy_object.rb', line 23

def destination
  @destination
end

#introspected ⇒ Object

Flag determining whether the object has been introspected.



21
22
23
 
# File 'lib/dbus/proxy_object.rb', line 21

def introspected
  @introspected
end

#path ⇒ Object (readonly)

The path to the object.



25
26
27
 
# File 'lib/dbus/proxy_object.rb', line 25

def path
  @path
end

#subnodes ⇒ Object

The names of direct subnodes of the object in the tree.



19
20
21
 
# File 'lib/dbus/proxy_object.rb', line 19

def subnodes
  @subnodes
end

Instance Method Details

#[](intfname) ⇒ ProxyObjectInterface

Retrieves an interface of the proxy object

Parameters:

  • intfname (String)

Returns:



51
52
53
 
# File 'lib/dbus/proxy_object.rb', line 51

def [](intfname)
  @interfaces[intfname]
end

#[]=(intfname, intf) ⇒ ProxyObjectInterface

Maps the given interface name intfname to the given interface _intf.

Parameters:

Returns:



59
60
61
 
# File 'lib/dbus/proxy_object.rb', line 59

def []=(intfname, intf)
  @interfaces[intfname] = intf
end

#define_shortcut_methods ⇒ Object

For each non duplicated method name in any interface present on the caller, defines a shortcut method dynamically. This function is automatically called when a DBus::ProxyObject is introspected.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/dbus/proxy_object.rb', line 77

def define_shortcut_methods
  # builds a list of duplicated methods
  dup_meths, univocal_meths = [],{}
  @interfaces.each_value do |intf|
    intf.methods.each_value do |meth|
      name = meth.name.to_sym
      # don't overwrite instance methods!
      if dup_meths.include? name or self.class.instance_methods.include? name
        next
      elsif univocal_meths.include? name
        univocal_meths.delete name
        dup_meths << name
      else
        univocal_meths[name] = intf
      end
    end
  end
  univocal_meths.each do |name, intf|
    # creates a shortcut function that forwards each call to the method on
    # the appropriate intf
    singleton_class.class_eval do
      define_method name do |*args, &reply_handler|
        intf.method(name).call(*args, &reply_handler)
      end
    end
  end
end

#has_iface?(name) ⇒ Boolean

Returns whether the object has an interface with the given name.

Returns:

  • (Boolean) 


106
107
108
109
 
# File 'lib/dbus/proxy_object.rb', line 106

def has_iface?(name)
  raise "Cannot call has_iface? if not introspected" if not @introspected
  @interfaces.member?(name)
end

#interfaces ⇒ Object

Returns the interfaces of the object.



44
45
46
 
# File 'lib/dbus/proxy_object.rb', line 44

def interfaces
  @interfaces.keys
end

#introspect ⇒ Object

Introspects the remote object. Allows you to find and select interfaces on the object.



65
66
67
68
69
70
71
 
# File 'lib/dbus/proxy_object.rb', line 65

def introspect
  # Synchronous call here.
  xml = @bus.introspect_data(@destination, @path)
  ProxyObjectFactory.introspect_into(self, xml)
  define_shortcut_methods()
  xml
end

#on_signal(name, &block) ⇒ void

This method returns an undefined value.

Registers a handler, the code block, for a signal with the given name. It uses default_iface which must have been set.



114
115
116
117
118
119
120
121
 
# File 'lib/dbus/proxy_object.rb', line 114

def on_signal(name, &block)
  if @default_iface and has_iface?(@default_iface)
    @interfaces[@default_iface].on_signal(name, &block)
  else
    # TODO improve
    raise NoMethodError
  end
end