logo

Crate ashpd

source · []
Expand description

ASHPD

docs crates.io CI

ASHPD, acronym of Aperture Science Handheld Portal Device is a Rust & zbus wrapper of the XDG portals DBus interfaces. The library aims to provide an easy way to interact with the various portals defined per the specifications. It provides an alternative to the C library https://github.com/flatpak/libportal

Examples

Ask the compositor to pick a color

use ashpd::desktop::screenshot::ScreenshotProxy;
use ashpd::WindowIdentifier;

async fn run() -> ashpd::Result<()> {
    let proxy = ScreenshotProxy::new().await?;
    let color = proxy.pick_color(&WindowIdentifier::default()).await?;
    println!("({}, {}, {})", color.red(), color.green(), color.blue());
    Ok(())
}

Start a PipeWire stream from the user’s camera

use ashpd::desktop::camera::CameraProxy;

pub async fn run() -> ashpd::Result<()> {
    let proxy = CameraProxy::new().await?;
    if proxy.is_camera_present().await? {
        proxy.access_camera().await?;
        let remote_fd = proxy.open_pipe_wire_remote().await?;
        // pass the remote fd to GStreamer for example
    }
    Ok(())
}

Optional features

FeatureDescriptionDefault
tracingRecord various debug information using the tracing libraryNo
tokioEnable tokio runtime on zbus dependencyNo
async-stdEnable the use of the async-std rumtimeYes
gtk3Implement From<Color> for gdk3::RGBA Provides WindowIdentifier::from_window that takes a IsA<gdk3::Window>No
gtk3_waylandProvides WindowIdentifier::from_window that takes a IsA<gdk3::Window> with Wayland backend support onlyNo
gtk3_x11Provides WindowIdentifier::from_window that takes a IsA<gdk3::Window> with X11 backend support onlyNo
gtk4Implement From<Color> for gdk4::RGBA Provides WindowIdentifier::from_native that takes a IsA<gtk4::Native>No
gtk4_waylandProvides WindowIdentifier::from_native that takes a IsA<gtk4::Native> with Wayland backend support onlyNo
gtk4_x11Provides WindowIdentifier::from_native that takes a IsA<gtk4::Native> with X11 backend support onlyNo
pipewireProvides ashpd::desktop::camera::pipewire_streams that helps you retrieve the various camera streams associated with the retrieved file descriptorNo
raw_handleProvides WindowIdentifier::from_raw_handle and WindowIdentifier::as_raw_handle for raw-window-handle crateNo
waylandProvides WindowIdentifier::from_wayland for wayland-client crateNo

Demo

The library comes with a demo built using the GTK 4 Rust bindings and previews most of the portals. It is meant as a test case for the portals (from a distributor perspective) and as a way for the developers to see which portals exists and how to integrate them into their application using ASHPD.

Re-exports

pub use enumflags2;
pub use zbus;
pub use zbus::zvariant;

Modules

Interact with the user’s desktop such as taking a screenshot, setting a background or querying the user’s location.

Interact with the documents store or transfer files across apps.

Spawn commands outside the sandbox or monitor if the running application has received an update & install it.

Enums

The error type for ashpd.

An error type that describes the various DBus errors.

Most portals interact with the user by showing dialogs. These dialogs should generally be placed on top of the application window that triggered them. To arrange this, the compositor needs to know about the application window. Many portal requests expect a WindowIdentifier for this reason.

Functions

Check whether the application is running inside a sandbox.

Type Definitions

Alias for a Result with the error type ashpd::Error.