ruby-dbus 0.16.0 → 0.25.0

data/lib/dbus/object_server.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+# Copyright (C) 2023 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.
+
+require_relative "node_tree"
+
+module DBus
+  # The part of a {Connection} that can export {DBus::Object}s to provide
+  # services to clients.
+  #
+  # Note that an ObjectServer does not have a name. Typically a {Connection}
+  # has one well known name, but can have none or more.
+  #
+  # Formerly this class was intermixed with {ProxyService} as Service.
+  #
+  # @example Usage
+  #   bus = DBus.session_bus
+  #   obj = DBus::Object.new("/path") # a subclass more likely
+  #   bus.object_server.export(obj)
+  #   bus.request_name("org.example.Test")
+  class ObjectServer < NodeTree
+    # @return [Connection] The connection we're using.
+    attr_reader :connection
+
+    def initialize(connection)
+      @connection = connection
+      super()
+    end
+
+    # Retrieves an object at the given _path_
+    # @param path [ObjectPath]
+    # @return [DBus::Object,nil]
+    def object(path)
+      node = get_node(path, create: false)
+      node&.object
+    end
+    alias [] object
+
+    # Export an object
+    # @param obj [DBus::Object]
+    # @raise RuntimeError if there's already an exported object at the same path
+    def export(obj)
+      node = get_node(obj.path, create: true)
+      raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
+
+      node.object = obj
+
+      obj.object_server = self
+      object_manager_for(obj)&.object_added(obj)
+    end
+
+    # Undo exporting an object *obj_or_path*.
+    # Raises ArgumentError if it is not a DBus::Object.
+    # Returns the object, or false if _obj_ was not exported.
+    # @param obj_or_path [DBus::Object,ObjectPath,String] an object or a valid object path
+    def unexport(obj_or_path)
+      path = self.class.path_of(obj_or_path)
+      parent_path, _separator, node_name = path.rpartition("/")
+
+      parent_node = get_node(parent_path, create: false)
+      return false unless parent_node
+
+      node = if node_name == "" # path == "/"
+               parent_node
+             else
+               parent_node[node_name]
+             end
+      obj = node&.object
+      raise ArgumentError, "Cannot unexport, no object at #{path}" unless obj
+
+      object_manager_for(obj)&.object_removed(obj)
+      obj.object_server = nil
+      node.object = nil
+
+      # node can be deleted if
+      # - it has no children
+      # - it is not root
+      if node.empty? && !node.equal?(parent_node)
+        parent_node.delete(node_name)
+      end
+
+      obj
+    end
+
+    # Find the (closest) parent of *object*
+    # implementing the ObjectManager interface, or nil
+    # @return [DBus::Object,nil]
+    def object_manager_for(object)
+      path = object.path
+      node_chain = get_node_chain(path)
+      om_node = node_chain.reverse_each.find do |node|
+        node.object&.is_a? DBus::ObjectManager
+      end
+      om_node&.object
+    end
+
+    # All objects (not paths) under this path (except itself).
+    # @param path [ObjectPath]
+    # @return [Array<DBus::Object>]
+    # @raise ArgumentError if the *path* does not exist
+    def descendants_for(path)
+      node = get_node(path, create: false)
+      raise ArgumentError, "Object path #{path} doesn't exist" if node.nil?
+
+      node.descendant_objects
+    end
+
+    # @param obj_or_path [DBus::Object,ObjectPath,String] an object or a valid object path
+    # @return [ObjectPath]
+    # @api private
+    def self.path_of(obj_or_path)
+      case obj_or_path
+      when ObjectPath
+        obj_or_path
+      when String
+        ObjectPath.new(obj_or_path)
+      when DBus::Object
+        obj_or_path.path
+      else
+        raise ArgumentError, "Expecting a DBus::Object argument or DBus::ObjectPath or String which parses as one"
+      end
+    end
+
+    #########
+
+    private
+
+    #########
+
+    # @param path [ObjectPath] a path that must exist
+    # @return [Array<Node>] nodes from the root to the leaf
+    def get_node_chain(path)
+      n = @root
+      result = [n]
+      path.sub(%r{^/}, "").split("/").each do |elem|
+        n = n[elem]
+        result.push(n)
+      end
+      result
+    end
+  end
+end

data/lib/dbus/org.freedesktop.DBus.xml

@@ -0,0 +1,97 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.freedesktop.DBus">
+    <method name="Hello">
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="RequestName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="ReleaseName">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="StartServiceByName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="UpdateActivationEnvironment">
+      <arg direction="in" type="a{ss}"/>
+    </method>
+    <method name="NameHasOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="b"/>
+    </method>
+    <method name="ListNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="ListActivatableNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="AddMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="RemoveMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="GetNameOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="ListQueuedOwners">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="GetConnectionUnixUser">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetConnectionUnixProcessID">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetAdtAuditSessionData">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="ay"/>
+    </method>
+    <method name="GetConnectionSELinuxSecurityContext">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="ay"/>
+    </method>
+    <method name="ReloadConfig">
+    </method>
+    <method name="GetId">
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="GetConnectionCredentials">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="a{sv}"/>
+    </method>
+    <property name="Features" type="as" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
+    </property>
+    <property name="Interfaces" type="as" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
+    </property>
+    <signal name="NameOwnerChanged">
+      <arg type="s"/>
+      <arg type="s"/>
+      <arg type="s"/>
+    </signal>
+    <signal name="NameLost">
+      <arg type="s"/>
+    </signal>
+    <signal name="NameAcquired">
+      <arg type="s"/>
+    </signal>
+  </interface>
+</node>

data/lib/dbus/platform.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2023 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.
+
+require "rbconfig"
+
+module DBus
+  # Platform detection
+  module Platform
+    module_function
+
+    def freebsd?
+      RbConfig::CONFIG["target_os"] =~ /freebsd/
+    end
+
+    def macos?
+      RbConfig::CONFIG["target_os"] =~ /darwin/
+    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
@@ -8,20 +10,20 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # D-Bus proxy object class
-  #
-  # Class representing a remote object in an external application.
+  # 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 correctponding
+  # over the bus so that the method is executed remotely on the corresponding
   # object.
   class ProxyObject
     # The names of direct subnodes of the object in the tree.
     attr_accessor :subnodes
     # Flag determining whether the object has been introspected.
+    # @return [Boolean]
     attr_accessor :introspected
     # The (remote) destination of the object.
     attr_reader :destination
     # The path to the object.
+    # @return [ObjectPath]
     attr_reader :path
     # The bus the object is reachable via.
     attr_reader :bus
@@ -31,6 +33,8 @@ module DBus
     # @return [ApiOptions]
     attr_reader :api
 
+    OPEN_QUOTE = RUBY_VERSION >= "3.4" ? "'" : "`"
+
     # Creates a new proxy object living on the given _bus_ at destination _dest_
     # on the given _path_.
     def initialize(bus, dest, path, api: ApiOptions::CURRENT)
@@ -44,6 +48,7 @@ module DBus
     end
 
     # Returns the interfaces of the object.
+    # @return [Array<String>] names of the interfaces
     def interfaces
       introspect unless introspected
       @interfaces.keys
@@ -55,7 +60,8 @@ module DBus
     def [](intfname)
       introspect unless introspected
       ifc = @interfaces[intfname]
-      raise DBus::Error, "no such interface `#{intfname}' on object `#{@path}'" unless ifc
+      raise DBus::Error, "no such interface #{OPEN_QUOTE}#{intfname}' on object #{OPEN_QUOTE}#{@path}'" unless ifc
+
       ifc
     end
 
@@ -92,6 +98,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
@@ -121,8 +128,11 @@ module DBus
     # It uses _default_iface_ which must have been set.
     # @return [void]
     def on_signal(name, &block)
-      # TODO: improve
-      raise NoMethodError unless @default_iface && has_iface?(@default_iface)
+      unless @default_iface && has_iface?(@default_iface)
+        raise NoMethodError, "undefined signal #{OPEN_QUOTE}#{name}' for DBus interface " \
+                             "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
+      end
+
       @interfaces[@default_iface].on_signal(name, &block)
     end
 
@@ -137,7 +147,8 @@ module DBus
         # - 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}'"
+        raise NoMethodError, "undefined method #{OPEN_QUOTE}#{name}' for DBus interface " \
+                             "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
       end
 
       begin
@@ -145,10 +156,18 @@ module DBus
       rescue NameError => e
         # interesting, foo.method("unknown")
         # raises NameError, not NoMethodError
-        raise unless e.to_s =~ /undefined method `#{name}'/
+        raise unless e.to_s =~ /undefined method #{OPEN_QUOTE}#{name}'/
+
         # BTW e.exception("...") would preserve the class.
-        raise NoMethodError, "undefined method `#{name}' for DBus interface `#{@default_iface}' on object `#{@path}'"
+        raise NoMethodError, "undefined method #{OPEN_QUOTE}#{name}' for DBus interface " \
+                             "#{OPEN_QUOTE}#{@default_iface}' on object #{OPEN_QUOTE}#{@path}'"
       end
     end
-  end # class ProxyObject
+
+    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

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
@@ -13,13 +15,16 @@ module DBus
   # A class similar to the normal Interface used as a proxy for remote
   # object interfaces.
   class ProxyObjectInterface
-    # The proxied methods contained in the interface.
-    attr_accessor :methods
-    # The proxied signals contained in the interface.
-    attr_accessor :signals
-    # The proxy object to which this interface belongs.
+    # @return [Hash{String => DBus::Method}]
+    attr_reader :methods
+    # @return [Hash{String => Signal}]
+    attr_reader :signals
+    # @return [Hash{Symbol => Property}]
+    attr_reader :properties
+
+    # @return [ProxyObject] The proxy object to which this interface belongs.
     attr_reader :object
-    # The name of the interface.
+    # @return [String] The name of the interface.
     attr_reader :name
 
     # Creates a new proxy interface for the given proxy _object_
@@ -29,6 +34,7 @@ module DBus
       @name = name
       @methods = {}
       @signals = {}
+      @properties = {}
     end
 
     # Returns the string representation of the interface (the name).
@@ -36,27 +42,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 +71,35 @@ 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)
+    # @param prop [Property]
+    def define_property_from_descriptor(prop)
+      @properties[prop.name] = prop
+    end
+
+    # Defines a signal or method based on the descriptor _ifc_el_.
+    # @param ifc_el [DBus::Method,Signal,Property]
+    def define(ifc_el)
+      case ifc_el
+      when Method
+        define_method_from_descriptor(ifc_el)
+      when Signal
+        define_signal_from_descriptor(ifc_el)
+      when Property
+        define_property_from_descriptor(ifc_el)
       end
     end
 
@@ -109,7 +126,7 @@ module DBus
       end
     end
 
-    PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties".freeze
+    PROPERTY_INTERFACE = "org.freedesktop.DBus.Properties"
 
     # Read a property.
     # @param propname [String]
@@ -124,10 +141,26 @@ module DBus
     end
 
     # Write a property.
-    # @param propname [String]
+    # @param property_name [String]
     # @param value [Object]
-    def []=(propname, value)
-      object[PROPERTY_INTERFACE].Set(name, propname, value)
+    def []=(property_name, value)
+      property = properties[property_name.to_sym]
+      if !property
+        raise DBus.error("org.freedesktop.DBus.Error.UnknownProperty"),
+              "Property '#{name}.#{property_name}' (on object '#{object.path}') not found"
+      end
+
+      case value
+      # accommodate former need to explicitly make a variant with the right type
+      when Data::Variant
+        variant = value
+      else
+        type = property.type
+        typed_value = Data.make_typed(type, value)
+        variant = Data::Variant.new(typed_value, member_type: type)
+      end
+
+      object[PROPERTY_INTERFACE].Set(name, property_name, variant)
     end
 
     # Read all properties at once, as a hash.
@@ -141,5 +174,5 @@ module DBus
         ret
       end
     end
-  end # class ProxyObjectInterface
+  end
 end