# class DBus::BusConnection

A regular Bus {Connection}. As opposed to a peer connection to a single counterparty with no daemon in between.

### Constants

RELEASE_NAME_REPLY_NON_EXISTENT

  The given name does not exist on this bus.

RELEASE_NAME_REPLY_NOT_OWNER

  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_RELEASED

  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.

### Attributes

unique_name[R]

The unique name (by specification) of the message.

### Public Class Methods

new(addresses) click to toggle source

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

Calls superclass method

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

### Public Instance Methods

[](name)
Alias for: service
add_match(match_rule, &slot) click to toggle source

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

Calls superclass method

        # 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

on_name_acquired(&handler) click to toggle source

        # File lib/dbus/bus.rb
    151 def on_name_acquired(&handler)
    152   proxy.on_signal("NameAcquired", &handler)
    153 end

on_name_lost(&handler) click to toggle source

        # File lib/dbus/bus.rb
    155 def on_name_lost(&handler)
    156   proxy.on_signal("NameLost", &handler)
    157 end

proxy() click to toggle source

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

release_name(name) click to toggle source

@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

remove_match(match_rule) click to toggle source

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

Calls superclass method

        # 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_name(name, allow_replacement: false, replace_existing: false, queue: false, flags: nil) click to toggle source

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

service(name) click to toggle source

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

Also aliased as: []

### Private Instance Methods

send_hello() click to toggle source

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