# class DBus::ProxyObject

Represents 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 corresponding object.

### Constants

OPEN_QUOTE

### Attributes

api[R]

@api private @return [ApiOptions]

bus[R]

The bus the object is reachable via.

default_iface[RW]

@return [String] The name of the default interface of the object.

destination[R]

The (remote) destination of the object.

introspected[RW]

Flag determining whether the object has been introspected. @return [Boolean]

path[R]

The path to the object. @return [ObjectPath]

subnodes[RW]

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

### Public Class Methods

new(bus, dest, path, api: ApiOptions::CURRENT) click to toggle source

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

       # File lib/dbus/proxy_object.rb
    40 def initialize(bus, dest, path, api: ApiOptions::CURRENT)
    41   @bus = bus
    42   @destination = dest
    43   @path = ObjectPath.new(path)
    44   @introspected = false
    45   @interfaces = {}
    46   @subnodes = []
    47   @api = api
    48 end

### Public Instance Methods

[](intfname) click to toggle source

Retrieves an interface of the proxy object @param [String] intfname @return [ProxyObjectInterface]

       # File lib/dbus/proxy_object.rb
    60 def [](intfname)
    61   introspect unless introspected
    62   ifc = @interfaces[intfname]
    63   raise DBus::Error, "no such interface #{OPEN_QUOTE}#{intfname}' on object #{OPEN_QUOTE}#{@path}'" unless ifc
    64
    65   ifc
    66 end

[]=(intfname, intf) click to toggle source

Maps the given interface name intfname to the given interface _intf. @param [String] intfname @param [ProxyObjectInterface] intf @return [ProxyObjectInterface] @api private

       # File lib/dbus/proxy_object.rb
    73 def []=(intfname, intf)
    74   @interfaces[intfname] = intf
    75 end

define_shortcut_methods() click to toggle source

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 {ProxyObject} is introspected.

        # File lib/dbus/proxy_object.rb
     91 def define_shortcut_methods
     92   # builds a list of duplicated methods
     93   dup_meths = []
     94   univocal_meths = {}
     95   @interfaces.each_value do |intf|
     96     intf.methods.each_value do |meth|
     97       name = meth.name.to_sym
     98       # don't overwrite instance methods!
     99       next if dup_meths.include?(name)
    100       next if self.class.instance_methods.include?(name)
    101
    102       if univocal_meths.include? name
    103         univocal_meths.delete name
    104         dup_meths << name
    105       else
    106         univocal_meths[name] = intf
    107       end
    108     end
    109   end
    110   univocal_meths.each do |name, intf|
    111     # creates a shortcut function that forwards each call to the method on
    112     # the appropriate intf
    113     singleton_class.class_eval do
    114       redefine_method name do |*args, &reply_handler|
    115         intf.method(name).call(*args, &reply_handler)
    116       end
    117     end
    118   end
    119 end

has_iface?(name) click to toggle source

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

        # File lib/dbus/proxy_object.rb
    122 def has_iface?(name)
    123   introspect unless introspected
    124   @interfaces.key?(name)
    125 end

interfaces() click to toggle source

Returns the interfaces of the object. @return [Array<String>] names of the interfaces

       # File lib/dbus/proxy_object.rb
    52 def interfaces
    53   introspect unless introspected
    54   @interfaces.keys
    55 end

introspect() click to toggle source

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

       # File lib/dbus/proxy_object.rb
    79 def introspect
    80   # Synchronous call here.
    81   xml = @bus.introspect_data(@destination, @path)
    82   ProxyObjectFactory.introspect_into(self, xml)
    83   define_shortcut_methods
    84   xml
    85 end

on_signal(name, &block) click to toggle source

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

        # File lib/dbus/proxy_object.rb
    130 def on_signal(name, &block)
    131   unless @default_iface && has_iface?(@default_iface)
    132     raise NoMethodError, "undefined signal #{OPEN_QUOTE}#{name}' for DBus interface " \
    133                          "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
    134   end
    135
    136   @interfaces[@default_iface].on_signal(name, &block)
    137 end

### Private Instance Methods

method_missing(name, *args, &reply_handler) click to toggle source

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

        # File lib/dbus/proxy_object.rb
    144 def method_missing(name, *args, &reply_handler)
    145   unless @default_iface && has_iface?(@default_iface)
    146     # TODO: distinguish:
    147     # - di not specified
    148     # TODO
    149     # - di is specified but not found in introspection data
    150     raise NoMethodError, "undefined method #{OPEN_QUOTE}#{name}' for DBus interface " \
    151                          "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
    152   end
    153
    154   begin
    155     @interfaces[@default_iface].method(name).call(*args, &reply_handler)
    156   rescue NameError => e
    157     # interesting, foo.method("unknown")
    158     # raises NameError, not NoMethodError
    159     raise unless e.to_s =~ /undefined method #{OPEN_QUOTE}#{name}'/
    160
    161     # BTW e.exception("...") would preserve the class.
    162     raise NoMethodError, "undefined method #{OPEN_QUOTE}#{name}' for DBus interface " \
    163                          "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
    164   end
    165 end

respond_to_missing?(name, _include_private = false) click to toggle source
Calls superclass method

        # File lib/dbus/proxy_object.rb
    167 def respond_to_missing?(name, _include_private = false)
    168   (@default_iface &&
    169     has_iface?(@default_iface) &&
    170     @interfaces[@default_iface].methods.key?(name)) or super
    171 end