pub struct Handle { /* private fields */ }
Expand description
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.
Implementations§
source§impl Handle
impl Handle
sourcepub fn downgrade(&self) -> WeakHandle
pub fn downgrade(&self) -> WeakHandle
Get a WeakHandle
from this handle
sourcepub fn object_info(&self, id: ObjectId) -> Result<ObjectInfo, InvalidId>
pub fn object_info(&self, id: ObjectId) -> Result<ObjectInfo, InvalidId>
Get the detailed protocol information about a wayland object
Returns an error if the provided object ID is no longer valid.
sourcepub fn insert_client(
&mut self,
stream: UnixStream,
data: Arc<dyn ClientData>,
) -> Result<ClientId>
pub fn insert_client( &mut self, stream: UnixStream, data: Arc<dyn ClientData>, ) -> Result<ClientId>
Initializes a connection with a client.
The data
parameter contains data that will be associated with the client.
sourcepub fn get_client(&self, id: ObjectId) -> Result<ClientId, InvalidId>
pub fn get_client(&self, id: ObjectId) -> Result<ClientId, InvalidId>
Returns the id of the client which owns the object.
sourcepub fn get_client_data(
&self,
id: ClientId,
) -> Result<Arc<dyn ClientData>, InvalidId>
pub fn get_client_data( &self, id: ClientId, ) -> Result<Arc<dyn ClientData>, InvalidId>
Returns the data associated with a client.
sourcepub fn get_client_credentials(
&self,
id: ClientId,
) -> Result<Credentials, InvalidId>
pub fn get_client_credentials( &self, id: ClientId, ) -> Result<Credentials, InvalidId>
Retrive the Credentials
of a client
sourcepub fn with_all_clients(&self, f: impl FnMut(ClientId))
pub fn with_all_clients(&self, f: impl FnMut(ClientId))
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.
sourcepub fn with_all_objects_for(
&self,
client_id: ClientId,
f: impl FnMut(ObjectId),
) -> Result<(), InvalidId>
pub fn with_all_objects_for( &self, client_id: ClientId, f: impl FnMut(ObjectId), ) -> Result<(), InvalidId>
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.
sourcepub fn object_for_protocol_id(
&self,
client_id: ClientId,
interface: &'static Interface,
protocol_id: u32,
) -> Result<ObjectId, InvalidId>
pub fn object_for_protocol_id( &self, client_id: ClientId, interface: &'static Interface, protocol_id: u32, ) -> Result<ObjectId, InvalidId>
Retrieve the ObjectId
for a wayland object given its protocol numerical ID
sourcepub fn create_object<D: 'static>(
&self,
client_id: ClientId,
interface: &'static Interface,
version: u32,
data: Arc<dyn ObjectData<D>>,
) -> Result<ObjectId, InvalidId>
pub fn create_object<D: 'static>( &self, client_id: ClientId, interface: &'static Interface, version: u32, data: Arc<dyn ObjectData<D>>, ) -> Result<ObjectId, InvalidId>
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.
sourcepub fn send_event(&self, msg: Message<ObjectId, RawFd>) -> Result<(), InvalidId>
pub fn send_event(&self, msg: Message<ObjectId, RawFd>) -> Result<(), InvalidId>
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
sourcepub fn get_object_data<D: 'static>(
&self,
id: ObjectId,
) -> Result<Arc<dyn ObjectData<D>>, InvalidId>
pub fn get_object_data<D: 'static>( &self, id: ObjectId, ) -> Result<Arc<dyn ObjectData<D>>, InvalidId>
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.
sourcepub fn get_object_data_any(
&self,
id: ObjectId,
) -> Result<Arc<dyn Any + Send + Sync>, InvalidId>
pub fn get_object_data_any( &self, id: ObjectId, ) -> Result<Arc<dyn Any + Send + Sync>, InvalidId>
Returns the data associated with an object as a dyn Any
sourcepub fn set_object_data<D: 'static>(
&self,
id: ObjectId,
data: Arc<dyn ObjectData<D>>,
) -> Result<(), InvalidId>
pub fn set_object_data<D: 'static>( &self, id: ObjectId, data: Arc<dyn ObjectData<D>>, ) -> Result<(), InvalidId>
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.
sourcepub fn post_error(&self, object_id: ObjectId, error_code: u32, message: CString)
pub fn post_error(&self, object_id: ObjectId, error_code: u32, message: CString)
Posts a protocol error on an object. This will also disconnect the client which created the object.
sourcepub fn kill_client(&self, client_id: ClientId, reason: DisconnectReason)
pub fn kill_client(&self, client_id: ClientId, reason: DisconnectReason)
Kills the connection to a client.
The disconnection reason determines the error message that is sent to the client (if any).
sourcepub fn create_global<D: 'static>(
&self,
interface: &'static Interface,
version: u32,
handler: Arc<dyn GlobalHandler<D>>,
) -> GlobalId
pub fn create_global<D: 'static>( &self, interface: &'static Interface, version: u32, handler: Arc<dyn GlobalHandler<D>>, ) -> GlobalId
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.
sourcepub fn disable_global<D: 'static>(&self, id: GlobalId)
pub fn disable_global<D: 'static>(&self, id: GlobalId)
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.
sourcepub fn remove_global<D: 'static>(&self, id: GlobalId)
pub fn remove_global<D: 'static>(&self, id: GlobalId)
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.
sourcepub fn global_info(&self, id: GlobalId) -> Result<GlobalInfo, InvalidId>
pub fn global_info(&self, id: GlobalId) -> Result<GlobalInfo, InvalidId>
Returns information about a global.
sourcepub fn get_global_handler<D: 'static>(
&self,
id: GlobalId,
) -> Result<Arc<dyn GlobalHandler<D>>, InvalidId>
pub fn get_global_handler<D: 'static>( &self, id: GlobalId, ) -> Result<Arc<dyn GlobalHandler<D>>, InvalidId>
Returns the handler which manages the visibility and notifies when a client has bound the global.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Handle
impl RefUnwindSafe for Handle
impl Send for Handle
impl Sync for Handle
impl Unpin for Handle
impl UnwindSafe for Handle
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.