class DBus::BusConnection

Connect, authenticate, and send Hello. @param addresses [String] @see dbus.freedesktop.org/doc/dbus-specification.html#addresses

   # File lib/dbus/bus.rb
31 def initialize(addresses)
32   super
33   @unique_name = nil
34   @proxy = nil
35   send_hello
36 end

Asks bus to send us messages matching mr, and execute slot when received @param match_rule [MatchRule,#to_s] @return [void]

    # File lib/dbus/bus.rb
163 def add_match(match_rule, &slot)
164   mrs = match_rule.to_s
165   rule_existed = super(mrs, &slot)
166   # don't ask for the same match if we override it
167   return if rule_existed
168 
169   DBus.logger.debug "Asked for a new match"
170   proxy.AddMatch(mrs)
171 end

Set up a ProxyObject for the bus itself, since the bus is introspectable. @return [ProxyObject] that always returns an array

({DBus::ApiOptions#proxy_method_returns_array})

Returns the object.

   # File lib/dbus/bus.rb
42 def proxy
43   if @proxy.nil?
44     xml_filename = File.expand_path("org.freedesktop.DBus.xml", __dir__)
45     xml = File.read(xml_filename)
46 
47     path = "/org/freedesktop/DBus"
48     dest = "org.freedesktop.DBus"
49     pof = DBus::ProxyObjectFactory.new(
50       xml, self, dest, path,
51       api: ApiOptions::A0
52     )
53     @proxy = pof.build["org.freedesktop.DBus"]
54   end
55   @proxy
56 end

@param name [BusName] the name to release

    # File lib/dbus/bus.rb
146 def release_name(name)
147   name = BusName.new(name)
148   proxy.ReleaseName(name).first
149 end

@param match_rule [MatchRule,#to_s] @return [void]

    # File lib/dbus/bus.rb
175 def remove_match(match_rule)
176   mrs = match_rule.to_s
177   rule_existed = super(mrs)
178   # don't remove nonexisting matches.
179   return if rule_existed
180 
181   # FIXME: if we do try, the Error.MatchRuleNotFound is *not* raised
182   # and instead is reported as "no return code for nil"
183   proxy.RemoveMatch(mrs)
184 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 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 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

    # File lib/dbus/bus.rb
120 def request_name(name,
121                  allow_replacement: false,
122                  replace_existing: false,
123                  queue: false,
124                  flags: nil)
125   if flags.nil?
126     flags = (allow_replacement ? NAME_FLAG_ALLOW_REPLACEMENT : 0) |
127             (replace_existing ? NAME_FLAG_REPLACE_EXISTING : 0) |
128             (queue ? 0 : NAME_FLAG_DO_NOT_QUEUE)
129   end
130   name = BusName.new(name)
131   r = proxy.RequestName(name, flags).first
132   handle_return_of_request_name(r, name)
133 end

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]

    # File lib/dbus/bus.rb
190 def service(name)
191   # The service might not exist at this time so we cannot really check
192   # anything
193   ProxyService.new(name, self)
194 end

Send a hello messages to the bus to let it know we are here.

    # File lib/dbus/bus.rb
201 def send_hello
202   m = Message.new(DBus::Message::METHOD_CALL)
203   m.path = "/org/freedesktop/DBus"
204   m.destination = "org.freedesktop.DBus"
205   m.interface = "org.freedesktop.DBus"
206   m.member = "Hello"
207   send_sync(m) do |rmsg|
208     @unique_name = rmsg.destination
209     DBus.logger.debug "Got hello reply. Our unique_name is #{@unique_name}"
210   end
211 end