ruby-dbus 0.15.0 → 0.18.0.beta1

data/lib/dbus/object.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+require_relative "core_ext/class/attribute"
+
+module DBus
+  PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties"
+
+  # Exported object type
+  # = Exportable D-Bus object class
+  #
+  # Objects that are going to be exported by a D-Bus service
+  # should inherit from this class. At the client side, use {ProxyObject}.
+  class Object
+    # The path of the object.
+    attr_reader :path
+
+    # The interfaces that the object supports. Hash: String => Interface
+    my_class_attribute :intfs
+    self.intfs = {}
+
+    # The service that the object is exported by.
+    attr_writer :service
+
+    @@cur_intf = nil # Interface
+    @@intfs_mutex = Mutex.new
+
+    # Create a new object with a given _path_.
+    # Use Service#export to export it.
+    def initialize(path)
+      @path = path
+      @service = nil
+    end
+
+    # Dispatch a message _msg_ to call exported methods
+    def dispatch(msg)
+      case msg.message_type
+      when Message::METHOD_CALL
+        reply = nil
+        begin
+          iface = intfs[msg.interface]
+          if !iface
+            raise DBus.error("org.freedesktop.DBus.Error.UnknownMethod"),
+                  "Interface \"#{msg.interface}\" of object \"#{msg.path}\" doesn't exist"
+          end
+          member_sym = msg.member.to_sym
+          meth = iface.methods[member_sym]
+          if !meth
+            raise DBus.error("org.freedesktop.DBus.Error.UnknownMethod"),
+                  "Method \"#{msg.member}\" on interface \"#{msg.interface}\" of object \"#{msg.path}\" doesn't exist"
+          end
+          methname = Object.make_method_name(msg.interface, msg.member)
+          retdata = method(methname).call(*msg.params)
+          retdata = [*retdata]
+
+          reply = Message.method_return(msg)
+          if iface.name == PROPERTY_INTERFACE && member_sym == :Get
+            # Use the specific property type instead of the generic variant
+            # returned by Get.
+            # TODO: GetAll and Set still missing
+            property = dbus_lookup_property(msg.params[0], msg.params[1])
+            rsigs = [property.type]
+          else
+            rsigs = meth.rets.map(&:type)
+          end
+          rsigs.zip(retdata).each do |rsig, rdata|
+            reply.add_param(rsig, rdata)
+          end
+        rescue StandardError => e
+          dbus_msg_exc = msg.annotate_exception(e)
+          reply = ErrorMessage.from_exception(dbus_msg_exc).reply_to(msg)
+        end
+        @service.bus.message_queue.push(reply)
+      end
+    end
+
+    # Select (and create) the interface that the following defined methods
+    # belong to.
+    # @param name [String] interface name like "org.example.ManagerManager"
+    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface
+    def self.dbus_interface(name)
+      @@intfs_mutex.synchronize do
+        @@cur_intf = intfs[name]
+        if !@@cur_intf
+          @@cur_intf = Interface.new(name) # validates the name
+          # As this is a mutable class_attr, we cannot use
+          #   self.intfs[name] = @@cur_intf                      # Hash#[]=
+          # as that would modify parent class attr in place.
+          # Using the setter lets a subclass have the new value
+          # while the superclass keeps the old one.
+          self.intfs = intfs.merge(name => @@cur_intf)
+        end
+        yield
+        @@cur_intf = nil
+      end
+    end
+
+    # Forgetting to declare the interface for a method/signal/property
+    # is a ScriptError.
+    class UndefinedInterface < ScriptError # rubocop:disable Lint/InheritException
+      def initialize(sym)
+        super "No interface specified for #{sym}. Enclose it in dbus_interface."
+      end
+    end
+
+    # A read-write property accessing an instance variable.
+    # A combination of `attr_accessor` and {.dbus_accessor}.
+    #
+    # PropertiesChanged signal will be emitted whenever `foo_bar=` is used
+    # but not when @foo_bar is written directly.
+    #
+    # @param ruby_name [Symbol] :foo_bar is exposed as FooBar;
+    #   use dbus_name to override
+    # @param type a signature like "s" or "a(uus)" or Type::STRING
+    # @param dbus_name [String] if not given it is made
+    #   by CamelCasing the ruby_name. foo_bar becomes FooBar
+    #   to convert the Ruby convention to the DBus convention.
+    # @return [void]
+    def self.dbus_attr_accessor(ruby_name, type, dbus_name: nil)
+      attr_accessor(ruby_name)
+
+      dbus_accessor(ruby_name, type, dbus_name: dbus_name)
+    end
+
+    # A read-only property accessing an instance variable.
+    # A combination of `attr_reader` and {.dbus_reader}.
+    #
+    # Whenever the property value gets changed from "inside" the object,
+    # you should emit the `PropertiesChanged` signal by calling
+    #
+    #   object[DBus::PROPERTY_INTERFACE].PropertiesChanged(interface_name, {dbus_name.to_s => value}, [])
+    #
+    # or, omitting the value in the signal,
+    #
+    #   object[DBus::PROPERTY_INTERFACE].PropertiesChanged(interface_name, {}, [dbus_name.to_s])
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_attr_reader(ruby_name, type, dbus_name: nil)
+      attr_reader(ruby_name)
+
+      dbus_reader(ruby_name, type, dbus_name: dbus_name)
+    end
+
+    # A write-only property accessing an instance variable.
+    # A combination of `attr_writer` and {.dbus_writer}.
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_attr_writer(ruby_name, type, dbus_name: nil)
+      attr_writer(ruby_name)
+
+      dbus_writer(ruby_name, type, dbus_name: dbus_name)
+    end
+
+    # A read-write property using a pair of reader/writer methods
+    # (which must already exist).
+    # (To directly access an instance variable, use {.dbus_attr_accessor} instead)
+    #
+    # Uses {.dbus_watcher} to set up the PropertiesChanged signal.
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_accessor(ruby_name, type, dbus_name: nil)
+      raise UndefinedInterface, ruby_name if @@cur_intf.nil?
+
+      dbus_name = make_dbus_name(ruby_name, dbus_name: dbus_name)
+      property = Property.new(dbus_name, type, :readwrite, ruby_name: ruby_name)
+      @@cur_intf.define(property)
+
+      dbus_watcher(ruby_name, dbus_name: dbus_name)
+    end
+
+    # A read-only property accessing a reader method (which must already exist).
+    # (To directly access an instance variable, use {.dbus_attr_reader} instead)
+    #
+    # Whenever the property value gets changed from "inside" the object,
+    # you should emit the `PropertiesChanged` signal by calling
+    #
+    #   object[DBus::PROPERTY_INTERFACE].PropertiesChanged(interface_name, {dbus_name.to_s => value}, [])
+    #
+    # or, omitting the value in the signal,
+    #
+    #   object[DBus::PROPERTY_INTERFACE].PropertiesChanged(interface_name, {}, [dbus_name.to_s])
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_reader(ruby_name, type, dbus_name: nil)
+      raise UndefinedInterface, ruby_name if @@cur_intf.nil?
+
+      dbus_name = make_dbus_name(ruby_name, dbus_name: dbus_name)
+      property = Property.new(dbus_name, type, :read, ruby_name: ruby_name)
+      @@cur_intf.define(property)
+    end
+
+    # A write-only property accessing a writer method (which must already exist).
+    # (To directly access an instance variable, use {.dbus_attr_writer} instead)
+    #
+    # Uses {.dbus_watcher} to set up the PropertiesChanged signal.
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_writer(ruby_name, type, dbus_name: nil)
+      raise UndefinedInterface, ruby_name if @@cur_intf.nil?
+
+      dbus_name = make_dbus_name(ruby_name, dbus_name: dbus_name)
+      property = Property.new(dbus_name, type, :write, ruby_name: ruby_name)
+      @@cur_intf.define(property)
+
+      dbus_watcher(ruby_name, dbus_name: dbus_name)
+    end
+
+    # Enables automatic sending of the PropertiesChanged signal.
+    # For *ruby_name* `foo_bar`, wrap `foo_bar=` so that it sends
+    # the signal for FooBar.
+    # The original version remains as `_original_foo_bar=`.
+    #
+    # @param ruby_name [Symbol] :foo_bar and :foo_bar= both mean the same thing
+    # @param dbus_name [String] if not given it is made
+    #   by CamelCasing the ruby_name. foo_bar becomes FooBar
+    #   to convert the Ruby convention to the DBus convention.
+    # @return [void]
+    def self.dbus_watcher(ruby_name, dbus_name: nil)
+      raise UndefinedInterface, ruby_name if @@cur_intf.nil?
+
+      cur_intf = @@cur_intf
+
+      ruby_name = ruby_name.to_s.sub(/=$/, "").to_sym
+      ruby_name_eq = "#{ruby_name}=".to_sym
+      original_ruby_name_eq = "_original_#{ruby_name_eq}"
+
+      dbus_name = make_dbus_name(ruby_name, dbus_name: dbus_name)
+
+      # the argument order is alias_method(new_name, existing_name)
+      alias_method original_ruby_name_eq, ruby_name_eq
+      define_method ruby_name_eq do |value|
+        public_send(original_ruby_name_eq, value)
+
+        # TODO: respect EmitsChangedSignal to use invalidated_properties instead
+        # PropertiesChanged, "interface:s, changed_properties:a{sv}, invalidated_properties:as"
+        PropertiesChanged(cur_intf.name, { dbus_name.to_s => value }, [])
+      end
+    end
+
+    # Defines an exportable method on the object with the given name _sym_,
+    # _prototype_ and the code in a block.
+    # @param prototype [Prototype]
+    def self.dbus_method(sym, prototype = "", &block)
+      raise UndefinedInterface, sym if @@cur_intf.nil?
+
+      @@cur_intf.define(Method.new(sym.to_s).from_prototype(prototype))
+
+      ruby_name = Object.make_method_name(@@cur_intf.name, sym.to_s)
+      # ::Module#define_method(name) { body }
+      define_method(ruby_name, &block)
+    end
+
+    # Emits a signal from the object with the given _interface_, signal
+    # _sig_ and arguments _args_.
+    # @param intf [Interface]
+    # @param sig [Signal]
+    # @param args arguments for the signal
+    def emit(intf, sig, *args)
+      @service.bus.emit(@service, self, intf, sig, *args)
+    end
+
+    # Defines a signal for the object with a given name _sym_ and _prototype_.
+    def self.dbus_signal(sym, prototype = "")
+      raise UndefinedInterface, sym if @@cur_intf.nil?
+
+      cur_intf = @@cur_intf
+      signal = Signal.new(sym.to_s).from_prototype(prototype)
+      cur_intf.define(Signal.new(sym.to_s).from_prototype(prototype))
+
+      # ::Module#define_method(name) { body }
+      define_method(sym.to_s) do |*args|
+        emit(cur_intf, signal, *args)
+      end
+    end
+
+    # Helper method that returns a method name generated from the interface
+    # name _intfname_ and method name _methname_.
+    # @api private
+    def self.make_method_name(intfname, methname)
+      "#{intfname}%%#{methname}"
+    end
+
+    # TODO: borrow a proven implementation
+    # @param str [String]
+    # @return [String]
+    # @api private
+    def self.camelize(str)
+      str.split(/_/).map(&:capitalize).join("")
+    end
+
+    # Make a D-Bus conventional name, CamelCased.
+    # @param ruby_name [String,Symbol] eg :do_something
+    # @param dbus_name [String,Symbol,nil] use this if given
+    # @return [Symbol] eg DoSomething
+    def self.make_dbus_name(ruby_name, dbus_name: nil)
+      dbus_name ||= camelize(ruby_name.to_s)
+      dbus_name.to_sym
+    end
+
+    # @param interface_name [String]
+    # @param property_name [String]
+    # @return [Property]
+    # @raise [DBus::Error]
+    # @api private
+    def dbus_lookup_property(interface_name, property_name)
+      # what should happen for unknown properties
+      # plasma: InvalidArgs (propname), UnknownInterface (interface)
+      # systemd: UnknownProperty
+      interface = intfs[interface_name]
+      if !interface
+        raise DBus.error("org.freedesktop.DBus.Error.UnknownProperty"),
+              "Property '#{interface_name}.#{property_name}' (on object '#{@path}') not found: no such interface"
+      end
+
+      property = interface.properties[property_name.to_sym]
+      if !property
+        raise DBus.error("org.freedesktop.DBus.Error.UnknownProperty"),
+              "Property '#{interface_name}.#{property_name}' (on object '#{@path}') not found"
+      end
+
+      property
+    end
+
+    ####################################################################
+
+    # use the above defined methods to declare the property-handling
+    # interfaces and methods
+
+    dbus_interface PROPERTY_INTERFACE do
+      dbus_method :Get, "in interface_name:s, in property_name:s, out value:v" do |interface_name, property_name|
+        property = dbus_lookup_property(interface_name, property_name)
+
+        if property.readable?
+          ruby_name = property.ruby_name
+          value = public_send(ruby_name)
+          [value]
+        else
+          raise DBus.error("org.freedesktop.DBus.Error.PropertyWriteOnly"),
+                "Property '#{interface_name}.#{property_name}' (on object '#{@path}') is not readable"
+        end
+      end
+
+      dbus_method :Set, "in interface_name:s, in property_name:s, in val:v" do |interface_name, property_name, value|
+        property = dbus_lookup_property(interface_name, property_name)
+
+        if property.writable?
+          ruby_name_eq = "#{property.ruby_name}="
+          public_send(ruby_name_eq, value)
+        else
+          raise DBus.error("org.freedesktop.DBus.Error.PropertyReadOnly"),
+                "Property '#{interface_name}.#{property_name}' (on object '#{@path}') is not writable"
+        end
+      end
+
+      dbus_method :GetAll, "in interface_name:s, out value:a{sv}" do |interface_name|
+        interface = intfs[interface_name]
+        if !interface
+          raise DBus.error("org.freedesktop.DBus.Error.UnknownProperty"),
+                "Properties '#{interface_name}.*' (on object '#{@path}') not found: no such interface"
+        end
+
+        p_hash = {}
+        interface.properties.each do |p_name, property|
+          next unless property.readable?
+
+          ruby_name = property.ruby_name
+          begin
+            # D-Bus spec says:
+            # > If GetAll is called with a valid interface name for which some
+            # > properties are not accessible to the caller (for example, due
+            # > to per-property access control implemented in the service),
+            # > those properties should be silently omitted from the result
+            # > array.
+            # so we will silently omit properties that fail to read.
+            # Get'ting them individually will send DBus.Error
+            p_hash[p_name.to_s] = public_send(ruby_name)
+          rescue StandardError
+            DBus.logger.debug "Property '#{interface_name}.#{p_name}' (on object '#{@path}')" \
+                              " has raised during GetAll, omitting it"
+          end
+        end
+
+        [p_hash]
+      end
+
+      dbus_signal :PropertiesChanged, "interface:s, changed_properties:a{sv}, invalidated_properties:as"
+    end
+  end
+end

data/lib/dbus/object_path.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2019 Martin Vidner
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+module DBus
+  # A {::String} that validates at initialization time
+  # @see https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path
+  class ObjectPath < String
+    # @raise Error if not a valid object path
+    def initialize(str)
+      unless self.class.valid?(str)
+        raise DBus::Error, "Invalid object path #{str.inspect}"
+      end
+
+      super
+    end
+
+    def self.valid?(str)
+      str == "/" || str =~ %r{\A(/[A-Za-z0-9_]+)+\z}
+    end
+  end
+end

data/lib/dbus/proxy_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is part of the ruby-dbus project
 # Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
 # Copyright (C) 2009-2014 Martin Vidner
@@ -36,7 +38,7 @@ module DBus
     def initialize(bus, dest, path, api: ApiOptions::CURRENT)
       @bus = bus
       @destination = dest
-      @path = path
+      @path = ObjectPath.new(path)
       @introspected = false
       @interfaces = {}
       @subnodes = []
@@ -44,6 +46,7 @@ module DBus
     end
 
     # Returns the interfaces of the object.
+    # @return [Array<String>] names of the interfaces
     def interfaces
       introspect unless introspected
       @interfaces.keys
@@ -56,6 +59,7 @@ module DBus
       introspect unless introspected
       ifc = @interfaces[intfname]
       raise DBus::Error, "no such interface `#{intfname}' on object `#{@path}'" unless ifc
+
       ifc
     end
 
@@ -92,6 +96,7 @@ module DBus
           # don't overwrite instance methods!
           next if dup_meths.include?(name)
           next if self.class.instance_methods.include?(name)
+
           if univocal_meths.include? name
             univocal_meths.delete name
             dup_meths << name
@@ -123,12 +128,20 @@ module DBus
     def on_signal(name, &block)
       # TODO: improve
       raise NoMethodError unless @default_iface && has_iface?(@default_iface)
+
       @interfaces[@default_iface].on_signal(name, &block)
     end
 
     ####################################################
     private
 
+    # rubocop:disable Lint/MissingSuper
+    # as this should forward everything
+    #
+    # https://github.com/rubocop-hq/ruby-style-guide#no-method-missing
+    # and http://blog.marc-andre.ca/2010/11/15/methodmissing-politely/
+    # have a point to be investigated
+
     # Handles all unkown methods, mostly to route method calls to the
     # default interface.
     def method_missing(name, *args, &reply_handler)
@@ -146,9 +159,17 @@ module DBus
         # 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
     end
-  end # class ProxyObject
+    # rubocop:enable Lint/MissingSuper
+
+    def respond_to_missing?(name, _include_private = false)
+      @default_iface &&
+        has_iface?(@default_iface) &&
+        @interfaces[@default_iface].methods.key?(name) or super
+    end
+  end
 end

data/lib/dbus/proxy_object_factory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is part of the ruby-dbus project
 # Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
 # Copyright (C) 2009-2014 Martin Vidner
@@ -22,17 +24,19 @@ module DBus
       @api = api
     end
 
-    # Investigates the sub-nodes of the proxy object _po_ based on the
+    # Investigates the sub-nodes of the proxy object _pobj_ based on the
     # introspection XML data _xml_ and sets them up recursively.
-    def self.introspect_into(po, xml)
-      intfs, po.subnodes = IntrospectXMLParser.new(xml).parse
+    # @param pobj [ProxyObject]
+    # @param xml [String]
+    def self.introspect_into(pobj, xml)
+      intfs, pobj.subnodes = IntrospectXMLParser.new(xml).parse
       intfs.each do |i|
-        poi = ProxyObjectInterface.new(po, i.name)
+        poi = ProxyObjectInterface.new(pobj, i.name)
         i.methods.each_value { |m| poi.define(m) }
         i.signals.each_value { |s| poi.define(s) }
-        po[i.name] = poi
+        pobj[i.name] = poi
       end
-      po.introspected = true
+      pobj.introspected = true
     end
 
     # Generates, sets up and returns the proxy object.
@@ -41,5 +45,5 @@ module DBus
       ProxyObjectFactory.introspect_into(po, @xml)
       po
     end
-  end # class ProxyObjectFactory
+  end
 end

data/lib/dbus/proxy_object_interface.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is part of the ruby-dbus project
 # Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
 # Copyright (C) 2009-2014 Martin Vidner
@@ -36,27 +38,28 @@ module DBus
       @name
     end
 
-    # Defines a method on the interface from the Method descriptor _m_.
-    def define_method_from_descriptor(m)
-      m.params.each do |fpar|
+    # Defines a method on the interface from the Method descriptor _method_.
+    # @param method [Method]
+    def define_method_from_descriptor(method)
+      method.params.each do |fpar|
         par = fpar.type
         # This is the signature validity check
         Type::Parser.new(par).parse
       end
 
       singleton_class.class_eval do
-        define_method m.name do |*args, &reply_handler|
-          if m.params.size != args.size
-            raise ArgumentError, "wrong number of arguments (#{args.size} for #{m.params.size})"
+        define_method method.name do |*args, &reply_handler|
+          if method.params.size != args.size
+            raise ArgumentError, "wrong number of arguments (#{args.size} for #{method.params.size})"
           end
 
           msg = Message.new(Message::METHOD_CALL)
           msg.path = @object.path
           msg.interface = @name
           msg.destination = @object.destination
-          msg.member = m.name
+          msg.member = method.name
           msg.sender = @object.bus.unique_name
-          m.params.each do |fpar|
+          method.params.each do |fpar|
             par = fpar.type
             msg.add_param(par, args.shift)
           end
@@ -64,25 +67,27 @@ module DBus
           if ret.nil? || @object.api.proxy_method_returns_array
             ret
           else
-            m.rets.size == 1 ? ret.first : ret
+            method.rets.size == 1 ? ret.first : ret
           end
         end
       end
 
-      @methods[m.name] = m
+      @methods[method.name] = method
     end
 
-    # Defines a signal from the descriptor _s_.
-    def define_signal_from_descriptor(s)
-      @signals[s.name] = s
+    # Defines a signal from the descriptor _sig_.
+    # @param sig [Signal]
+    def define_signal_from_descriptor(sig)
+      @signals[sig.name] = sig
     end
 
-    # Defines a signal or method based on the descriptor _m_.
-    def define(m)
-      if m.is_a?(Method)
-        define_method_from_descriptor(m)
-      elsif m.is_a?(Signal)
-        define_signal_from_descriptor(m)
+    # Defines a signal or method based on the descriptor _ifc_el_.
+    def define(ifc_el)
+      case ifc_el
+      when Method
+        define_method_from_descriptor(ifc_el)
+      when Signal
+        define_signal_from_descriptor(ifc_el)
       end
     end
 
@@ -109,7 +114,7 @@ module DBus
       end
     end
 
-    PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties".freeze
+    PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties"
 
     # Read a property.
     # @param propname [String]
@@ -141,5 +146,5 @@ module DBus
         ret
       end
     end
-  end # class ProxyObjectInterface
+  end
 end