Struct Connection

pub struct Connection<D> { /* private fields */ }

Wayland connection state.

This struct manages a buffered Wayland socket, keeps track of objects and request/event queues and dispatches object events.

Set WAYLAND_DEBUG=1 environment variable to get debug messages.

Implementations

impl<D> Connection<D>

pub fn connect() -> Result<Self, ConnectError>

Connect to a Wayland socket and create a registry.

From the Wayland Book:

To find the Unix socket to connect to, most implementations just do what libwayland does:

1. If WAYLAND_SOCKET is set, interpret it as a file descriptor number on which the connection is already established, assuming that the parent process configured the connection for us.
2. If WAYLAND_DISPLAY is set, concat with XDG_RUNTIME_DIR to form the path to the Unix socket.
3. Assume the socket name is wayland-0 and concat with XDG_RUNTIME_DIR to form the path to the Unix socket.
4. Give up.

Current implementation follows libwayland except for the step 3.

Examples found in repository

examples/list_globals.rs (line 4)

fn main() {
    let mut conn = Connection::<()>::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    for global in conn.globals() {
        println!("{} v{}", global.interface.to_string_lossy(), global.version);
    }
}

examples/output_watcher.rs (line 9)

fn main() {
    let mut conn = Connection::connect().unwrap();
    let mut state = State::default();

    conn.add_registry_cb(wl_registry_cb);

    loop {
        conn.flush(IoMode::Blocking).unwrap();
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }
}

examples/output_info.rs (line 8)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub fn connect_and_collect_globals() -> Result<(Self, Vec<GlobalArgs>), ConnectError>

👎Deprecated: use blocking_roundtrip() + bind_singleton() instead

connect and collect the initial set of advertised globals.

This will empty the event queue, so no callbacks will be called on the received globals.

pub async fn async_connect_and_collect_globals() -> Result<(Self, Vec<GlobalArgs>), ConnectError>

👎Deprecated: use async_roundtrip() + bind_singleton() instead

Available on crate feature tokio only.

Async version of connect_and_collect_globals.

pub fn registry(&self) -> WlRegistry

Get Wayland registry.

At the moment, only a single registry can be created. This might or might not change in the future, considering registries cannot be destroyed.

pub fn globals(&self) -> &[GlobalArgs]

Get a list of available globals.

The order of globals is not specified.

Note that this function has knowledge of all events received from the compositor, even the ones that had not been dispatched in dispatch_events yet.

Examples found in repository

examples/list_globals.rs (line 7)

fn main() {
    let mut conn = Connection::<()>::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    for global in conn.globals() {
        println!("{} v{}", global.interface.to_string_lossy(), global.version);
    }
}

examples/output_info.rs (line 13)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub fn bind_singleton<P: Proxy>( &mut self, version: impl VersionBounds, ) -> Result<P, BindError>

Bind a singleton global.

Use this function to only bind singleton globals. If more than one global of the requeseted interface is available, the behaviour is not specified.

Note that this function has knowledge of all events received from the compositor, even the ones that had not been dispatched in dispatch_events yet.

The version argmuent can be a:

• Number - require a specific version
• Range to inclusive (..=b - bind a version in range [1, b])
• Range inclusive (a..=b - bind a version in range [a, b])

pub fn bind_singleton_with_cb<P: Proxy, F: FnMut(EventCtx<'_, D, P>) + Send + 'static>( &mut self, version: impl VersionBounds, cb: F, ) -> Result<P, BindError>

Same as bind_singleton but also sets the callback

pub fn add_registry_cb<F: FnMut(&mut Connection<D>, &mut D, &Event) + Send + 'static>( &mut self, cb: F, )

Register a registry event callback.

In this library, wl_registry is the only object which can have any number of callbacks, which are triggered in the order in which they were added.

Panics

This method panics if called from the context of a registry callback.

Examples found in repository

examples/output_watcher.rs (line 12)

fn main() {
    let mut conn = Connection::connect().unwrap();
    let mut state = State::default();

    conn.add_registry_cb(wl_registry_cb);

    loop {
        conn.flush(IoMode::Blocking).unwrap();
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }
}

pub fn set_callback_for<P: Proxy, F: FnMut(EventCtx<'_, D, P>) + Send + 'static>( &mut self, proxy: P, cb: F, )

Set a callback for a given object.

Panics

This method panics if current set of objects does not contain an object with id identical to proxy.id(), internally stored object differs from proxy or object is dead.

It also panics if proxy is a wl_registry. Use add_registry_cb to listen to registry events.

Calling this function on a destroyed object will most likely panic, but this is not guarantied due to id-reuse.

pub fn clear_callbacks<D2>(self) -> Connection<D2>

👎Deprecated: this function is error-prone and best avoided

Remove all callbacks.

You can use this function to change the “state type” of a connection.

pub fn blocking_roundtrip(&mut self) -> Result<()>

Perform a blocking roundtrip.

This function flushes the buffer of pending requests. All received events during the roundtrip are queued.

Examples found in repository

examples/list_globals.rs (line 5)

fn main() {
    let mut conn = Connection::<()>::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    for global in conn.globals() {
        println!("{} v{}", global.interface.to_string_lossy(), global.version);
    }
}

examples/output_info.rs (line 9)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub async fn async_roundtrip(&mut self) -> Result<()>

Available on crate feature tokio only.

Async version of blocking_roundtrip.

pub fn recv_events(&mut self, mode: IoMode) -> Result<()>

Receive events from Wayland socket.

If mode is Blocking, this function will block the current thread until at least one event is read.

If mode is NonBlocking, this function will read form the socket until reading would block. If at least one event was received, Ok will be returned. Otherwise, WouldBlock will be propagated.

Regular IO errors are propagated as usual.

Examples found in repository

examples/output_watcher.rs (line 16)

fn main() {
    let mut conn = Connection::connect().unwrap();
    let mut state = State::default();

    conn.add_registry_cb(wl_registry_cb);

    loop {
        conn.flush(IoMode::Blocking).unwrap();
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }
}

examples/output_info.rs (line 27)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub async fn async_recv_events(&mut self) -> Result<()>

Available on crate feature tokio only.

Async version of recv_events.

pub fn flush(&mut self, mode: IoMode) -> Result<()>

Send the queue of pending request to the server.

Examples found in repository

examples/output_watcher.rs (line 15)

fn main() {
    let mut conn = Connection::connect().unwrap();
    let mut state = State::default();

    conn.add_registry_cb(wl_registry_cb);

    loop {
        conn.flush(IoMode::Blocking).unwrap();
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }
}

examples/output_info.rs (line 24)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub async fn async_flush(&mut self) -> Result<()>

Available on crate feature tokio only.

Async version of flush.

pub fn dispatch_events(&mut self, state: &mut D)

Empty the queue of pending events, calling a callback (if set) for each event.

Panics

This method panics if called from the context of a callback.

Examples found in repository

examples/output_watcher.rs (line 17)

fn main() {
    let mut conn = Connection::connect().unwrap();
    let mut state = State::default();

    conn.add_registry_cb(wl_registry_cb);

    loop {
        conn.flush(IoMode::Blocking).unwrap();
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }
}

examples/output_info.rs (line 28)

fn main() {
    let mut conn = Connection::connect().unwrap();
    conn.blocking_roundtrip().unwrap();

    let mut state = State {
        outputs: conn
            .globals()
            .iter()
            .filter(|g| g.is::<WlOutput>())
            .map(|g| g.clone())
            .collect::<Vec<_>>()
            .into_iter()
            .map(|g| g.bind_with_cb(&mut conn, 2..=4, wl_output_cb).unwrap())
            .map(|output| (output, OutputInfo::default()))
            .collect(),
    };

    conn.flush(IoMode::Blocking).unwrap();

    while !state.outputs.iter().all(|x| x.1.done) {
        conn.recv_events(IoMode::Blocking).unwrap();
        conn.dispatch_events(&mut state);
    }

    for (_, output) in state.outputs {
        dbg!(output);
    }
}

pub fn break_dispatch_loop(&mut self)

Call this function from a callback to break the dispatch loop.

This will cause dispatch_events to return. Events that go after current event are left in the queue.

Trait Implementations

impl<D> AsRawFd for Connection<D>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.