Server-side Wayland connector
This crate provides the interfaces and machinery to safely create servers
for the Wayland protocol. It can be used as either a rust implementatin of the protocol,
or as a wrapper around the system-wide
libwayland-server.so if you need interoperability
with other libraries. This last case is activated by the
use_system_lib cargo feature.
The Wayland protocol revolves around the creation of various objects and the exchange
of messages associated to these objects. Whenever a client connects, a
is automatically created in their object space, which they use as a root to create new
objects and bootstrap their state.
The protocol being bi-directional, you can send and receive messages. Sending messages is done via methods of Rust objects corresponding to the wayland protocol objects, receiving and handling them is done by providing callbacks.
The protocol and message model is very similar to the one of
wayland-client, with the
main difference being that the underlying handles to objects are represented by the
type, very similarly to proxies in
These resources are used to send messages to the client (in the Wayland context,
these are called “events”). You usually don’t use them directly, and instead call
methods on the Rust objects themselves, which invoke the appropriate
It is also possible to directly use the
There is not a 1 to 1 mapping between Rust object instances and protocol
objects. Rather, you can think of the Rust objects as
Rc-like handles to a
Wayland object. Multiple instances of a Rust object can exist referring to the same
Similarly, the lifetimes of the protocol objects and the Rust objects are
not tightly tied. As protocol objects are created and destroyed by protocol
messages, it can happen that an object gets destroyed while one or more
Rust objects still refer to it. In such case, these Rust objects will be disabled
alive() method on the underlying
Resource<I> will start to return
Events that are subsequently sent to them are ignored.
Your wayland objects can receive requests from the client, which need to be processed.
To do so, you can assign
Filters to your object. These are specially wrapped closure
so that several objects can be assigned to the same
Filter, to ease state sharing
between the code handling different objects.
All objects must be assigned to a filter, even if it is for doing nothing.
Failure to do will cause a
panic!() if a request is dispatched to the faulty object.
A Rust object passed to your implementation is guaranteed to be alive (as it just received a request), unless the exact message received is a destructor (which is indicated in the API documentations).
The core of your server is the
Display object. It represent the ability of your program to
process Wayland messages. Once this object is created, you can configure it to listen on one
or more sockets for incoming client connections (see the
Display docs for details).
wayland-server does not include an event loop, and you are expected to drive the wayland socket
yourself using the
Display::dispatch methods. The
methods provides you with a file descriptor that can be used in a polling structure to integrate
the wayland socket in an event loop.
Generate an enum joining several objects requests
A handle to a client connected to your server
Holds the client credentials the can be
retrieved from the socket with
Holder of global dispatch-related data
The wayland display
An event filter
A handle to a global object
A main handle to a proxy
An handle to a wayland resource
A handle to the object map internal to the library state
A storage able to store several values of
of different types. It behaves similarly to a
An empty enum representing a MessageGroup with no messages