ruby-dbus 0.16.0 → 0.18.1

data/lib/dbus/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
 #
@@ -6,10 +8,11 @@
 # License, version 2.1 as published by the Free Software Foundation.
 # See the file "COPYING" for the exact licensing terms.
 
-require "thread"
-require "dbus/core_ext/class/attribute"
+require_relative "core_ext/class/attribute"
 
 module DBus
+  PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties"
+
   # Exported object type
   # = Exportable D-Bus object class
   #
@@ -18,6 +21,7 @@ module DBus
   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 = {}
@@ -41,11 +45,13 @@ module DBus
       when Message::METHOD_CALL
         reply = nil
         begin
-          if !intfs[msg.interface]
+          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
-          meth = intfs[msg.interface].methods[msg.member.to_sym]
+          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"
@@ -55,11 +61,12 @@ module DBus
           retdata = [*retdata]
 
           reply = Message.method_return(msg)
-          meth.rets.zip(retdata).each do |rsig, rdata|
-            reply.add_param(rsig.type, rdata)
+          rsigs = meth.rets.map(&:type)
+          rsigs.zip(retdata).each do |rsig, rdata|
+            reply.add_param(rsig, rdata)
           end
-        rescue => ex
-          dbus_msg_exc = msg.annotate_exception(ex)
+        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)
@@ -68,62 +75,389 @@ module DBus
 
     # Select (and create) the interface that the following defined methods
     # belong to.
-    def self.dbus_interface(s)
+    # @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[s]
+        @@cur_intf = intfs[name]
         if !@@cur_intf
-          @@cur_intf = Interface.new(s)
+          @@cur_intf = Interface.new(name) # validates the name
           # As this is a mutable class_attr, we cannot use
-          #   self.intfs[s] = @@cur_intf                      # Hash#[]=
+          #   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(s => @@cur_intf)
+          self.intfs = intfs.merge(name => @@cur_intf)
         end
         yield
         @@cur_intf = nil
       end
     end
 
-    # Dummy undefined interface class.
-    class UndefinedInterface < ScriptError
+    # 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}"
+        super "No interface specified for #{sym}. Enclose it in dbus_interface."
+      end
+    end
+
+    # Declare the behavior of PropertiesChanged signal,
+    # common for all properties in this interface
+    # (individual properties may override it)
+    # @example
+    #   self.emits_changed_signal = :invalidates
+    # @param [true,false,:const,:invalidates] value
+    def self.emits_changed_signal=(value)
+      raise UndefinedInterface, :emits_changed_signal if @@cur_intf.nil?
+
+      @@cur_intf.emits_changed_signal = EmitsChangedSignal.new(value)
+    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.
+    # @param emits_changed_signal [true,false,:const,:invalidates]
+    #   see {EmitsChangedSignal}; if unspecified, ask the interface.
+    # @return [void]
+    def self.dbus_attr_accessor(ruby_name, type, dbus_name: nil, emits_changed_signal: nil)
+      attr_accessor(ruby_name)
+
+      dbus_accessor(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
+    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
+    # {#dbus_properties_changed}.
+    #
+    #   dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
+    #
+    # or, omitting the value in the signal,
+    #
+    #   dbus_properties_changed(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, emits_changed_signal: nil)
+      attr_reader(ruby_name)
+
+      dbus_reader(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
+    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, emits_changed_signal: nil)
+      attr_writer(ruby_name)
+
+      dbus_writer(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
+    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, emits_changed_signal: 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, emits_changed_signal: emits_changed_signal)
+    end
+
+    # A read-only property accessing a reader method (which must already exist).
+    # (To directly access an instance variable, use {.dbus_attr_reader} instead)
+    #
+    # At the D-Bus side the property is read only but it makes perfect sense to
+    # implement it with a read-write attr_accessor. In that case this method
+    # uses {.dbus_watcher} to set up the PropertiesChanged signal.
+    #
+    #   attr_accessor :foo_bar
+    #   dbus_reader :foo_bar, "s"
+    #
+    # If the property value should change by other means than its attr_writer,
+    # you should emit the `PropertiesChanged` signal by calling
+    # {#dbus_properties_changed}.
+    #
+    #   dbus_properties_changed(interface_name, {dbus_name.to_s => value}, [])
+    #
+    # or, omitting the value in the signal,
+    #
+    #   dbus_properties_changed(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, emits_changed_signal: 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)
+
+      ruby_name_eq = "#{ruby_name}=".to_sym
+      return unless method_defined?(ruby_name_eq)
+
+      dbus_watcher(ruby_name, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
+    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, emits_changed_signal: 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, emits_changed_signal: emits_changed_signal)
+    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.
+    # @param emits_changed_signal [true,false,:const,:invalidates]
+    #   see {EmitsChangedSignal}; if unspecified, ask the interface.
+    # @return [void]
+    def self.dbus_watcher(ruby_name, dbus_name: nil, emits_changed_signal: nil)
+      raise UndefinedInterface, ruby_name if @@cur_intf.nil?
+
+      interface_name = @@cur_intf.name
+
+      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)
+
+      emits_changed_signal = EmitsChangedSignal.new(emits_changed_signal, interface: @@cur_intf)
+
+      # 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|
+        result = public_send(original_ruby_name_eq, value)
+
+        case emits_changed_signal.value
+        when true
+          # signature: "interface:s, changed_props:a{sv}, invalidated_props:as"
+          dbus_properties_changed(interface_name, { dbus_name.to_s => value }, [])
+        when :invalidates
+          dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
+        when :const
+          # Oh my, seeing a value change of a supposedly constant property.
+          # Maybe should have raised at declaration time, don't make a fuss now.
+        when false
+          # Do nothing
+        end
+
+        result
       end
     end
 
     # Defines an exportable method on the object with the given name _sym_,
     # _prototype_ and the code in a block.
-    def self.dbus_method(sym, protoype = "", &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(protoype))
-      define_method(Object.make_method_name(@@cur_intf.name, sym.to_s), &block)
+
+      @@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, protoype = "")
+    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(protoype)
-      cur_intf.define(Signal.new(sym.to_s).from_prototype(protoype))
+      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
+
+    # Use this instead of calling PropertiesChanged directly. This one
+    # considers not only the PC signature (which says that all property values
+    # are variants) but also the specific property type.
+    # @param interface_name [String] interface name like "org.example.ManagerManager"
+    # @param changed_props [Hash{String => ::Object}]
+    #   changed properties (D-Bus names) and their values.
+    # @param invalidated_props [Array<String>]
+    #   names of properties whose changed value is not specified
+    def dbus_properties_changed(interface_name, changed_props, invalidated_props)
+      typed_changed_props = changed_props.map do |dbus_name, value|
+        property = dbus_lookup_property(interface_name, dbus_name)
+        type = property.type
+        typed_value = Data.make_typed(type, value)
+        variant = Data::Variant.new(typed_value, member_type: type)
+        [dbus_name, variant]
+      end.to_h
+      PropertiesChanged(interface_name, typed_changed_props, invalidated_props)
+    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)
+          # may raise, DBus.error or https://ruby-doc.com/core-3.1.0/TypeError.html
+          typed_value = Data.make_typed(property.type, value)
+          [typed_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}="
+          # TODO: declare dbus_method :Set to take :exact argument
+          # and type check it here before passing its :plain value
+          # to the implementation
+          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
+            value = public_send(ruby_name)
+            # may raise, DBus.error or https://ruby-doc.com/core-3.1.0/TypeError.html
+            typed_value = Data.make_typed(property.type, value)
+            p_hash[p_name.to_s] = typed_value
+          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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is part of the ruby-dbus project
 # Copyright (C) 2019 Martin Vidner
 #
@@ -7,18 +9,21 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # A {::String} that validates at initialization time
+  # A {::String} that validates at initialization time.
+  # See also {DBus::Data::ObjectPath}
+  # @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(s)
-      unless self.class.valid?(s)
-        raise DBus::Error, "Invalid object path #{s.inspect}"
+    def initialize(str)
+      unless self.class.valid?(str)
+        raise DBus::Error, "Invalid object path #{str.inspect}"
       end
+
       super
     end
 
-    def self.valid?(s)
-      s == "/" || s =~ %r{\A(/[A-Za-z0-9_]+)+\z}
+    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
@@ -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,21 @@ 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 [Array<Interface>], subnodes [Array<String>]
+      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
+        i.properties.each_value { |p| poi.define(p) }
+        pobj[i.name] = poi
       end
-      po.introspected = true
+      pobj.introspected = true
     end
 
     # Generates, sets up and returns the proxy object.
@@ -41,5 +47,5 @@ module DBus
       ProxyObjectFactory.introspect_into(po, @xml)
       po
     end
-  end # class ProxyObjectFactory
+  end
 end