ashpd

Most portals (like file pickers or permission dialogs) need to be displayed on top of the application window that triggered them. To achieve this, the compositor requires a WindowIdentifier to associate the portal dialog with the parent application window.

WindowIdentifier abstracts the differences between display protocols:

• X11: Uses the format x11:XID, where XID is the hexadecimal XID of the window.
• Wayland: Uses the format wayland:HANDLE, where HANDLE is a surface handle obtained via the xdg-foreign protocol.

Depending on your toolkit and features, you can create these identifiers from GTK 4 natives, Wayland surfaces, or raw window handles.

// Example: Creating an identifier from an X11 XID
let identifier = WindowIdentifier::from_xid(212321);

// Example: Creating an identifier from a Wayland surface (requires `wayland` feature)
// let identifier = WindowIdentifier::from_wayland(wl_surface).await;

The GameMode struct provides an interface for sandboxed applications to access the org.freedesktop.portal.GameMode DBus interface. It allows applications to register themselves (or other processes) as games to request GameMode activation, unregister them, and query the current status of a process.

Key features:

• PID Translation: If running in a sandbox with PID namespace isolation, the portal transparently translates sandbox PIDs to host PIDs.
• Automatic Unregistration: If a registered client terminates without calling unregister, GameMode will automatically unregister it after a small delay.
• Multiple Identification Methods: You can identify processes using raw PIDs, PID file descriptors (pidfd), or a combination of a target PID/FD and a requester PID/FD.

use ashpd::desktop::game_mode::GameMode;

async fn run() -> ashpd::Result<()> {
    let proxy = GameMode::new().await?;

    // Register a process
    proxy.register(246612).await?;

    // Query status
    let status = proxy.query_status(246612).await?;
    println!("{:#?}", status);

    // Unregister a process
    proxy.unregister(246612).await?;

    Ok(())
}

The Session<T> type is a wrapper around the org.freedesktop.portal.Session DBus interface. It is used by portals that involve long-lived interactions (such as ScreenCast, Remote Desktop, or Global Shortcuts). When a portal method creates a session, it returns a session handle (an object path) that identifies a Session object which remains alive for the duration of that interaction.

Key capabilities:

• Closing a session: You can end the session and all related user interactions (like active dialogs) by calling .close().
• Monitoring closure: You can listen for the session being closed (either by your application or by the system/user) using the .receive_closed() stream.

Note: You should not create a Session instance manually. Instead, it is provided as a response to a session-creating method from a SessionPortal.

// Example of interacting with an existing session
// (Assuming `session` is obtained from a SessionPortal call)

// Listen for the session closing
let mut closed_stream = session.receive_closed().await?;
while let Some(details) = closed_stream.next().await {
    println!("Session closed with details: {:?}", details);
}

// Or manually close the session
session.close().await?;

ASHPD uses Cargo features to enable specific functionalities. By default, tokio is enabled. Other features include:

• tracing: Enables debug information via the tracing library.
• async-io: Enables compatibility with async-io crates (e.g., smol or glib).
• frontend: Enables all frontend APIs. You can also enable individual APIs like account, camera, or screencast.
• glib: Makes all enums derive glib::Enum (flags not yet supported).
• gtk4: Implements From<Color> for gdk4::RGBA and provides WindowIdentifier::from_native for IsA<gtk4::Native>.
• gtk4_wayland / gtk4_x11: Specialized WindowIdentifier::from_native support for specific backends.
• pipewire: Provides ashpd::desktop::camera::pipewire_streams to help retrieve camera streams from a file descriptor.
• raw_handle: Provides WindowIdentifier integration with the raw-window-handle crate.
• wayland: Provides WindowIdentifier::from_wayland for the wayland-client crate.
• backend: Enables support for implementing portal backend interfaces.

The FileTransfer API acts as a middle-man for transferring files between applications, typically via drag-and-drop or copy-paste.

Workflow:

1. Sender:
   • Call start_transfer() to obtain a unique key.
   • Call add_files() using that key and a list of file descriptors to register files in the session.
   • Transmit the key to the target application (e.g., via the application/vnd.portal.filetransfer mimetype).
2. Receiver:
   • Receive the key.
   • Call retrieve_files() with the key to obtain the list of file paths. The portal handles exporting the files so they are accessible to the receiver.
3. Cleanup:
   • Call stop_transfer() to end the session.

Note: Only regular files (not directories) can be added via add_files.

use std::{fs::File, os::fd::AsFd};
use ashpd::documents::file_transfer::{FileTransfer, StartTransferOptions};

async fn run() -> ashpd::Result<()> {
    let proxy = FileTransfer::new().await?;

    // 1. Start transfer and get key
    let key = proxy
        .start_transfer(
            StartTransferOptions::default()
                .set_writable(true)
                .set_auto_stop(true),
        )
        .await?;

    // 2. Add files to the session
    let file = File::open("/path/to/file.jpg").unwrap();
    proxy
        .add_files(&key, &[&file.as_fd()], Default::default()),
        .await?;

    // 3. Receiver retrieves files using the key
    let files = proxy.retrieve_files(&key, Default::default()).await?;
    println!("{:#?}", files);

    // 4. Stop the transfer
    proxy.stop_transfer(&key).await?;

    Ok(())
}