[][src]Crate wayland_server

Server-side Wayland connector

Overview

This crate provides the interfaces and machinery to safely create servers for the wayland protocol. It is a rust wrapper around the libwayland-server.so C library.

The wayland protocol revolves around the creation of various objects and the exchange of messages associated to these objects. Whenever a client connects, a Display object is automatically created in their object space, which they use as a root to create new objects and bootstrap their state.

Protocol and messages handling model

The protocol being bi-directional, you can send and receive messages. Sending messages is done via methods of Resource<_> objects, receiving and handling them is done by providing implementations.

Resources

The protocol and message model is very similar to the one of wayland-client, with the main difference being that the handles to objects are represented by the Resource<I> type.

These resources are used to send messages to the clients (they are called "events" in the wayland context). This is done by the Resource::<I>::send(..) method.

There is not a 1 to 1 mapping between Resource<I> instances and protocol objects. Rather, you can think of Resource<I> as an Rc-like handle to a wayland object. Multiple instances of it can exist referring to the same protocol object.

Similarly, the lifetimes of the protocol objects and the Resource<I> 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 Resource<I> still refers to it. In such case, these resources will be disabled and their alive() method will start to return false. Events that are subsequently sent to them are ignored.

Implementations

To receive and process messages from the clients to you (in wayland context they are called "requests"), you need to provide an Implementation for each wayland object created in the protocol session. Whenever a new protocol object is created, you will receive a NewResource<I> object. Providing an implementation via its implement() method will turn it into a regular Resource<I> object.

All objects must be implemented, even if it is an implementation doing nothing. Failure to do so (by dropping the NewResource<I> for example) can cause future fatal protocol errors if the client tries to send a request to this object.

An implementation is just an FnMut(I::Request, Resource<I>) where I is the interface of the considered object.

The Resource<I> 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).

Event loops and general structure

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).

To properly function, this wayland implementation also needs an event loop structure, which is here provided by the calloop crate. It is a public dependency and is reexported as wayland_server::calloop.

Re-exports

pub extern crate calloop;

Modules

protocol

Generated interfaces for the core wayland protocol

Structs

AnonymousObject

Anonymous interface

Client

A handle to a client connected to your server

Display

The wayland display

DisplayToken

A token that is required for providing non-Send implementations to resources

Global

A handle to a global object

NewResource

A newly-created resource that needs implementation

Resource

An handle to a wayland resource

ResourceMap

A handle to the object map internal to the lib state

UserDataMap

A storage able to store several values of UserData of different types. It behaves similarly to a TypeMap.

Enums

NoMessage

An empty enum representing a MessageGroup with no messages

Traits

Interface

The description of a wayland interface

MessageGroup

A group of messages