Struct Builder 

pub struct Builder<'a> {
    target: Option<Target>,
    max_queued: Option<usize>,
    guid: Option<Guid<'a>>,
    internal_executor: bool,
    interfaces: HashMap<ObjectPath<'a>, HashMap<InterfaceName<'static>, ArcInterface>>,
    names: HashSet<WellKnownName<'a>>,
    auth_mechanism: Option<AuthMechanism>,
    request_name_flags: BitFlags<RequestNameFlags>,
    method_timeout: Option<Duration>,
    user_id: Option<u32>,
}

A builder for zbus::Connection.

The builder allows setting the flags RequestNameFlags::AllowReplacement and RequestNameFlags::ReplaceExisting when requesting names, but the flag RequestNameFlags::DoNotQueue will always be enabled. The reasons are:

1. There is no indication given to the caller of Self::build that the name(s) request was enqueued and that the requested name might not be available right after building.

2. The name may be acquired in between the time the name is requested and the crate::fdo::NameAcquiredStream is constructed. As a result the service can miss the crate::fdo::NameAcquired signal.

Fields

target: Option<Target>

max_queued: Option<usize>

guid: Option<Guid<'a>>

internal_executor: bool

interfaces: HashMap<ObjectPath<'a>, HashMap<InterfaceName<'static>, ArcInterface>>

names: HashSet<WellKnownName<'a>>

auth_mechanism: Option<AuthMechanism>

request_name_flags: BitFlags<RequestNameFlags>

method_timeout: Option<Duration>

user_id: Option<u32>

Implementations

impl<'a> Builder<'a>

pub fn session() -> Result<Self>

Create a builder for the session/user message bus connection.

pub fn system() -> Result<Self>

Create a builder for the system-wide message bus connection.

pub fn ibus() -> Result<Self>

Create a builder for an IBus connection.

IBus (Intelligent Input Bus) is an input method framework. This method creates a builder that will query the IBus daemon for its D-Bus address using the ibus address command.

Platform Support

This method is available on Unix-like systems where IBus is installed.

Errors

Returns an error if:

• The ibus command is not found or fails to execute
• The IBus daemon is not running
• The command output cannot be parsed as a valid D-Bus address

Example

let conn = Builder::ibus()?
    .build()
    .await?;

// Use the connection to interact with IBus services

pub fn address<A>(address: A) -> Result<Self>

where A: TryInto<Address>, A::Error: Into<Error>,

Create a builder for a connection that will use the given D-Bus bus address.

Example

Here is an example of connecting to an IBus service:

let addr = "unix:\
    path=/home/zeenix/.cache/ibus/dbus-ET0Xzrk9,\
    guid=fdd08e811a6c7ebe1fef0d9e647230da";
let conn = Builder::address(addr)?
    .build()
    .await?;

// Do something useful with `conn`..

Note: The IBus address is different for each session. You can find the address for your current session using ibus address command. For a more convenient way to connect to IBus, see Builder::ibus.

pub fn unix_stream(stream: UnixStream) -> Self

Create a builder for a connection that will use the given unix stream.

If the default async-io feature is disabled, this method will expect a tokio::net::UnixStream argument.

Since tokio currently does not support Unix domain sockets on Windows, this method is not available when the tokio feature is enabled and building for Windows target.

pub fn tcp_stream(stream: TcpStream) -> Self

Create a builder for a connection that will use the given TCP stream.

If the default async-io feature is disabled, this method will expect a tokio::net::TcpStream argument.

pub fn socket<S: Into<BoxedSplit>>(socket: S) -> Self

Create a builder for a connection that will use the given socket.

pub fn authenticated_socket<S, G>(socket: S, guid: G) -> Result<Self>

where S: Into<BoxedSplit>, G: TryInto<Guid<'a>>, G::Error: Into<Error>,

Create a builder for a connection that will use the given pre-authenticated socket.

This is similar to Builder::socket, except that the socket is either already authenticated or does not require authentication.

pub fn auth_mechanism(self, auth_mechanism: AuthMechanism) -> Self

Specify the mechanism to use during authentication.

pub fn user_id(self, id: u32) -> Self

Specify the user id during authentication.

This can be useful when using AuthMechanism::External with socat to avoid the host decide what uid to use and instead provide one known to have access rights.

pub fn max_queued(self, max: usize) -> Self

Set the capacity of the main (unfiltered) queue.

Since typically you’d want to set this at instantiation time, you can set it through the builder.

Example

let conn = Builder::session()?
    .max_queued(30)
    .build()
    .await?;
assert_eq!(conn.max_queued(), 30);

// Do something useful with `conn`..

pub fn internal_executor(self, enabled: bool) -> Self

Enable or disable the internal executor thread.

The thread is enabled by default.

See Connection::executor for more details.

pub fn serve_at<P, I>(self, path: P, iface: I) -> Result<Self>

where I: Interface, P: TryInto<ObjectPath<'a>>, P::Error: Into<Error>,

Register a D-Bus Interface to be served at a given path.

This is similar to zbus::ObjectServer::at, except that it allows you to have your interfaces available immediately after the connection is established. Typically, this is exactly what you’d want. Also in contrast to zbus::ObjectServer::at, this method will replace any previously added interface with the same name at the same path.

Standard interfaces (Peer, Introspectable, Properties) are added on your behalf. If you attempt to add yours, Builder::build() will fail.

pub fn name<W>(self, well_known_name: W) -> Result<Self>

where W: TryInto<WellKnownName<'a>>, W::Error: Into<Error>,

Register a well-known name for this connection on the bus.

This is similar to zbus::Connection::request_name, except the name is requested as part of the connection setup (Builder::build), immediately after interfaces registered (through Builder::serve_at) are advertised. Typically this is exactly what you want.

The methods Builder::allow_name_replacements and Builder::replace_existing_names allow to set the zbus::fdo::RequestNameFlags used to request the name.

pub fn allow_name_replacements(self, allow_replacement: bool) -> Self

Whether the zbus::fdo::RequestNameFlags::AllowReplacement flag will be set when requesting names.

pub fn replace_existing_names(self, replace_existing: bool) -> Self

Whether the zbus::fdo::RequestNameFlags::ReplaceExisting flag will be set when requesting names.

pub fn method_timeout(self, timeout: Duration) -> Self

Set a timeout for method calls.

Method calls will return zbus::Error::InputOutput(std::io::Error(kind: ErrorKind::TimedOut)) if a client does not receive an answer from a service in time.

pub async fn build(self) -> Result<Connection>

Build the connection, consuming the builder.

Errors

Until server-side bus connection is supported, attempting to build such a connection will result in a Error::Unsupported error.

async fn build_(self, executor: Executor<'static>) -> Result<Connection>

fn new(target: Target) -> Self

async fn connect(&mut self, is_bus_conn: bool) -> Result<Authenticated>

async fn target_connect( &mut self, ) -> Result<(BoxedSplit, Option<OwnedGuid>, bool)>

Trait Implementations

impl<'a> Debug for Builder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.