1//! Interface for interacting with the Wayland protocol, client-side.
2//!
3//! ## General concepts
4//!
5//! This crate is structured around four main objects: the [`Connection`] and [`EventQueue`] structs,
6//! proxies (objects implementing the [`Proxy`] trait), and the [`Dispatch`] trait.
7//!
8//! The [`Connection`] is the heart of this crate. It represents your connection to the Wayland server, and
9//! you'll generally initialize it using the [`Connection::connect_to_env()`] method, which will
10//! attempt to open a Wayland connection following the configuration specified by the ! environment.
11//!
12//! Once you have a [`Connection`], you can create an [`EventQueue`] from it. This [`EventQueue`] will take
13//! care of processing events from the Wayland server and delivering them to your processing logic, in the form
14//! of a state struct with several [`Dispatch`] implementations (see below).
15//!
16//! Each of the Wayland objects you can manipulate is represented by a struct implementing the [`Proxy`]
17//! trait. Those structs are automatically generated from the wayland XML protocol specification. This crate
18//! provides the types generated from the core protocol in the [`protocol`] module. For other standard
19//! protocols, see the `wayland-protocols` crate.
20//!
21//! ## Event dispatching
22//!
23//! The core event dispatching logic provided by this crate is built around the [`EventQueue`] struct. In
24//! this paradigm, receiving and processing events is a two-step process:
25//!
26//! - First, events are read from the Wayland socket. For each event, the backend figures out which [`EventQueue`]
27//! manages it, and enqueues the event in an internal buffer of that queue.
28//! - Then, the [`EventQueue`] empties its internal buffer by sequentially invoking the appropriate
29//! [`Dispatch::event()`] method on the `State` value that was provided to it.
30//!
31//! The main goal of this structure is to make your `State` accessible without synchronization to most of
32//! your event-processing logic, to reduce the plumbing costs. See [`EventQueue`]'s documentation for
33//! explanations of how to use it to drive your event loop, and when and how to use multiple
34//! event queues in your app.
35//!
36//! ### The [`Dispatch`] trait and dispatch delegation
37//!
38//! In this paradigm, your `State` needs to implement `Dispatch<O, _>` for every Wayland object `O` it needs to
39//! process events for. This is ensured by the fact that, whenever creating an object using the methods on
40//! an other object, you need to pass a [`QueueHandle<State>`] from the [`EventQueue`] that will be
41//! managing the newly created object.
42//!
43//! However, implementing all those traits on your own is a lot of (often uninteresting) work. To make this
44//! easier a composition mechanism is provided using the [`delegate_dispatch!`] macro. This way, another
45//! library (such as Smithay's Client Toolkit) can provide generic [`Dispatch`] implementations that you
46//! can reuse in your own app by delegating those objects to that provided implementation. See the
47//! documentation of those traits and macro for details.
48//!
49//! ## Getting started example
50//!
51//! As an overview of how this crate is used, here is a commented example of a program that connects to the
52//! Wayland server and lists the globals this server advertised through the `wl_registry`:
53//!
54//! ```rust,no_run
55//! use wayland_client::{protocol::wl_registry, Connection, Dispatch, QueueHandle};
56//! // This struct represents the state of our app. This simple app does not
57//! // need any state, but this type still supports the `Dispatch` implementations.
58//! struct AppData;
59//!
60//! // Implement `Dispatch<WlRegistry, ()> for our state. This provides the logic
61//! // to be able to process events for the wl_registry interface.
62//! //
63//! // The second type parameter is the user-data of our implementation. It is a
64//! // mechanism that allows you to associate a value to each particular Wayland
65//! // object, and allow different dispatching logic depending on the type of the
66//! // associated value.
67//! //
68//! // In this example, we just use () as we don't have any value to associate. See
69//! // the `Dispatch` documentation for more details about this.
70//! impl Dispatch<wl_registry::WlRegistry, ()> for AppData {
71//! fn event(
72//! _state: &mut Self,
73//! _: &wl_registry::WlRegistry,
74//! event: wl_registry::Event,
75//! _: &(),
76//! _: &Connection,
77//! _: &QueueHandle<AppData>,
78//! ) {
79//! // When receiving events from the wl_registry, we are only interested in the
80//! // `global` event, which signals a new available global.
81//! // When receiving this event, we just print its characteristics in this example.
82//! if let wl_registry::Event::Global { name, interface, version } = event {
83//! println!("[{}] {} (v{})", name, interface, version);
84//! }
85//! }
86//! }
87//!
88//! // The main function of our program
89//! fn main() {
90//! // Create a Wayland connection by connecting to the server through the
91//! // environment-provided configuration.
92//! let conn = Connection::connect_to_env().unwrap();
93//!
94//! // Retrieve the WlDisplay Wayland object from the connection. This object is
95//! // the starting point of any Wayland program, from which all other objects will
96//! // be created.
97//! let display = conn.display();
98//!
99//! // Create an event queue for our event processing
100//! let mut event_queue = conn.new_event_queue();
101//! // And get its handle to associate new objects to it
102//! let qh = event_queue.handle();
103//!
104//! // Create a wl_registry object by sending the wl_display.get_registry request.
105//! // This method takes two arguments: a handle to the queue that the newly created
106//! // wl_registry will be assigned to, and the user-data that should be associated
107//! // with this registry (here it is () as we don't need user-data).
108//! let _registry = display.get_registry(&qh, ());
109//!
110//! // At this point everything is ready, and we just need to wait to receive the events
111//! // from the wl_registry. Our callback will print the advertised globals.
112//! println!("Advertised globals:");
113//!
114//! // To actually receive the events, we invoke the `roundtrip` method. This method
115//! // is special and you will generally only invoke it during the setup of your program:
116//! // it will block until the server has received and processed all the messages you've
117//! // sent up to now.
118//! //
119//! // In our case, that means it'll block until the server has received our
120//! // wl_display.get_registry request, and as a reaction has sent us a batch of
121//! // wl_registry.global events.
122//! //
123//! // `roundtrip` will then empty the internal buffer of the queue it has been invoked
124//! // on, and thus invoke our `Dispatch` implementation that prints the list of advertised
125//! // globals.
126//! event_queue.roundtrip(&mut AppData).unwrap();
127//! }
128//! ```
129//!
130//! ## Advanced use
131//!
132//! ### Bypassing [`Dispatch`]
133//!
134//! It may be that for some of your objects, handling them via the [`EventQueue`] is impractical. For example,
135//! if processing the events from those objects doesn't require accessing some global state, and/or you need to
136//! handle them in a context where cranking an event loop is impractical.
137//!
138//! In those contexts, this crate also provides some escape hatches to directly interface with the low-level
139//! APIs from `wayland-backend`, allowing you to register callbacks for those objects that will be invoked
140//! whenever they receive an event and *any* event queue from the program is being dispatched. Those
141//! callbacks are more constrained: they don't get a `&mut State` reference, and must be threadsafe. See
142//! [`Proxy::send_constructor()`] and [`ObjectData`] for details about how to
143//! assign such callbacks to objects.
144//!
145//! ### Interaction with FFI
146//!
147//! It can happen that you'll need to interact with Wayland states accross FFI. A typical example would be if
148//! you need to use the [`raw-window-handle`](https://docs.rs/raw-window-handle/) crate.
149//!
150//! In this case, you'll need to do it in two steps, by explicitly working with `wayland-backend`, adding
151//! it to your dependencies and enabling its `client_system` feature.
152//!
153//! - If you need to send pointers to FFI, you can retrive the `*mut wl_proxy` pointers from the proxies by
154//! first getting the [`ObjectId`] using the [`Proxy::id()`] method, and then
155//! using the [`ObjectId::as_ptr()`] method.
156// - If you need to receive pointers from FFI, you need to first create a
157// [`Backend`][backend::Backend] from the `*mut wl_display` using
158// [`Backend::from_external_display()`][backend::Backend::from_foreign_display()], and then
159// make it into a [`Connection`] using [`Connection::from_backend()`]. Similarly, you can make
160// [`ObjectId`]s from the `*mut wl_proxy` pointers using [`ObjectId::from_ptr()`], and then make
161// the proxies using [`Proxy::from_id()`].
162
163#![allow(clippy::needless_doctest_main)]
164#![warn(missing_docs, missing_debug_implementations)]
165#![forbid(improper_ctypes, unsafe_op_in_unsafe_fn)]
166#![cfg_attr(coverage, feature(coverage_attribute))]
167// Doc feature labels can be tested locally by running RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc -p <crate>
168#![cfg_attr(docsrs, feature(doc_auto_cfg))]
169
170use std::{
171 fmt,
172 hash::{Hash, Hasher},
173 os::unix::io::{BorrowedFd, OwnedFd},
174 sync::Arc,
175};
176use wayland_backend::{
177 client::{InvalidId, ObjectData, ObjectId, WaylandError, WeakBackend},
178 protocol::{Interface, Message},
179};
180
181mod conn;
182mod event_queue;
183pub mod globals;
184
185/// Backend reexports
186pub mod backend {
187 pub use wayland_backend::client::{
188 Backend, InvalidId, NoWaylandLib, ObjectData, ObjectId, ReadEventsGuard, WaylandError,
189 WeakBackend,
190 };
191 pub use wayland_backend::protocol;
192 pub use wayland_backend::smallvec;
193}
194
195pub use wayland_backend::protocol::WEnum;
196
197pub use conn::{ConnectError, Connection};
198pub use event_queue::{Dispatch, EventQueue, QueueFreezeGuard, QueueHandle, QueueProxyData};
199
200// internal imports for dispatching logging depending on the `log` feature
201#[cfg(feature = "log")]
202#[allow(unused_imports)]
203use log::{debug as log_debug, error as log_error, info as log_info, warn as log_warn};
204#[cfg(not(feature = "log"))]
205#[allow(unused_imports)]
206use std::{
207 eprintln as log_error, eprintln as log_warn, eprintln as log_info, eprintln as log_debug,
208};
209
210/// Generated protocol definitions
211///
212/// This module is automatically generated from the `wayland.xml` protocol specification,
213/// and contains the interface definitions for the core Wayland protocol.
214#[allow(missing_docs)]
215pub mod protocol {
216 use self::__interfaces::*;
217 use crate as wayland_client;
218 pub mod __interfaces {
219 wayland_scanner::generate_interfaces!("wayland.xml");
220 }
221 wayland_scanner::generate_client_code!("wayland.xml");
222}
223
224/// Trait representing a Wayland interface
225pub trait Proxy: Clone + std::fmt::Debug + Sized {
226 /// The event enum for this interface
227 type Event;
228 /// The request enum for this interface
229 type Request<'a>;
230
231 /// The interface description
232 fn interface() -> &'static Interface;
233
234 /// The ID of this object
235 fn id(&self) -> ObjectId;
236
237 /// The version of this object
238 fn version(&self) -> u32;
239
240 /// Checks if the Wayland object associated with this proxy is still alive
241 fn is_alive(&self) -> bool {
242 if let Some(backend) = self.backend().upgrade() {
243 backend.info(self.id()).is_ok()
244 } else {
245 false
246 }
247 }
248
249 /// Access the user-data associated with this object
250 fn data<U: Send + Sync + 'static>(&self) -> Option<&U>;
251
252 /// Access the raw data associated with this object.
253 ///
254 /// For objects created using the scanner-generated methods, this will be an instance of the
255 /// [`QueueProxyData`] type.
256 fn object_data(&self) -> Option<&Arc<dyn ObjectData>>;
257
258 /// Access the backend associated with this object
259 fn backend(&self) -> &backend::WeakBackend;
260
261 /// Create an object proxy from its ID
262 ///
263 /// Returns an error this the provided object ID does not correspond to
264 /// the `Self` interface.
265 ///
266 /// **Note:** This method is mostly meant as an implementation detail to be
267 /// used by code generated by wayland-scanner.
268 fn from_id(conn: &Connection, id: ObjectId) -> Result<Self, InvalidId>;
269
270 /// Create an inert object proxy
271 ///
272 /// **Note:** This method is mostly meant as an implementation detail to be
273 /// used by code generated by wayland-scanner.
274 fn inert(backend: backend::WeakBackend) -> Self;
275
276 /// Send a request for this object.
277 ///
278 /// It is an error to use this function on requests that create objects; use
279 /// [`send_constructor()`][Self::send_constructor()] for such requests.
280 fn send_request(&self, req: Self::Request<'_>) -> Result<(), InvalidId>;
281
282 /// Send a request for this object that creates another object.
283 ///
284 /// It is an error to use this function on requests that do not create objects; use
285 /// [`send_request()`][Self::send_request()] for such requests.
286 fn send_constructor<I: Proxy>(
287 &self,
288 req: Self::Request<'_>,
289 data: Arc<dyn ObjectData>,
290 ) -> Result<I, InvalidId>;
291
292 /// Parse a event for this object
293 ///
294 /// **Note:** This method is mostly meant as an implementation detail to be
295 /// used by code generated by wayland-scanner.
296 fn parse_event(
297 conn: &Connection,
298 msg: Message<ObjectId, OwnedFd>,
299 ) -> Result<(Self, Self::Event), DispatchError>;
300
301 /// Serialize a request for this object
302 ///
303 /// **Note:** This method is mostly meant as an implementation detail to be
304 /// used by code generated by wayland-scanner.
305 #[allow(clippy::type_complexity)]
306 fn write_request<'a>(
307 &self,
308 conn: &Connection,
309 req: Self::Request<'a>,
310 ) -> Result<(Message<ObjectId, BorrowedFd<'a>>, Option<(&'static Interface, u32)>), InvalidId>;
311
312 /// Creates a weak handle to this object
313 ///
314 /// This weak handle will not keep the user-data associated with the object alive,
315 /// and can be converted back to a full proxy using [`Weak::upgrade()`].
316 ///
317 /// This can be of use if you need to store proxies in the used data of other objects and want
318 /// to be sure to avoid reference cycles that would cause memory leaks.
319 fn downgrade(&self) -> Weak<Self> {
320 Weak { backend: self.backend().clone(), id: self.id(), _iface: std::marker::PhantomData }
321 }
322}
323
324/// Wayland dispatching error
325#[derive(Debug)]
326pub enum DispatchError {
327 /// The received message does not match the specification for the object's interface.
328 BadMessage {
329 /// The id of the target object
330 sender_id: ObjectId,
331 /// The interface of the target object
332 interface: &'static str,
333 /// The opcode number
334 opcode: u16,
335 },
336 /// The backend generated an error
337 Backend(WaylandError),
338}
339
340impl std::error::Error for DispatchError {
341 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
342 match self {
343 DispatchError::BadMessage { .. } => Option::None,
344 DispatchError::Backend(source: &WaylandError) => Some(source),
345 }
346 }
347}
348
349impl fmt::Display for DispatchError {
350 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
351 match self {
352 DispatchError::BadMessage { sender_id: &ObjectId, interface: &&'static str, opcode: &u16 } => {
353 write!(f, "Bad message for object {interface}@{sender_id} on opcode {opcode}")
354 }
355 DispatchError::Backend(source: &WaylandError) => {
356 write!(f, "Backend error: {source}")
357 }
358 }
359 }
360}
361
362impl From<WaylandError> for DispatchError {
363 fn from(source: WaylandError) -> Self {
364 DispatchError::Backend(source)
365 }
366}
367
368/// A weak handle to a Wayland object
369///
370/// This handle does not keep the underlying user data alive, and can be converted back to a full proxy
371/// using [`Weak::upgrade()`].
372#[derive(Debug, Clone)]
373pub struct Weak<I> {
374 backend: WeakBackend,
375 id: ObjectId,
376 _iface: std::marker::PhantomData<I>,
377}
378
379impl<I: Proxy> Weak<I> {
380 /// Try to upgrade with weak handle back into a full proxy.
381 ///
382 /// This will fail if either:
383 /// - the object represented by this handle has already been destroyed at the protocol level
384 /// - the Wayland connection has already been closed
385 pub fn upgrade(&self) -> Result<I, InvalidId> {
386 let backend: Backend = self.backend.upgrade().ok_or(err:InvalidId)?;
387 // Check if the object has been destroyed
388 backend.info(self.id.clone())?;
389 let conn: Connection = Connection::from_backend(backend);
390 I::from_id(&conn, self.id.clone())
391 }
392
393 /// The underlying [`ObjectId`]
394 pub fn id(&self) -> ObjectId {
395 self.id.clone()
396 }
397}
398
399impl<I> PartialEq for Weak<I> {
400 fn eq(&self, other: &Self) -> bool {
401 self.id == other.id
402 }
403}
404
405impl<I> Eq for Weak<I> {}
406
407impl<I> Hash for Weak<I> {
408 fn hash<H: Hasher>(&self, state: &mut H) {
409 self.id.hash(state);
410 }
411}
412
413impl<I: Proxy> PartialEq<I> for Weak<I> {
414 fn eq(&self, other: &I) -> bool {
415 self.id == other.id()
416 }
417}
418