ashpd/desktop/
background.rs

1//! Request to run in the background or started automatically when the user
2//! logs in.
3//!
4//! **Note** This portal only works for sandboxed applications.
5//!
6//! Wrapper of the DBus interface: [`org.freedesktop.portal.Background`](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Background.html).
7//!
8//! ### Examples
9//!
10//! ```rust,no_run
11//! use ashpd::desktop::background::Background;
12//!
13//! async fn run() -> ashpd::Result<()> {
14//!     let response = Background::request()
15//!         .reason("Automatically fetch your latest mails")
16//!         .auto_start(true)
17//!         .command(&["geary"])
18//!         .dbus_activatable(false)
19//!         .send()
20//!         .await?
21//!         .response()?;
22//!
23//!     println!("{}", response.auto_start());
24//!     println!("{}", response.run_in_background());
25//!
26//!     Ok(())
27//! }
28//! ```
29//!
30//! If no `command` is provided, the [`Exec`](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables) line from the [desktop
31//! file](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction) will be used.
32
33use serde::Serialize;
34use zbus::zvariant::{DeserializeDict, SerializeDict, Type};
35
36use super::{HandleToken, Request};
37use crate::{proxy::Proxy, Error, WindowIdentifier};
38
39#[derive(SerializeDict, Type, Debug, Default)]
40#[zvariant(signature = "dict")]
41struct BackgroundOptions {
42    handle_token: HandleToken,
43    reason: Option<String>,
44    autostart: Option<bool>,
45    #[zvariant(rename = "dbus-activatable")]
46    dbus_activatable: Option<bool>,
47    #[zvariant(rename = "commandline")]
48    command: Option<Vec<String>>,
49}
50
51#[derive(DeserializeDict, Type, Debug)]
52/// The response of a [`BackgroundRequest`] request.
53#[zvariant(signature = "dict")]
54pub struct Background {
55    background: bool,
56    autostart: bool,
57}
58
59impl Background {
60    /// Creates a new builder-pattern struct instance to construct
61    /// [`Background`].
62    ///
63    /// This method returns an instance of [`BackgroundRequest`].
64    pub fn request() -> BackgroundRequest {
65        BackgroundRequest::default()
66    }
67
68    /// If the application is allowed to run in the background.
69    pub fn run_in_background(&self) -> bool {
70        self.background
71    }
72
73    /// If the application will be auto-started.
74    pub fn auto_start(&self) -> bool {
75        self.autostart
76    }
77}
78
79#[derive(SerializeDict, Type, Debug, Default)]
80#[zvariant(signature = "dict")]
81struct SetStatusOptions {
82    message: String,
83}
84
85/// The interface lets sandboxed applications request that the application
86/// is allowed to run in the background or started automatically when the user
87/// logs in.
88///
89/// Wrapper of the DBus interface: [`org.freedesktop.portal.Background`](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Background.html).
90#[doc(alias = "org.freedesktop.portal.Background")]
91pub struct BackgroundProxy<'a>(Proxy<'a>);
92
93impl<'a> BackgroundProxy<'a> {
94    /// Create a new instance of [`BackgroundProxy`].
95    pub async fn new() -> Result<BackgroundProxy<'a>, Error> {
96        let proxy = Proxy::new_desktop("org.freedesktop.portal.Background").await?;
97        Ok(Self(proxy))
98    }
99
100    ///  Sets the status of the application running in background.
101    ///
102    /// # Arguments
103    ///
104    /// * `message` - A string that will be used as the status message of the
105    ///   application.
106    ///
107    /// # Required version
108    ///
109    /// The method requires the 2nd version implementation of the portal and
110    /// would fail with [`Error::RequiresVersion`] otherwise.
111    ///
112    /// # Specifications
113    ///
114    /// See also [`SetStatus`](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Background.html#org-freedesktop-portal-background-setstatus).
115    pub async fn set_status(&self, message: &str) -> Result<(), Error> {
116        self.0
117            .call_versioned(
118                "SetStatus",
119                &(SetStatusOptions {
120                    message: message.to_owned(),
121                }),
122                2,
123            )
124            .await
125    }
126
127    async fn request_background(
128        &self,
129        identifier: Option<&WindowIdentifier>,
130        options: BackgroundOptions,
131    ) -> Result<Request<Background>, Error> {
132        let identifier = identifier.map(|i| i.to_string()).unwrap_or_default();
133        self.0
134            .request(
135                &options.handle_token,
136                "RequestBackground",
137                (&identifier, &options),
138            )
139            .await
140    }
141}
142
143impl<'a> std::ops::Deref for BackgroundProxy<'a> {
144    type Target = zbus::Proxy<'a>;
145
146    fn deref(&self) -> &Self::Target {
147        &self.0
148    }
149}
150
151#[doc(alias = "xdp_portal_request_background")]
152/// A [builder-pattern] type to construct [`Background`].
153///
154/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
155#[derive(Debug, Default)]
156pub struct BackgroundRequest {
157    identifier: Option<WindowIdentifier>,
158    options: BackgroundOptions,
159}
160
161impl BackgroundRequest {
162    #[must_use]
163    /// Sets a window identifier.
164    pub fn identifier(mut self, identifier: impl Into<Option<WindowIdentifier>>) -> Self {
165        self.identifier = identifier.into();
166        self
167    }
168
169    #[must_use]
170    /// Sets whether to auto start the application or not.
171    pub fn auto_start(mut self, auto_start: impl Into<Option<bool>>) -> Self {
172        self.options.autostart = auto_start.into();
173        self
174    }
175
176    #[must_use]
177    /// Sets whether the application is dbus activatable.
178    pub fn dbus_activatable(mut self, dbus_activatable: impl Into<Option<bool>>) -> Self {
179        self.options.dbus_activatable = dbus_activatable.into();
180        self
181    }
182
183    #[must_use]
184    /// Specifies the command line to execute.
185    /// If this is not specified, the [`Exec`](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables) line from the [desktop
186    /// file](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction)
187    pub fn command<P: IntoIterator<Item = I>, I: AsRef<str> + Type + Serialize>(
188        mut self,
189        command: impl Into<Option<P>>,
190    ) -> Self {
191        self.options.command = command
192            .into()
193            .map(|a| a.into_iter().map(|s| s.as_ref().to_owned()).collect());
194        self
195    }
196
197    #[must_use]
198    /// Sets a user-visible reason for the request.
199    pub fn reason<'a>(mut self, reason: impl Into<Option<&'a str>>) -> Self {
200        self.options.reason = reason.into().map(ToOwned::to_owned);
201        self
202    }
203
204    /// Build the [`Background`].
205    pub async fn send(self) -> Result<Request<Background>, Error> {
206        let proxy = BackgroundProxy::new().await?;
207        proxy
208            .request_background(self.identifier.as_ref(), self.options)
209            .await
210    }
211}
ashpd/desktop/background.rs

ashpd/desktop/
background.rs
