hjkl-clipboard 0.40.0

Cross-platform clipboard library with rich types, async support, and OSC 52 fallback for SSH
Documentation 
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

//! Backend trait and platform probe.
//!
//! Each platform module implements [`Backend`]. [`crate::Clipboard::new`]
//! selects the best available backend at runtime; [`crate::Clipboard::with_backend`]
//! lets callers inject any `Box<dyn Backend>` (mocks, decorators, custom impls).

#[cfg(target_os = "linux")]
pub(crate) mod dlopen;
#[cfg(target_os = "macos")]
pub(crate) mod macos;
pub mod mock;
pub(crate) mod osc52;
pub mod ssh_aware;
#[cfg(target_os = "linux")]
pub(crate) mod wayland;
#[cfg(target_os = "linux")]
pub mod wayland_backend;
#[cfg(target_os = "linux")]
pub(crate) mod wayland_socket;
#[cfg(target_os = "linux")]
pub(crate) mod wayland_thread;
#[cfg(target_os = "linux")]
pub(crate) mod wayland_wire;
#[cfg(target_os = "windows")]
pub(crate) mod windows;
#[cfg(target_os = "linux")]
pub(crate) mod x11;
#[cfg(target_os = "linux")]
pub mod x11_backend;
#[cfg(target_os = "linux")]
pub(crate) mod x11_thread;

use crate::{BackendKind, Capabilities, ClipboardError, MimeType, Selection};
use async_trait::async_trait;

/// Trait implemented by every clipboard backend.
///
/// Sync methods are required; async methods default to
/// [`ClipboardError::UnsupportedAsync`] so backends can opt into async
/// incrementally. Check
/// [`capabilities`][Backend::capabilities] for `ASYNC_*` flags before calling
/// async variants.
///
/// Implementations must be `Send + Sync + 'static` so they can be stored in
/// `Box<dyn Backend>` and shared across threads.
#[async_trait]
pub trait Backend: Send + Sync + 'static {
    /// Stable identifier for diagnostics + status display.
    fn kind(&self) -> BackendKind;

    /// Capability bitmask. Callers should check before invoking methods that
    /// might return `UnsupportedMime` / `UnsupportedAsync`.
    fn capabilities(&self) -> Capabilities;

    /// Write `bytes` to `sel` as `mime`. Sync.
    fn set(&self, sel: Selection, mime: MimeType, bytes: &[u8]) -> Result<(), ClipboardError>;

    /// Read the current contents of `sel` as `mime`. Sync.
    fn get(&self, sel: Selection, mime: MimeType) -> Result<Vec<u8>, ClipboardError>;

    /// Clear `sel`. Sync.
    fn clear(&self, sel: Selection) -> Result<(), ClipboardError>;

    /// Return MIME types currently available in `sel`. Sync.
    fn available(&self, sel: Selection) -> Result<Vec<MimeType>, ClipboardError>;

    /// Async version of [`set`][Backend::set]. Default returns
    /// [`UnsupportedAsync`][ClipboardError::UnsupportedAsync].
    async fn set_async(
        &self,
        _sel: Selection,
        _mime: MimeType,
        _bytes: Vec<u8>,
    ) -> Result<(), ClipboardError> {
        Err(ClipboardError::UnsupportedAsync)
    }

    /// Async version of [`get`][Backend::get]. Default returns
    /// [`UnsupportedAsync`][ClipboardError::UnsupportedAsync].
    async fn get_async(&self, _sel: Selection, _mime: MimeType) -> Result<Vec<u8>, ClipboardError> {
        Err(ClipboardError::UnsupportedAsync)
    }

    /// Async version of [`clear`][Backend::clear]. Default returns
    /// [`UnsupportedAsync`][ClipboardError::UnsupportedAsync].
    async fn clear_async(&self, _sel: Selection) -> Result<(), ClipboardError> {
        Err(ClipboardError::UnsupportedAsync)
    }

    /// Async version of [`available`][Backend::available]. Default returns
    /// [`UnsupportedAsync`][ClipboardError::UnsupportedAsync].
    async fn available_async(&self, _sel: Selection) -> Result<Vec<MimeType>, ClipboardError> {
        Err(ClipboardError::UnsupportedAsync)
    }
}