ruby-dbus 0.23.0.beta1 → 0.23.1

data/lib/dbus/connection.rb

@@ -0,0 +1,363 @@
+# 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.
+
+module DBus
+  # D-Bus main connection class
+  #
+  # Main class that maintains a connection to a bus and can handle incoming
+  # and outgoing messages.
+  class Connection
+    # pop and push messages here
+    # @return [MessageQueue]
+    attr_reader :message_queue
+
+    # Create a new connection to the bus for a given connect _path_. _path_
+    # format is described in the D-Bus specification:
+    # http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
+    # and is something like:
+    # "transport1:key1=value1,key2=value2;transport2:key1=value1,key2=value2"
+    # e.g. "unix:path=/tmp/dbus-test" or "tcp:host=localhost,port=2687"
+    def initialize(path)
+      @message_queue = MessageQueue.new(path)
+
+      # @return [Hash{Integer => Proc}]
+      #   key: message serial
+      #   value: block to be run when the reply to that message is received
+      @method_call_replies = {}
+
+      # @return [Hash{Integer => Message}]
+      #   for debugging only: messages for which a reply was not received yet;
+      #   key == value.serial
+      @method_call_msgs = {}
+      @signal_matchrules = {}
+    end
+
+    def object_server
+      @object_server ||= ObjectServer.new(self)
+    end
+
+    # Dispatch all messages that are available in the queue,
+    # but do not block on the queue.
+    # Called by a main loop when something is available in the queue
+    def dispatch_message_queue
+      while (msg = @message_queue.pop(blocking: false)) # FIXME: EOFError
+        process(msg)
+      end
+    end
+
+    # Tell a bus to register itself on the glib main loop
+    def glibize
+      require "glib2"
+      # Circumvent a ruby-glib bug
+      @channels ||= []
+
+      gio = GLib::IOChannel.new(@message_queue.socket.fileno)
+      @channels << gio
+      gio.add_watch(GLib::IOChannel::IN) do |_c, _ch|
+        dispatch_message_queue
+        true
+      end
+    end
+
+    # NAME_FLAG_* and REQUEST_NAME_* belong to BusConnection
+    # but users will have referenced them in Connection so they need to stay here
+
+    # FIXME: describe the following names, flags and constants.
+    # See DBus spec for definition
+    NAME_FLAG_ALLOW_REPLACEMENT = 0x1
+    NAME_FLAG_REPLACE_EXISTING = 0x2
+    NAME_FLAG_DO_NOT_QUEUE = 0x4
+
+    REQUEST_NAME_REPLY_PRIMARY_OWNER = 0x1
+    REQUEST_NAME_REPLY_IN_QUEUE = 0x2
+    REQUEST_NAME_REPLY_EXISTS = 0x3
+    REQUEST_NAME_REPLY_ALREADY_OWNER = 0x4
+
+    # @api private
+    # Send a _message_.
+    # If _reply_handler_ is not given, wait for the reply
+    # and return the reply, or raise the error.
+    # If _reply_handler_ is given, it will be called when the reply
+    # eventually arrives, with the reply message as the 1st param
+    # and its params following
+    def send_sync_or_async(message, &reply_handler)
+      ret = nil
+      if reply_handler.nil?
+        send_sync(message) do |rmsg|
+          raise rmsg if rmsg.is_a?(Error)
+
+          ret = rmsg.params
+        end
+      else
+        on_return(message) do |rmsg|
+          if rmsg.is_a?(Error)
+            reply_handler.call(rmsg)
+          else
+            reply_handler.call(rmsg, * rmsg.params)
+          end
+        end
+        @message_queue.push(message)
+      end
+      ret
+    end
+
+    # @api private
+    def introspect_data(dest, path, &reply_handler)
+      m = DBus::Message.new(DBus::Message::METHOD_CALL)
+      m.path = path
+      m.interface = "org.freedesktop.DBus.Introspectable"
+      m.destination = dest
+      m.member = "Introspect"
+      m.sender = unique_name
+      if reply_handler.nil?
+        send_sync_or_async(m).first
+      else
+        send_sync_or_async(m) do |*args|
+          # TODO: test async introspection, is it used at all?
+          args.shift # forget the message, pass only the text
+          reply_handler.call(*args)
+          nil
+        end
+      end
+    end
+
+    # @api private
+    # Issues a call to the org.freedesktop.DBus.Introspectable.Introspect method
+    # _dest_ is the service and _path_ the object path you want to introspect
+    # If a code block is given, the introspect call in asynchronous. If not
+    # data is returned
+    #
+    # FIXME: link to ProxyObject data definition
+    # The returned object is a ProxyObject that has methods you can call to
+    # issue somme METHOD_CALL messages, and to setup to receive METHOD_RETURN
+    def introspect(dest, path)
+      if !block_given?
+        # introspect in synchronous !
+        data = introspect_data(dest, path)
+        pof = DBus::ProxyObjectFactory.new(data, self, dest, path)
+        pof.build
+      else
+        introspect_data(dest, path) do |async_data|
+          yield(DBus::ProxyObjectFactory.new(async_data, self, dest, path).build)
+        end
+      end
+    end
+
+    # Exception raised when a service name is requested that is not available.
+    class NameRequestError < Exception
+      # @return [Integer] one of
+      #   REQUEST_NAME_REPLY_IN_QUEUE
+      #   REQUEST_NAME_REPLY_EXISTS
+      attr_reader :error_code
+
+      def initialize(error_code)
+        @error_code = error_code
+        super()
+      end
+    end
+
+    # In case RequestName did not succeed, raise an exception but first ask the bus who owns the name instead of us
+    # @param ret [Integer] what RequestName returned
+    # @param name Name that was requested
+    # @return [REQUEST_NAME_REPLY_PRIMARY_OWNER,REQUEST_NAME_REPLY_ALREADY_OWNER] on success
+    # @raise [NameRequestError] with #error_code REQUEST_NAME_REPLY_EXISTS or REQUEST_NAME_REPLY_IN_QUEUE, on failure
+    # @api private
+    def handle_return_of_request_name(ret, name)
+      if [REQUEST_NAME_REPLY_EXISTS, REQUEST_NAME_REPLY_IN_QUEUE].include?(ret)
+        other = proxy.GetNameOwner(name).first
+        other_creds = proxy.GetConnectionCredentials(other).first
+        message = "Could not request #{name}, already owned by #{other}, #{other_creds.inspect}"
+        raise NameRequestError.new(ret), message
+      end
+
+      ret
+    end
+
+    # Attempt to request a service _name_.
+    # @raise NameRequestError which cannot really be rescued as it will be raised when dispatching a later call.
+    # @return [ObjectServer]
+    # @deprecated Use {BusConnection#request_name}.
+    def request_service(name)
+      # Use RequestName, but asynchronously!
+      # A synchronous call would not work with service activation, where
+      # method calls to be serviced arrive before the reply for RequestName
+      # (Ticket#29).
+      proxy.RequestName(name, NAME_FLAG_REPLACE_EXISTING) do |rmsg, r|
+        # check and report errors first
+        raise rmsg if rmsg.is_a?(Error)
+
+        handle_return_of_request_name(r, name)
+      end
+      object_server
+    end
+
+    # @api private
+    # Wait for a message to arrive. Return it once it is available.
+    def wait_for_message
+      @message_queue.pop # FIXME: EOFError
+    end
+
+    # @api private
+    # Send a message _msg_ on to the bus. This is done synchronously, thus
+    # the call will block until a reply message arrives.
+    # @param msg [Message]
+    # @param retc [Proc] the reply handler
+    # @yieldparam rmsg [MethodReturnMessage] the reply
+    # @yieldreturn [Array<Object>] the reply (out) parameters
+    def send_sync(msg, &retc) # :yields: reply/return message
+      return if msg.nil? # check if somethings wrong
+
+      @message_queue.push(msg)
+      @method_call_msgs[msg.serial] = msg
+      @method_call_replies[msg.serial] = retc
+
+      retm = wait_for_message
+      return if retm.nil? # check if somethings wrong
+
+      process(retm)
+      while @method_call_replies.key? msg.serial
+        retm = wait_for_message
+        process(retm)
+      end
+    rescue EOFError
+      new_err = DBus::Error.new("Connection dropped after we sent #{msg.inspect}")
+      raise new_err
+    end
+
+    # @api private
+    # Specify a code block that has to be executed when a reply for
+    # message _msg_ is received.
+    # @param msg [Message]
+    def on_return(msg, &retc)
+      # Have a better exception here
+      if msg.message_type != Message::METHOD_CALL
+        raise "on_return should only get method_calls"
+      end
+
+      @method_call_msgs[msg.serial] = msg
+      @method_call_replies[msg.serial] = retc
+    end
+
+    # Asks bus to send us messages matching mr, and execute slot when
+    # received
+    # @param match_rule [MatchRule,#to_s]
+    # @return [void] actually return whether the rule existed, internal detail
+    def add_match(match_rule, &slot)
+      # check this is a signal.
+      mrs = match_rule.to_s
+      DBus.logger.debug "#{@signal_matchrules.size} rules, adding #{mrs.inspect}"
+      rule_existed = @signal_matchrules.key?(mrs)
+      @signal_matchrules[mrs] = slot
+      rule_existed
+    end
+
+    # @param match_rule [MatchRule,#to_s]
+    # @return [void] actually return whether the rule existed, internal detail
+    def remove_match(match_rule)
+      mrs = match_rule.to_s
+      @signal_matchrules.delete(mrs).nil?
+    end
+
+    # @api private
+    # Process a message _msg_ based on its type.
+    # @param msg [Message]
+    def process(msg)
+      return if msg.nil? # check if somethings wrong
+
+      case msg.message_type
+      when Message::ERROR, Message::METHOD_RETURN
+        raise InvalidPacketException if msg.reply_serial.nil?
+
+        mcs = @method_call_replies[msg.reply_serial]
+        if !mcs
+          DBus.logger.debug "no return code for mcs: #{mcs.inspect} msg: #{msg.inspect}"
+        else
+          if msg.message_type == Message::ERROR
+            mcs.call(Error.new(msg))
+          else
+            mcs.call(msg)
+          end
+          @method_call_replies.delete(msg.reply_serial)
+          @method_call_msgs.delete(msg.reply_serial)
+        end
+      when DBus::Message::METHOD_CALL
+        if msg.path == "/org/freedesktop/DBus"
+          DBus.logger.debug "Got method call on /org/freedesktop/DBus"
+        end
+        node = object_server.get_node(msg.path, create: false)
+        # introspect a known path even if there is no object on it
+        if node &&
+           msg.interface == "org.freedesktop.DBus.Introspectable" &&
+           msg.member == "Introspect"
+          reply = Message.new(Message::METHOD_RETURN).reply_to(msg)
+          reply.sender = @unique_name
+          xml = node.to_xml(msg.path)
+          reply.add_param(Type::STRING, xml)
+          @message_queue.push(reply)
+        # dispatch for an object
+        elsif node&.object
+          node.object.dispatch(msg)
+        else
+          reply = Message.error(msg, "org.freedesktop.DBus.Error.UnknownObject",
+                                "Object #{msg.path} doesn't exist")
+          @message_queue.push(reply)
+        end
+      when DBus::Message::SIGNAL
+        # the signal can match multiple different rules
+        # clone to allow new signale handlers to be registered
+        @signal_matchrules.dup.each do |mrs, slot|
+          if DBus::MatchRule.new.from_s(mrs).match(msg)
+            slot.call(msg)
+          end
+        end
+      else
+        # spec(Message Format): Unknown types must be ignored.
+        DBus.logger.debug "Unknown message type: #{msg.message_type}"
+      end
+    rescue Exception => e
+      raise msg.annotate_exception(e)
+    end
+
+    # @api private
+    # Emit a signal event for the given _service_, object _obj_, interface
+    # _intf_ and signal _sig_ with arguments _args_.
+    # @param _service unused
+    # @param obj [DBus::Object]
+    # @param intf [Interface]
+    # @param sig [Signal]
+    # @param args arguments for the signal
+    def emit(_service, obj, intf, sig, *args)
+      m = Message.new(DBus::Message::SIGNAL)
+      m.path = obj.path
+      m.interface = intf.name
+      m.member = sig.name
+      i = 0
+      sig.params.each do |par|
+        m.add_param(par.type, args[i])
+        i += 1
+      end
+      @message_queue.push(m)
+    end
+  end
+
+  # A {Connection} that is talking directly to a peer, with no bus daemon in between.
+  # A prominent example is the PulseAudio connection,
+  # see https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/Clients/DBus/
+  # When starting, it still starts with authentication but omits the Hello message.
+  class PeerConnection < Connection
+    # Get a {ProxyPeerService}, a dummy helper to get {ProxyObject}s for
+    # a {PeerConnection}.
+    # @return [ProxyPeerService]
+    def peer_service
+      ProxyPeerService.new(self)
+    end
+  end
+end

data/lib/dbus/object.rb

@@ -19,31 +19,37 @@ module DBus
   # 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.
+    # @return [ObjectPath] The path of the object.
     attr_reader :path
 
     # The interfaces that the object supports. Hash: String => Interface
     my_class_attribute :intfs
     self.intfs = {}
 
-    # @return [Connection] the connection the object is exported by
-    attr_reader :connection
-
     @@cur_intf = nil # Interface
     @@intfs_mutex = Mutex.new
 
     # Create a new object with a given _path_.
     # Use ObjectServer#export to export it.
+    # @param path [ObjectPath] The path of the object.
     def initialize(path)
       @path = path
-      @connection = nil
+      # TODO: what parts of our API are supposed to work before we're exported?
+      self.object_server = nil
+    end
+
+    # @return [ObjectServer] the server the object is exported by
+    def object_server
+      # tests may mock the old ivar
+      @object_server || @service
     end
 
-    # @param connection [Connection] the connection the object is exported by
-    def connection=(connection)
-      @connection = connection
-      # deprecated, keeping @service for compatibility
-      @service = connection&.object_server
+    # @param server [ObjectServer] the server the object is exported by
+    # @note only the server itself should call this in its #export/#unexport
+    def object_server=(server)
+      # until v0.22.1 there was attr_writer :service
+      # so subclasses only could use @service
+      @object_server = @service = server
     end
 
     # Dispatch a message _msg_ to call exported methods
@@ -78,7 +84,9 @@ module DBus
           dbus_msg_exc = msg.annotate_exception(e)
           reply = ErrorMessage.from_exception(dbus_msg_exc).reply_to(msg)
         end
-        @connection.message_queue.push(reply)
+        # TODO: this method chain is too long,
+        # we should probably just return reply [Message] like we get a [Message]
+        object_server.connection.message_queue.push(reply)
       end
     end
 
@@ -148,18 +156,32 @@ module DBus
       dbus_accessor(ruby_name, type, dbus_name: dbus_name, emits_changed_signal: emits_changed_signal)
     end
 
+    # A read-only property accessing a read-write instance variable.
+    # A combination of `attr_accessor` and {.dbus_reader}.
+    #
+    # @param  (see .dbus_attr_accessor)
+    # @return (see .dbus_attr_accessor)
+    def self.dbus_reader_attr_accessor(ruby_name, type, dbus_name: nil, emits_changed_signal: nil)
+      attr_accessor(ruby_name)
+
+      dbus_reader(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}.
     #
+    # You may be instead looking for a variant which is read-write from the Ruby side:
+    # {.dbus_reader_attr_accessor}.
+    #
     # 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}, [])
+    #     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])
+    #     dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
     #
     # @param  (see .dbus_attr_accessor)
     # @return (see .dbus_attr_accessor)
@@ -205,18 +227,22 @@ module DBus
     # 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"
+    #     attr_accessor :foo_bar
+    #     dbus_reader :foo_bar, "s"
+    #
+    # The above two declarations have a shorthand:
+    #
+    #     dbus_reader_attr_accessor :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}, [])
+    #     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])
+    #     dbus_properties_changed(interface_name, {}, [dbus_name.to_s])
     #
     # @param  (see .dbus_attr_accessor)
     # @return (see .dbus_attr_accessor)
@@ -316,7 +342,9 @@ module DBus
     # @param sig [Signal]
     # @param args arguments for the signal
     def emit(intf, sig, *args)
-      @connection.emit(nil, self, intf, sig, *args)
+      raise "Cannot emit signal #{intf.name}.#{sig.name} before #{path} is exported" if object_server.nil?
+
+      object_server.connection.emit(nil, self, intf, sig, *args)
     end
 
     # Defines a signal for the object with a given name _sym_ and _prototype_.

data/lib/dbus/object_manager.rb

@@ -20,27 +20,31 @@ module DBus
   module ObjectManager
     OBJECT_MANAGER_INTERFACE = "org.freedesktop.DBus.ObjectManager"
 
+    # Implements `the GetManagedObjects` method.
     # @return [Hash{ObjectPath => Hash{String => Hash{String => Data::Base}}}]
     #   object -> interface -> property -> value
     def managed_objects
-      descendant_objects = connection.object_server.descendants_for(path)
+      descendant_objects = object_server.descendants_for(path)
       descendant_objects.each_with_object({}) do |obj, hash|
         hash[obj.path] = obj.interfaces_and_properties
       end
     end
 
+    # {ObjectServer#export} will call this for you to emit the `InterfacesAdded` signal.
     # @param object [DBus::Object]
     # @return [void]
     def object_added(object)
       InterfacesAdded(object.path, object.interfaces_and_properties)
     end
 
+    # {ObjectServer#unexport} will call this for you to emit the `InterfacesRemoved` signal.
     # @param object [DBus::Object]
     # @return [void]
     def object_removed(object)
       InterfacesRemoved(object.path, object.intfs.keys)
     end
 
+    # Module#included, a hook for `include ObjectManager`, declares its dbus_interface.
     def self.included(base)
       base.class_eval do
         dbus_interface OBJECT_MANAGER_INTERFACE do

data/lib/dbus/object_server.rb

@@ -36,7 +36,7 @@ module DBus
 
     # Retrieves an object at the given _path_
     # @param path [ObjectPath]
-    # @return [DBus::Object]
+    # @return [DBus::Object,nil]
     def object(path)
       node = get_node(path, create: false)
       node&.object
@@ -45,34 +45,48 @@ module DBus
 
     # 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)
-      # TODO: clarify that this is indeed the right thing, and document
-      # raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
+      raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
 
       node.object = obj
 
-      obj.connection = @connection
+      obj.object_server = self
       object_manager_for(obj)&.object_added(obj)
     end
 
-    # Undo exporting an object _obj_.
+    # 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 [DBus::Object]
-    def unexport(obj)
-      raise ArgumentError, "Expecting a DBus::Object argument" unless obj.is_a?(DBus::Object)
-
-      last_path_separator_idx = obj.path.rindex("/")
-      parent_path = obj.path[1..last_path_separator_idx - 1]
-      node_name = obj.path[last_path_separator_idx + 1..-1]
+    # @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.connection = nil
-      parent_node.delete(node_name).object
+      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*
@@ -98,6 +112,22 @@ module DBus
       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