Struct State 

pub struct State { /* private fields */ }

The proxy state.

This type represents a connection to a server and any number of clients connected to this proxy.

This type can be constructed by using a StateBuilder.

Example

let state = State::builder(Baseline::ALL_OF_THEM).build().unwrap();
let acceptor = state.create_acceptor(1000).unwrap();
eprintln!("{}", acceptor.display());
loop {
    state.dispatch_blocking().unwrap();
}

struct StateHandlerImpl;

impl StateHandler for StateHandlerImpl {
    fn new_client(&mut self, client: &Rc<Client>) {
        eprintln!("Client connected");
        client.set_handler(ClientHandlerImpl);
        client.display().set_handler(DisplayHandler);
    }
}

struct ClientHandlerImpl;

impl ClientHandler for ClientHandlerImpl {
    fn disconnected(self: Box<Self>) {
        eprintln!("Client disconnected");
    }
}

struct DisplayHandler;

impl WlDisplayHandler for DisplayHandler {
    fn handle_get_registry(&mut self, slf: &Rc<WlDisplay>, registry: &Rc<WlRegistry>) {
        eprintln!("get_registry called");
        let _ = slf.send_get_registry(registry);
    }
}

Implementations

impl State

These functions can be used to create a new state.

pub fn builder(baseline: Baseline) -> StateBuilder

Creates a new StateBuilder.

impl State

These functions can be used to dispatch and flush messages.

pub fn dispatch_blocking(self: &Rc<Self>) -> Result<bool, StateError>

Performs a blocking dispatch.

This is a shorthand for self.dispatch(None).

pub fn dispatch_available(self: &Rc<Self>) -> Result<bool, StateError>

Performs a non-blocking dispatch.

This is a shorthand for self.dispatch(Some(Duration::from_secs(0)).

pub fn dispatch( self: &Rc<Self>, timeout: Option<Duration>, ) -> Result<bool, StateError>

Performs a dispatch.

The timeout determines how long this function will wait for new events. If the timeout is None, then it will wait indefinitely. If the timeout is 0, then it will only process currently available events.

If the timeout is not 0, then outgoing messages will be flushed before waiting.

Outgoing messages will be flushed immediately before this function returns.

The return value indicates if any work was performed.

This function is not reentrant. It should not be called from within a callback. Trying to do so will cause it to return an error immediately and the state will be otherwise unchanged.

impl State

pub fn poll_fd(&self) -> &Rc<OwnedFd>

Returns a file descriptor that can be used with epoll or similar.

If this file descriptor becomes readable, the state should be dispatched. Self::before_poll should be used before going to sleep.

This function always returns the same file descriptor.

pub fn before_poll(&self) -> Result<(), StateError>

Prepares the state for an external poll operation.

If Self::poll_fd is used, this function should be called immediately before going to sleep. Otherwise, outgoing messages might not be flushed.

loop {
    state.before_poll().unwrap();
    poll(state.poll_fd());
    state.dispatch_available().unwrap();
}

impl State

These functions can be used to manipulate objects.

pub fn create_object<P>(self: &Rc<Self>, version: u32) -> Rc<P>

where P: Object,

Creates a new object.

The new object is not associated with a client ID or a server ID. It can become associated with a client ID by sending an event with a new_id parameter. It can become associated with a server ID by sending a request with a new_id parameter.

The object can only be associated with one client at a time. The association with a client is removed when the object is used in a destructor event.

This function does not enforce that the version is less than or equal to the maximum version supported by this crate. Using a version that exceeds tha maximum supported version can cause a protocol error if the client sends a request that is not available in the maximum supported protocol version or if the server sends an event that is not available in the maximum supported protocol version.

pub fn display(self: &Rc<Self>) -> Rc<WlDisplay>

Returns a wl_display object.

pub fn set_default_forward_to_client(&self, enabled: bool)

Changes the default forward-to-client setting.

This affects objects created after this call. See ObjectCoreApi::set_forward_to_client.

pub fn set_default_forward_to_server(&self, enabled: bool)

Changes the default forward-to-server setting.

This affects objects created after this call. See ObjectCoreApi::set_forward_to_server.

impl State

These functions can be used to manage sockets associated with this state.

pub fn connect(self: &Rc<Self>) -> Result<(Rc<Client>, OwnedFd), StateError>

Creates a new connection to this proxy.

The returned file descriptor is the client end of the connection and can be used with a function such as wl_display_connect_to_fd or with the WAYLAND_SOCKET environment variable.

The StateHandler::new_client callback will not be invoked.

pub fn add_client( self: &Rc<Self>, socket: &Rc<OwnedFd>, ) -> Result<Rc<Client>, StateError>

Creates a new connection to this proxy from an existing socket.

The file descriptor should be the server end of the connection. It can be created with a function such as socketpair or by accepting a connection from a file-system socket.

The StateHandler::new_client callback will not be invoked.

pub fn create_acceptor( &self, max_tries: u32, ) -> Result<Rc<Acceptor>, StateError>

Creates a new file-system acceptor and starts listening for connections.

See Acceptor::new for the meaning of the max_tries parameter.

Calling State::dispatch will automatically accept connections from this acceptor. The StateHandler::new_client callback will be invoked when this happens.

impl State

These functions can be used to manipulate the StateHandler of this state.

These functions can be called at any time, even from within a handler callback. In that case, the handler is replaced as soon as the callback returns.

pub fn unset_handler(&self)

Unsets the handler.

pub fn set_handler(&self, handler: impl StateHandler)

Sets a new handler.

pub fn set_boxed_handler(&self, handler: Box<dyn StateHandler>)

Sets a new, already boxed handler.

impl State

These functions can be used to check the state status and to destroy the state.

pub fn is_not_destroyed(&self) -> bool

Returns whether this state is not destroyed.

This is the same as !self.is_destroyed().

pub fn is_destroyed(&self) -> bool

Returns whether the state is destroyed.

If the state is destroyed, most functions that can return an error will return an error saying that the state is already destroyed.

This function or Self::is_not_destroyed should be used before dispatching the state.

Example

while state.is_not_destroyed() {
    if let Err(e) = state.dispatch_blocking() {
        log::error!("Could not dispatch the state: {}", Report::new(e));
    }
}

pub fn destroy(&self)

Destroys this state.

This function unsets all handlers and destroys all clients. You should drop the state after calling this function.

pub fn create_destructor(self: &Rc<Self>) -> Destructor

Creates a RAII destructor for this state.

Dropping the destructor will automatically call State::destroy unless you first call Destructor::disable.

State objects contain reference cycles that must be cleared manually to release the associated resources. Dropping the State is usually not sufficient to do this. Instead, State::destroy must be called manually. This function can be used to accomplish this in an application that otherwise relies on RAII semantics.

Ensure that the destructor is itself not part of a reference cycle.

pub fn create_remote_destructor(&self) -> Result<RemoteDestructor, StateError>

Creates a Sync+Send RAII destructor for this state.

This function is similar to State::create_destructor but the returned destructor implements Sync+Send. This destructor can therefore be used to destroy states running in a different thread.