ruby-dbus 0.23.0.beta2 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c671b06e04452129a899cd4b7877cf43f9c05b8e7bc6597e75bc460e250c97e7
-  data.tar.gz: 18f660c6e5804fd133cf8351d801f8e0d4e332f1473cc390bedf77341d71845d
+  metadata.gz: 46409560afa18cf728a8fdc0d5a488e69f04d3bf3c14cece10f8c14af8bc8a41
+  data.tar.gz: f0432d7e9716f8e87ce5daaf7dc581b0cf5b89c66f5e5cc3da50bb38cae85fa3
 SHA512:
-  metadata.gz: 5cff2ab01f4db3d069a73b28f46cf861dcc81302ed239a7fc4332f46a7583b2394d679d5d73ab13f080b674e46f8961c89fa3fccc58ce9043d0bd33c4c2d02c4
-  data.tar.gz: 495c060e5161c2c5267b723598d3185b14d4c6517e41504f5b49971d3c355acec1ee3ab6285b7796bb7aa8cb61dfb5bd24535a2613a9f22cfb80f65ec8a1cf49
+  metadata.gz: e98790e7cf81e2cb7bcaf3e2e39e530b99788483fd9fb583f209ce3f2a120ef381b59d3f0683c9affcef7d1475bf52f9d91e0f66004c1e78cb4fd363639698bf
+  data.tar.gz: 2660d2bf3b6a511898c13048a5548c31d04674e6ad62e13aca567b1379fed0ce48b063435c5c74a680fba649427cc3a7c802c0883a6ff433a20040129604e07c

data/NEWS.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## Ruby D-Bus 0.24.0 - 2025-01-02
+
+Bug fixes:
+ * Adapted for Ruby 3.4, which uses a single quote instead of a backtick
+   in exceptions ([#145][], by Mamoru TASAKA).
+
+[#145]: https://github.com/mvidner/ruby-dbus/pull/145
+
+## Ruby D-Bus 0.23.1 - 2023-10-03
+
+API:
+ * Add DBus::Object.dbus_reader_attr_accessor to declare a common use case
+   with a single call ([#140][]).
+ * BusConnection#request_name defaults to the simple use case: single owner
+   without queuing, failing fast; documented the complex use cases.
+
+[#140]: https://github.com/mvidner/ruby-dbus/pull/140
+
 ## Ruby D-Bus 0.23.0.beta2 - 2023-06-23
 
 License:

data/VERSION

@@ -1 +1 @@
-0.23.0.beta2
+0.24.0

data/examples/utils/listnames.rb

@@ -8,4 +8,12 @@ d = if ARGV.member?("--system")
     else
       DBus::SessionBus.instance
     end
-d.proxy.ListNames[0].each { |n| puts "\t#{n}" }
+d.proxy.ListNames[0].each do |n|
+  puts "\t#{n}"
+  qns = d.proxy.ListQueuedOwners(n)[0]
+  next if qns.size == 1 && qns.first == n
+
+  qns.each do |qn|
+    puts "\t\t#{qn}"
+  end
+end

data/lib/dbus/bus.rb

@@ -55,20 +55,107 @@ module DBus
       @proxy
     end
 
+    # 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 flags [Integer] TODO: explain and add a better non-numeric API for this
-    # @raise NameRequestError if we could not get the name
-    # @example Usage
+    # @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")
-    # @see https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name
-    def request_name(name, flags: 0)
+    #   # 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
 
+    # 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
+
+    def on_name_acquired(&handler)
+      proxy.on_signal("NameAcquired", &handler)
+    end
+
+    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]

data/lib/dbus/connection.rb

@@ -153,17 +153,30 @@ module DBus
 
     # 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)
-      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
+      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

data/lib/dbus/object.rb

@@ -156,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)
@@ -213,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)

data/lib/dbus/proxy_object.rb

@@ -33,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)
@@ -58,7 +60,7 @@ 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
@@ -127,7 +129,8 @@ module DBus
     # @return [void]
     def on_signal(name, &block)
       unless @default_iface && has_iface?(@default_iface)
-        raise NoMethodError, "undefined signal `#{name}' for DBus interface `#{@default_iface}' on object `#{@path}'"
+        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)
@@ -151,7 +154,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
@@ -159,10 +163,11 @@ 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
     # rubocop:enable Lint/MissingSuper

data/ruby-dbus.gemspec

@@ -28,6 +28,8 @@ GEMSPEC = Gem::Specification.new do |s|
   s.add_runtime_dependency "rexml"
   # s.add_runtime_dependency "nokogiri"
 
+  # workaround: rubocop-1.0 needs base64 which is no longer in stdlib in newer rubies
+  s.add_development_dependency "base64"
   s.add_development_dependency "packaging_rake_tasks"
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec", "~> 3"

data/spec/bus_connection_spec.rb

@@ -21,7 +21,6 @@ describe DBus::BusConnection do
     end
 
     context "when the name is taken already", tag_service: true do
-      # formerly it returned Service, now ObjectServer takes its role
       it "raises NameRequestError... too late" do
         name = "org.ruby.service"
         expect do
@@ -50,21 +49,35 @@ describe DBus::BusConnection do
 
   describe "#request_name", tag_bus: true do
     context "when the name request succeeds" do
-      it "returns something which can export objects" do
+      it "returns a success code" do
         name = "org.rubygems.ruby_dbus.RequestNameTest"
-        expect { bus.request_name(name) }.to_not raise_error
-        bus.proxy.ReleaseName(name)
+        expect(bus.request_name(name)).to eq DBus::Connection::REQUEST_NAME_REPLY_PRIMARY_OWNER
+        # second time, considered also a success
+        expect(bus.request_name(name)).to eq DBus::Connection::REQUEST_NAME_REPLY_ALREADY_OWNER
+        bus.release_name(name)
       end
     end
 
     context "when the name is taken already", tag_service: true do
-      # formerly it returned Service, now ObjectServer takes its role
       it "raises NameRequestError" do
         name = "org.ruby.service"
         expect do
-          # flags: avoid getting the name sometime later, unexpectedly
-          bus.request_name(name, flags: DBus::Connection::NAME_FLAG_DO_NOT_QUEUE)
+          bus.request_name(name)
+        end.to raise_error(DBus::Connection::NameRequestError)
+      end
+    end
+
+    context "when the name is taken already but we request queuing", tag_service: true do
+      it "raises NameRequestError but we are queued" do
+        name = "org.ruby.service"
+        owning = nil
+        # TODO: we do not expect the handlers to run
+        bus.on_name_acquired { owning = true }
+        bus.on_name_lost { owning = false }
+        expect do
+          bus.request_name(name, queue: true)
         end.to raise_error(DBus::Connection::NameRequestError)
+        expect(bus.release_name(name)).to eq DBus::BusConnection::RELEASE_NAME_REPLY_RELEASED
       end
     end
 

data/spec/mock-service/spaghetti-monster.rb

@@ -23,7 +23,7 @@ class TestChild < DBus::Object
   end
 
   dbus_interface "org.ruby.TestChild" do
-    dbus_attr_reader :name, "s"
+    dbus_reader_attr_accessor :name, "s"
   end
 end
 

data/spec/signal_spec.rb

@@ -107,9 +107,10 @@ describe "SignalHandlerTest" do
   describe DBus::ProxyObject do
     describe "#on_signal" do
       it "raises a descriptive error when the default_iface is wrong" do
+        open_quote = RUBY_VERSION >= "3.4" ? "'" : "`"
         @obj.default_iface = "org.ruby.NoSuchInterface"
         expect { @obj.on_signal("Foo") {} }
-          .to raise_error(NoMethodError, /undefined signal.*interface `org.ruby.NoSuchInterface'/)
+          .to raise_error(NoMethodError, /undefined signal.*interface #{open_quote}org.ruby.NoSuchInterface'/)
       end
     end
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-dbus
 version: !ruby/object:Gem::Version
-  version: 0.23.0.beta2
+  version: 0.24.0
 platform: ruby
 authors:
 - Ruby DBus Team
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2025-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rexml
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: packaging_rake_tasks
   requirement: !ruby/object:Gem::Requirement
@@ -224,7 +237,6 @@ homepage: https://github.com/mvidner/ruby-dbus
 licenses:
 - LGPL-2.1-or-later
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -235,12 +247,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Ruby module for interaction with D-Bus
 test_files: []