      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

    //! Common definitions for wayland
    //!
    //! This crate hosts common type and traits used to represent wayland messages
    //! and routines in the `wayland-client` and `wayland-server` crates.
    //!
    //! This notably includes the `Interface` trait, which can exhaustively describe
    //! any wayland interface. Its implementations are intended to be generated by the
    //! `wayland-scanner` crate.
    //!
    //! The principal user-facing definition provided by this crate is the `Implementation`
    //! trait, which as a user of `wayland-client` or `wayland-server` you will be using
    //! to define objects able to handle the messages your program receives. Note that
    //! this trait is auto-implemented for closures with appropriate signature, for
    //! convenience.

    #![warn(missing_docs)]

    #[macro_use]
    extern crate nix;
    #[cfg(feature = "native_lib")]
    extern crate wayland_sys;
    #[cfg(feature = "native_lib")]
    use std::os::raw::c_void;
    #[cfg(feature = "native_lib")]
    use wayland_sys::common as syscom;

    pub mod map;
    pub mod socket;
    pub mod utils;
    pub mod wire;

    /// A group of messages
    ///
    /// This represents a group of message that can be serialized on the protocol wire.
    /// Typically the set of events or requests of a single interface.
    ///
    /// Implementations of this trait are supposed to be
    /// generated using the `wayland-scanner` crate.
    pub trait MessageGroup: Sized {
        /// Wire representation of this MessageGroup
        const MESSAGES: &'static [wire::MessageDesc];
        /// The wrapper type for ObjectMap allowing the mapping of Object and
        /// NewId arguments to the object map during parsing.
        type Map;
        /// The opcode of this message
        fn opcode(&self) -> u16;
        /// Whether this message is a destructor
        ///
        /// If it is, once send or receive the associated object cannot be used any more.
        fn is_destructor(&self) -> bool;
        /// Retrieve the child `Object` associated with this message if any
        fn child<Meta: self::map::ObjectMetadata>(
            opcode: u16,
            version: u32,
            meta: &Meta,
        ) -> Option<::map::Object<Meta>>;
        /// Construct a message from its raw representation
        fn from_raw(msg: wire::Message, map: &mut Self::Map) -> Result<Self, ()>;
        /// Turn this message into its raw representation
        fn into_raw(self, send_id: u32) -> wire::Message;
        #[cfg(feature = "native_lib")]
        /// Construct a message of this group from its C representation
        unsafe fn from_raw_c(obj: *mut c_void, opcode: u32, args: *const syscom::wl_argument)
            -> Result<Self, ()>;
        #[cfg(feature = "native_lib")]
        /// Build a C representation of this message
        ///
        /// It can only be accessed from the provided closure, and this consumes
        /// the message.
        fn as_raw_c_in<F, T>(self, f: F) -> T
        where
            F: FnOnce(u32, &mut [syscom::wl_argument]) -> T;
    }

    /// The description of a wayland interface
    ///
    /// Implementations of this trait are supposed to be
    /// generated using the `wayland-scanner` crate.
    pub trait Interface: 'static {
        /// Set of requests associated to this interface
        ///
        /// Requests are messages from the client to the server
        type Request: MessageGroup + 'static;
        /// Set of events associated to this interface
        ///
        /// Events are messages from the server to the client
        type Event: MessageGroup + 'static;
        /// Name of this interface
        const NAME: &'static str;
        /// Maximum supported version of this interface
        const VERSION: u32;
        #[cfg(feature = "native_lib")]
        /// Pointer to the C representation of this interface
        fn c_interface() -> *const ::syscom::wl_interface;
    }

    /// Anonymous interface
    ///
    /// A special Interface implementation representing an
    /// handle to an object for which the interface is not known.
    pub struct AnonymousObject;

    /// An empty enum representing a MessageGroup with no messages
    pub enum NoMessage {}

    impl Interface for AnonymousObject {
        type Request = NoMessage;
        type Event = NoMessage;
        const NAME: &'static str = "<anonymous>";
        const VERSION: u32 = 0;
        #[cfg(feature = "native_lib")]
        fn c_interface() -> *const ::syscom::wl_interface {
            ::std::ptr::null()
        }
    }

    #[cfg_attr(tarpaulin, skip)]
    impl MessageGroup for NoMessage {
        const MESSAGES: &'static [wire::MessageDesc] = &[];
        type Map = ();
        fn is_destructor(&self) -> bool {
            match *self {}
        }
        fn opcode(&self) -> u16 {
            match *self {}
        }
        fn child<M: self::map::ObjectMetadata>(_: u16, _: u32, _: &M) -> Option<::map::Object<M>> {
            None
        }
        fn from_raw(_: wire::Message, _: &mut ()) -> Result<Self, ()> {
            Err(())
        }
        fn into_raw(self, _: u32) -> wire::Message {
            match self {}
        }
        #[cfg(feature = "native_lib")]
        unsafe fn from_raw_c(
            _obj: *mut c_void,
            _opcode: u32,
            _args: *const syscom::wl_argument,
        ) -> Result<Self, ()> {
            Err(())
        }
        #[cfg(feature = "native_lib")]
        fn as_raw_c_in<F, T>(self, _f: F) -> T
        where
            F: FnOnce(u32, &mut [syscom::wl_argument]) -> T,
        {
            match self {}
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)