ruby-dbus 0.23.0.beta1 → 0.23.1

data/lib/dbus/bus.rb

@@ -13,286 +13,26 @@
 require "socket"
 require "singleton"
 
+require_relative "connection"
+
 # = D-Bus main module
 #
 # Module containing all the D-Bus modules and classes.
 module DBus
-  # FIXME: rename Connection to Bus?
-
-  # D-Bus main connection class
-  #
-  # Main class that maintains a connection to a bus and can handle incoming
-  # and outgoing messages.
-  class Connection
+  # A regular Bus {Connection}.
+  # As opposed to a peer connection to a single counterparty with no daemon in between.
+  class BusConnection < Connection
     # The unique name (by specification) of the message.
     attr_reader :unique_name
-    # pop and push messages here
-    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)
-      @unique_name = nil
-
-      # @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 = {}
+    # Connect, authenticate, and send Hello.
+    # @param addresses [String]
+    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#addresses
+    def initialize(addresses)
+      super
+      @unique_name = nil
       @proxy = nil
-    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
-
-    # 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
-
-    DBUSXMLINTRO = '<!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>
-'
-    # This apostroph is for syntax highlighting editors confused by above xml: "
-
-    # @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
-    end
-
-    def handle_return_of_request_name(ret, name)
-      details = if ret == REQUEST_NAME_REPLY_IN_QUEUE
-                  other = proxy.GetNameOwner(name).first
-                  other_creds = proxy.GetConnectionCredentials(other).first
-                  "already owned by #{other}, #{other_creds.inspect}"
-                else
-                  "error code #{ret}"
-                end
-      raise NameRequestError, "Could not request #{name}, #{details}" unless ret == REQUEST_NAME_REPLY_PRIMARY_OWNER
-
-      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
+      send_hello
     end
 
     # Set up a ProxyObject for the bus itself, since the bus is introspectable.
@@ -301,10 +41,13 @@ module DBus
     # Returns the object.
     def proxy
       if @proxy.nil?
+        xml_filename = File.expand_path("org.freedesktop.DBus.xml", __dir__)
+        xml = File.read(xml_filename)
+
         path = "/org/freedesktop/DBus"
         dest = "org.freedesktop.DBus"
         pof = DBus::ProxyObjectFactory.new(
-          DBUSXMLINTRO, self, dest, path,
+          xml, self, dest, path,
           api: ApiOptions::A0
         )
         @proxy = pof.build["org.freedesktop.DBus"]
@@ -312,72 +55,126 @@ module DBus
       @proxy
     end
 
-    # @api private
-    # Wait for a message to arrive. Return it once it is available.
-    def wait_for_message
-      @message_queue.pop # FIXME: EOFError
+    # Request a well-known name so that clients can find us.
+    # @note Parameters other than *name* are advanced, you probably don't need them.
+    #
+    # With no boolean flags, running a second instance of a program that calls `request_name`
+    # will result in the second one failing, which this library translates to an exception.
+    # If you want the second instance to take over, you need both
+    # `allow_replacement: true` and `replace_existing: true.`
+    #
+    # @param name [BusName] the requested name
+    # @param replace_existing [Boolean]
+    #   Replace an existing owner of the name, if that owner set *allow_replacement*.
+    # @param allow_replacement [Boolean]
+    #   Other connections that specify *replace_existing* will be able to take
+    #   the name from us. We will get {#on_name_lost NameLost}. If we specified *queue*
+    #   we may get the name again, with {#on_name_acquired NameAcquired}.
+    # @param queue [Boolean]
+    #   Affects the behavior when the bus denies the name (sooner or later).
+    #   - If `false` (default), it is recommended to let the `NameRequestError` fall through and end your program.
+    #   - If `true`, you should `rescue` the `NameRequestError` and set up
+    #     {#on_name_acquired NameAcquired} and {#on_name_lost NameLost} handlers.
+    #     Meanwhile, the bus will put us in a queue waiting for *name* (this is the "sooner" case).
+    #     Also, if we had `allow_replacement: true`, another connection can cause us
+    #     to lose the name. We will be moved back to the queue, waiting for when the other owners give up
+    #     (the "later" case).
+    # @param flags [Integer,nil]
+    #    If specified, overrides the boolean parameters.
+    #    Use a bitwise sum `|` of:
+    #    -  NAME_FLAG_ALLOW_REPLACEMENT
+    #    -  NAME_FLAG_REPLACE_EXISTING
+    #    -  NAME_FLAG_DO_NOT_QUEUE
+    #    Note that `0` implies `queue: true`.
+    #
+    # @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
+    # @raise DBus::Error another way to fail is being prohibited to own the name
+    #   which is the default on the system bus
+    #
+    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name
+    #
+    # @example Simple usage
+    #   bus = DBus.session_bus
+    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
+    #   bus.request_name("org.example.Test")
+    #   # main loop
+    #
+    # @example Second instance taking over
+    #   bus = DBus.session_bus
+    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
+    #   bus.on_name_lost { exit }
+    #   bus.request_name("org.example.Test", allow_replacement: true, replace_existing: true)
+    #   # main loop
+    #
+    # @example Second instance waiting for its turn
+    #   bus = DBus.session_bus
+    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
+    #   bus.on_name_acquired { @owner = true }
+    #   begin
+    #     bus.request_name("org.example.Test", queue: true)
+    #   rescue DBus::Connection::NameRequestError => e
+    #     @owner = false
+    #   end
+    #   # main loop
+    def request_name(name,
+                     allow_replacement: false,
+                     replace_existing: false,
+                     queue: false,
+                     flags: nil)
+      if flags.nil?
+        flags = (allow_replacement ? NAME_FLAG_ALLOW_REPLACEMENT : 0) |
+                (replace_existing ? NAME_FLAG_REPLACE_EXISTING : 0) |
+                (queue ? 0 : NAME_FLAG_DO_NOT_QUEUE)
+      end
+      name = BusName.new(name)
+      r = proxy.RequestName(name, flags).first
+      handle_return_of_request_name(r, name)
     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
+    # The caller has released his claim on the given name.
+    # Either the caller was the primary owner of the name, and the name is now unused
+    #   or taken by somebody waiting in the queue for the name,
+    # or the caller was waiting in the queue for the name and has now been removed from the queue.
+    RELEASE_NAME_REPLY_RELEASED = 1
+    # The given name does not exist on this bus.
+    RELEASE_NAME_REPLY_NON_EXISTENT = 2
+    # The caller was not the primary owner of this name, and was also not waiting in the queue to own this name.
+    RELEASE_NAME_REPLY_NOT_OWNER = 3
+
+    # @param name [BusName] the name to release
+    def release_name(name)
+      name = BusName.new(name)
+      proxy.ReleaseName(name).first
     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
+    def on_name_acquired(&handler)
+      proxy.on_signal("NameAcquired", &handler)
+    end
 
-      @method_call_msgs[msg.serial] = msg
-      @method_call_replies[msg.serial] = retc
+    def on_name_lost(&handler)
+      proxy.on_signal("NameLost", &handler)
     end
 
     # Asks bus to send us messages matching mr, and execute slot when
     # received
     # @param match_rule [MatchRule,#to_s]
+    # @return [void]
     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 = super(mrs, &slot)
       # don't ask for the same match if we override it
-      unless @signal_matchrules.key?(mrs)
-        DBus.logger.debug "Asked for a new match"
-        proxy.AddMatch(mrs)
-      end
-      @signal_matchrules[mrs] = slot
+      return if rule_existed
+
+      DBus.logger.debug "Asked for a new match"
+      proxy.AddMatch(mrs)
     end
 
     # @param match_rule [MatchRule,#to_s]
+    # @return [void]
     def remove_match(match_rule)
       mrs = match_rule.to_s
-      rule_existed = @signal_matchrules.delete(mrs).nil?
+      rule_existed = super(mrs)
       # don't remove nonexisting matches.
       return if rule_existed
 
@@ -386,68 +183,10 @@ module DBus
       proxy.RemoveMatch(mrs)
     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
-
-    # Retrieves the Service with the given _name_.
-    # @return [Service]
+    # Makes a {ProxyService} with the given *name*.
+    # Note that this succeeds even if the name does not exist and cannot be
+    # activated. It will only fail when calling a method.
+    # @return [ProxyService]
     def service(name)
       # The service might not exist at this time so we cannot really check
       # anything
@@ -455,27 +194,6 @@ module DBus
     end
     alias [] service
 
-    # @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
-
     ###########################################################################
     private
 
@@ -493,25 +211,6 @@ module DBus
     end
   end
 
-  # A regular Bus {Connection}.
-  # As opposed to a peer connection to a single counterparty with no daemon in between.
-  # FIXME: move the remaining relevant methods from Connection here, but alias the constants
-  class BusConnection < Connection
-    # @param name [BusName] the requested name
-    # @param flags [Integer] TODO: explain and add a better non-numeric API for this
-    # @raise NameRequestError if we could not get the name
-    # @example Usage
-    #   bus = DBus.session_bus
-    #   bus.object_server.export(DBus::Object.new("/org/example/Test"))
-    #   bus.request_name("org.example.Test")
-    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name
-    def request_name(name, flags: 0)
-      name = BusName.new(name)
-      r = proxy.RequestName(name, flags).first
-      handle_return_of_request_name(r, name)
-    end
-  end
-
   # = D-Bus session bus class
   #
   # The session bus is a session specific bus (mostly for desktop use).
@@ -522,7 +221,6 @@ module DBus
     # Get the the default session bus.
     def initialize
       super(self.class.session_bus_address)
-      send_hello
     end
 
     def self.session_bus_address
@@ -573,7 +271,6 @@ module DBus
     # Get the default system bus.
     def initialize
       super(self.class.system_bus_address)
-      send_hello
     end
 
     def self.system_bus_address
@@ -593,12 +290,8 @@ module DBus
   # you'll need to take care about authentification then, more info here:
   # https://gitlab.com/pangdudu/ruby-dbus/-/blob/master/README.rdoc
   # TODO: keep the name but update the docs
+  # @deprecated just use BusConnection
   class RemoteBus < BusConnection
-    # Get the remote bus.
-    def initialize(socket_name)
-      super(socket_name)
-      send_hello
-    end
   end
 
   # See ASystemBus
@@ -607,13 +300,13 @@ module DBus
   end
 
   # Shortcut for the {SystemBus} instance
-  # @return [Connection]
+  # @return [BusConnection]
   def self.system_bus
     SystemBus.instance
   end
 
   # Shortcut for the {SessionBus} instance
-  # @return [Connection]
+  # @return [BusConnection]
   def self.session_bus
     SessionBus.instance
   end