wayland_backend/
server_api.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
use std::{
    ffi::CString,
    fmt,
    os::unix::{
        io::{BorrowedFd, OwnedFd, RawFd},
        net::UnixStream,
    },
    sync::Arc,
};

use crate::protocol::{Interface, Message, ObjectInfo};
pub use crate::types::server::{Credentials, DisconnectReason, GlobalInfo, InitError, InvalidId};

use super::server_impl;

/// A trait representing your data associated to an object
///
/// You will only be given access to it as a `&` reference, so you
/// need to handle interior mutability by yourself.
///
/// The methods of this trait will be invoked internally every time a
/// new object is created to initialize its data.
pub trait ObjectData<D>: downcast_rs::DowncastSync {
    /// Dispatch a request for the associated object
    ///
    /// If the request has a `NewId` argument, the callback must return the object data
    /// for the newly created object
    fn request(
        self: Arc<Self>,
        handle: &Handle,
        data: &mut D,
        client_id: ClientId,
        msg: Message<ObjectId, OwnedFd>,
    ) -> Option<Arc<dyn ObjectData<D>>>;
    /// Notification that the object has been destroyed and is no longer active
    fn destroyed(
        self: Arc<Self>,
        handle: &Handle,
        data: &mut D,
        client_id: ClientId,
        object_id: ObjectId,
    );
    /// Helper for forwarding a Debug implementation of your `ObjectData` type
    ///
    /// By default will just print `ObjectData { ... }`
    #[cfg_attr(coverage, coverage(off))]
    fn debug(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ObjectData").finish_non_exhaustive()
    }
}

downcast_rs::impl_downcast!(sync ObjectData<D>);

impl<D: 'static> std::fmt::Debug for dyn ObjectData<D> {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.debug(f)
    }
}

/// A trait representing the handling of new bound globals
pub trait GlobalHandler<D>: downcast_rs::DowncastSync {
    /// Check if given client is allowed to interact with given global
    ///
    /// If this function returns false, the client will not be notified of the existence
    /// of this global, and any attempt to bind it will result in a protocol error as if
    /// the global did not exist.
    ///
    /// Default implementation always return true.
    fn can_view(
        &self,
        _client_id: ClientId,
        _client_data: &Arc<dyn ClientData>,
        _global_id: GlobalId,
    ) -> bool {
        true
    }
    /// A global has been bound
    ///
    /// Given client bound given global, creating given object.
    ///
    /// The method must return the object data for the newly created object.
    fn bind(
        self: Arc<Self>,
        handle: &Handle,
        data: &mut D,
        client_id: ClientId,
        global_id: GlobalId,
        object_id: ObjectId,
    ) -> Arc<dyn ObjectData<D>>;
    /// Helper for forwarding a Debug implementation of your `GlobalHandler` type
    ///
    /// By default will just print `GlobalHandler { ... }`
    #[cfg_attr(coverage, coverage(off))]
    fn debug(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("GlobalHandler").finish_non_exhaustive()
    }
}

impl<D: 'static> std::fmt::Debug for dyn GlobalHandler<D> {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.debug(f)
    }
}

downcast_rs::impl_downcast!(sync GlobalHandler<D>);

/// A trait representing your data associated to a client
pub trait ClientData: downcast_rs::DowncastSync {
    /// Notification that the client was initialized
    fn initialized(&self, _client_id: ClientId) {}
    /// Notification that the client is disconnected
    fn disconnected(&self, _client_id: ClientId, _reason: DisconnectReason) {}
    /// Helper for forwarding a Debug implementation of your `ClientData` type
    ///
    /// By default will just print `GlobalHandler { ... }`
    #[cfg_attr(coverage, coverage(off))]
    fn debug(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ClientData").finish_non_exhaustive()
    }
}

impl std::fmt::Debug for dyn ClientData {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.debug(f)
    }
}

impl ClientData for () {}

downcast_rs::impl_downcast!(sync ClientData);

/// An ID representing a Wayland object
///
/// The backend internally tracks which IDs are still valid, invalidates them when the protocol object they
/// represent is destroyed. As such even though the Wayland protocol reuses IDs, you still confidently compare
/// two `ObjectId` for equality, they will only compare as equal if they both represent the same protocol
/// object from the same client.
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct ObjectId {
    pub(crate) id: server_impl::InnerObjectId,
}

impl ObjectId {
    /// Returns whether this object is a null object.
    ///
    /// **Note:** This is not the same as checking if the ID is still valid, which cannot be done without the
    /// [`Backend`]. A null ID is the ID equivalent of a null pointer: it never has been valid and never will
    /// be.
    pub fn is_null(&self) -> bool {
        self.id.is_null()
    }

    /// Returns an object id that represents a null object.
    ///
    /// This object ID is always invalid, and should be used for events with an optional `Object` argument.
    #[inline]
    pub fn null() -> ObjectId {
        server_impl::InnerHandle::null_id()
    }

    /// Returns the interface of this object.
    pub fn interface(&self) -> &'static Interface {
        self.id.interface()
    }

    /// Check if two object IDs are associated with the same client
    ///
    /// *Note:* This may spuriously return `false` if one (or both) of the objects to compare
    /// is no longer valid.
    pub fn same_client_as(&self, other: &Self) -> bool {
        self.id.same_client_as(&other.id)
    }

    /// Return the protocol-level numerical ID of this object
    ///
    /// Protocol IDs are reused after object destruction and each client has its own ID space, so this should
    /// not be used as a unique identifier, instead use the `ObjectId` directly, it implements `Clone`,
    /// `PartialEq`, `Eq` and `Hash`.
    pub fn protocol_id(&self) -> u32 {
        self.id.protocol_id()
    }
}

impl fmt::Display for ObjectId {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.id.fmt(f)
    }
}

impl fmt::Debug for ObjectId {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.id.fmt(f)
    }
}

/// An ID representing a Wayland client
///
/// The backend internally tracks which IDs are still valid, invalidates them when the client they represent
/// is disconnected. As such you can confidently compare two `ClientId` for equality, they will only compare
/// as equal if they both represent the same client.
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct ClientId {
    pub(crate) id: server_impl::InnerClientId,
}

impl fmt::Debug for ClientId {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.id.fmt(f)
    }
}

/// An Id representing a global
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct GlobalId {
    pub(crate) id: server_impl::InnerGlobalId,
}

impl fmt::Debug for GlobalId {
    #[cfg_attr(coverage, coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.id.fmt(f)
    }
}

/// Main handle of a backend to the Wayland protocol
///
/// This type hosts most of the protocol-related functionality of the backend, and is the
/// main entry point for manipulating Wayland objects. It can be retrieved from the backend via
/// [`Backend::handle()`] and cloned, and is given to you as argument in many callbacks.
#[derive(Clone, Debug)]
pub struct Handle {
    pub(crate) handle: server_impl::InnerHandle,
}

/// A weak reference to a [`Handle`]
///
/// This handle behaves similarly to [`Weak`][std::sync::Weak], and can be used to keep access to
/// the handle without actually preventing it from being dropped.
#[derive(Clone, Debug)]
pub struct WeakHandle {
    pub(crate) handle: server_impl::WeakInnerHandle,
}

impl WeakHandle {
    /// Try to upgrade this weak handle to a [`Handle`]
    ///
    /// Returns [`None`] if the associated backend was already dropped.
    #[inline]
    pub fn upgrade(&self) -> Option<Handle> {
        self.handle.upgrade().map(|handle| Handle { handle })
    }
}

impl Handle {
    /// Get a [`WeakHandle`] from this handle
    #[inline]
    pub fn downgrade(&self) -> WeakHandle {
        WeakHandle { handle: self.handle.downgrade() }
    }

    /// Get the detailed protocol information about a wayland object
    ///
    /// Returns an error if the provided object ID is no longer valid.
    #[inline]
    pub fn object_info(&self, id: ObjectId) -> Result<ObjectInfo, InvalidId> {
        self.handle.object_info(id.id)
    }

    /// Initializes a connection with a client.
    ///
    /// The `data` parameter contains data that will be associated with the client.
    #[inline]
    pub fn insert_client(
        &mut self,
        stream: UnixStream,
        data: Arc<dyn ClientData>,
    ) -> std::io::Result<ClientId> {
        Ok(ClientId { id: self.handle.insert_client(stream, data)? })
    }

    /// Returns the id of the client which owns the object.
    #[inline]
    pub fn get_client(&self, id: ObjectId) -> Result<ClientId, InvalidId> {
        self.handle.get_client(id.id)
    }

    /// Returns the data associated with a client.
    #[inline]
    pub fn get_client_data(&self, id: ClientId) -> Result<Arc<dyn ClientData>, InvalidId> {
        self.handle.get_client_data(id.id)
    }

    /// Retrive the [`Credentials`] of a client
    #[inline]
    pub fn get_client_credentials(&self, id: ClientId) -> Result<Credentials, InvalidId> {
        self.handle.get_client_credentials(id.id)
    }

    /// Invokes a closure for all clients connected to this server
    ///
    /// Note that while this method is running, an internal lock of the backend is held,
    /// as a result invoking other methods of the `Handle` within the closure will deadlock.
    /// You should thus store the relevant `ClientId` in a container of your choice and process
    /// them after this method has returned.
    #[inline]
    pub fn with_all_clients(&self, f: impl FnMut(ClientId)) {
        self.handle.with_all_clients(f)
    }

    /// Invokes a closure for all objects owned by a client.
    ///
    /// Note that while this method is running, an internal lock of the backend is held,
    /// as a result invoking other methods of the `Handle` within the closure will deadlock.
    /// You should thus store the relevant `ObjectId` in a container of your choice and process
    /// them after this method has returned.
    #[inline]
    pub fn with_all_objects_for(
        &self,
        client_id: ClientId,
        f: impl FnMut(ObjectId),
    ) -> Result<(), InvalidId> {
        self.handle.with_all_objects_for(client_id.id, f)
    }

    /// Retrieve the `ObjectId` for a wayland object given its protocol numerical ID
    #[inline]
    pub fn object_for_protocol_id(
        &self,
        client_id: ClientId,
        interface: &'static Interface,
        protocol_id: u32,
    ) -> Result<ObjectId, InvalidId> {
        self.handle.object_for_protocol_id(client_id.id, interface, protocol_id)
    }

    /// Create a new object for given client
    ///
    /// To ensure state coherence of the protocol, the created object should be immediately
    /// sent as a "New ID" argument in an event to the client.
    ///
    /// # Panics
    ///
    /// This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn create_object<D: 'static>(
        &self,
        client_id: ClientId,
        interface: &'static Interface,
        version: u32,
        data: Arc<dyn ObjectData<D>>,
    ) -> Result<ObjectId, InvalidId> {
        self.handle.create_object(client_id.id, interface, version, data)
    }

    /// Send an event to the client
    ///
    /// Returns an error if the sender ID of the provided message is no longer valid.
    ///
    /// # Panics
    ///
    /// Checks against the protocol specification are done, and this method will panic if they do
    /// not pass:
    ///
    /// - the message opcode must be valid for the sender interface
    /// - the argument list must match the prototype for the message associated with this opcode
    #[inline]
    pub fn send_event(&self, msg: Message<ObjectId, RawFd>) -> Result<(), InvalidId> {
        self.handle.send_event(msg)
    }

    /// Returns the data associated with an object.
    ///
    /// **Panic:** This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn get_object_data<D: 'static>(
        &self,
        id: ObjectId,
    ) -> Result<Arc<dyn ObjectData<D>>, InvalidId> {
        self.handle.get_object_data(id.id)
    }

    /// Returns the data associated with an object as a `dyn Any`
    #[inline]
    pub fn get_object_data_any(
        &self,
        id: ObjectId,
    ) -> Result<Arc<dyn std::any::Any + Send + Sync>, InvalidId> {
        self.handle.get_object_data_any(id.id)
    }

    /// Sets the data associated with some object.
    ///
    /// **Panic:** This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn set_object_data<D: 'static>(
        &self,
        id: ObjectId,
        data: Arc<dyn ObjectData<D>>,
    ) -> Result<(), InvalidId> {
        self.handle.set_object_data(id.id, data)
    }

    /// Posts a protocol error on an object. This will also disconnect the client which created the object.
    #[inline]
    pub fn post_error(&self, object_id: ObjectId, error_code: u32, message: CString) {
        self.handle.post_error(object_id.id, error_code, message)
    }

    /// Kills the connection to a client.
    ///
    /// The disconnection reason determines the error message that is sent to the client (if any).
    #[inline]
    pub fn kill_client(&self, client_id: ClientId, reason: DisconnectReason) {
        self.handle.kill_client(client_id.id, reason)
    }

    /// Creates a global of the specified interface and version and then advertises it to clients.
    ///
    /// The clients which the global is advertised to is determined by the implementation of the [`GlobalHandler`].
    ///
    /// **Panic:** This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn create_global<D: 'static>(
        &self,
        interface: &'static Interface,
        version: u32,
        handler: Arc<dyn GlobalHandler<D>>,
    ) -> GlobalId {
        GlobalId { id: self.handle.create_global(interface, version, handler) }
    }

    /// Disables a global object that is currently active.
    ///
    /// The global removal will be signaled to all currently connected clients. New clients will not know of
    /// the global, but the associated state and callbacks will not be freed. As such, clients that still try
    /// to bind the global afterwards (because they have not yet realized it was removed) will succeed.
    ///
    /// Invoking this method on an already disabled or removed global does nothing. It is not possible to
    /// re-enable a disabled global, this method is meant to be invoked some time before actually removing
    /// the global, to avoid killing clients because of a race.
    ///
    /// **Panic:** This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn disable_global<D: 'static>(&self, id: GlobalId) {
        self.handle.disable_global::<D>(id.id)
    }

    /// Removes a global object and free its ressources.
    ///
    /// The global object will no longer be considered valid by the server, clients trying to bind it will be
    /// killed, and the global ID is freed for re-use.
    ///
    /// It is advised to first disable a global and wait some amount of time before removing it, to ensure all
    /// clients are correctly aware of its removal. Note that clients will generally not expect globals that
    /// represent a capability of the server to be removed, as opposed to globals representing peripherals
    /// (like `wl_output` or `wl_seat`).
    ///
    /// This methods does nothing if the provided `GlobalId` corresponds to an already removed global.
    ///
    /// **Panic:** This method will panic if the type parameter `D` is not same to the same type as the
    /// one the backend was initialized with.
    #[inline]
    pub fn remove_global<D: 'static>(&self, id: GlobalId) {
        self.handle.remove_global::<D>(id.id)
    }

    /// Returns information about a global.
    #[inline]
    pub fn global_info(&self, id: GlobalId) -> Result<GlobalInfo, InvalidId> {
        self.handle.global_info(id.id)
    }

    /// Returns the handler which manages the visibility and notifies when a client has bound the global.
    #[inline]
    pub fn get_global_handler<D: 'static>(
        &self,
        id: GlobalId,
    ) -> Result<Arc<dyn GlobalHandler<D>>, InvalidId> {
        self.handle.get_global_handler(id.id)
    }

    /// Flushes pending events destined for a client.
    ///
    /// If no client is specified, all pending events are flushed to all clients.
    pub fn flush(&mut self, client: Option<ClientId>) -> std::io::Result<()> {
        self.handle.flush(client)
    }
}

/// A backend object that represents the state of a wayland server.
///
/// A backend is used to drive a wayland server by receiving requests, dispatching messages to the appropriate
/// handlers and flushes requests to be sent back to the client.
#[derive(Debug)]
pub struct Backend<D: 'static> {
    pub(crate) backend: server_impl::InnerBackend<D>,
}

impl<D> Backend<D> {
    /// Initialize a new Wayland backend
    #[inline]
    pub fn new() -> Result<Self, InitError> {
        Ok(Self { backend: server_impl::InnerBackend::new()? })
    }

    /// Flushes pending events destined for a client.
    ///
    /// If no client is specified, all pending events are flushed to all clients.
    #[inline]
    pub fn flush(&mut self, client: Option<ClientId>) -> std::io::Result<()> {
        self.backend.flush(client)
    }

    /// Returns a handle which represents the server side state of the backend.
    ///
    /// The handle provides a variety of functionality, such as querying information about wayland objects,
    /// obtaining data associated with a client and it's objects, and creating globals.
    #[inline]
    pub fn handle(&self) -> Handle {
        self.backend.handle()
    }

    /// Returns the underlying file descriptor.
    ///
    /// The file descriptor may be monitored for activity with a polling mechanism such as epoll or kqueue.
    /// When it becomes readable, this means there are pending messages that would be dispatched if you call
    /// [`Backend::dispatch_all_clients`].
    ///
    /// The file descriptor should not be used for any other purpose than monitoring it.
    #[inline]
    pub fn poll_fd(&self) -> BorrowedFd {
        self.backend.poll_fd()
    }

    /// Dispatches all pending messages from the specified client.
    ///
    /// This method will not block if there are no pending messages.
    ///
    /// The provided `data` will be provided to the handler of messages received from the client.
    ///
    /// For performance reasons, use of this function should be integrated with an event loop, monitoring
    /// the file descriptor associated with the client and only calling this method when messages are
    /// available.
    ///
    /// **Note:** This functionality is currently only available on the rust backend, invoking this method on
    /// the system backend will do the same as invoking
    /// [`Backend::dispatch_all_clients()`].
    #[inline]
    pub fn dispatch_single_client(
        &mut self,
        data: &mut D,
        client_id: ClientId,
    ) -> std::io::Result<usize> {
        self.backend.dispatch_client(data, client_id.id)
    }

    /// Dispatches all pending messages from all clients.
    ///
    /// This method will not block if there are no pending messages.
    ///
    /// The provided `data` will be provided to the handler of messages received from the clients.
    ///
    /// For performance reasons, use of this function should be integrated with an event loop, monitoring the
    /// file descriptor retrieved by [`Backend::poll_fd`] and only calling this method when messages are
    /// available.
    #[inline]
    pub fn dispatch_all_clients(&mut self, data: &mut D) -> std::io::Result<usize> {
        self.backend.dispatch_all_clients(data)
    }
}

// Workaround: Some versions of rustc throw a `struct is never constructed`-warning here,
// if the `server_system`-feature is enabled, even though the `rs`-module makes use if it.
#[allow(dead_code)]
pub(crate) struct DumbObjectData;

#[allow(dead_code)]
impl<D> ObjectData<D> for DumbObjectData {
    #[cfg_attr(coverage, coverage(off))]
    fn request(
        self: Arc<Self>,
        _handle: &Handle,
        _data: &mut D,
        _client_id: ClientId,
        _msg: Message<ObjectId, OwnedFd>,
    ) -> Option<Arc<dyn ObjectData<D>>> {
        unreachable!()
    }

    #[cfg_attr(coverage, coverage(off))]
    fn destroyed(
        self: Arc<Self>,
        _handle: &Handle,
        _: &mut D,
        _client_id: ClientId,
        _object_id: ObjectId,
    ) {
    }
}