Struct ashpd::documents::Documents

pub struct Documents<'a>(/* private fields */);

The interface lets sandboxed applications make files from the outside world available to sandboxed applications in a controlled way.

Exported files will be made accessible to the application via a fuse filesystem that gets mounted at /run/user/$UID/doc/. The filesystem gets mounted both outside and inside the sandbox, but the view inside the sandbox is restricted to just those files that the application is allowed to access.

Individual files will appear at /run/user/$UID/doc/$DOC_ID/filename, where $DOC_ID is the ID of the file in the document store. It is returned by the Documents::add and Documents::add_named calls.

The permissions that the application has for a document store entry (see Documents::grant_permissions) are reflected in the POSIX mode bits in the fuse filesystem.

Wrapper of the DBus interface: org.freedesktop.portal.Documents.

Implementations

impl<'a> Documents<'a>

pub async fn new() -> Result<Documents<'a>, Error>

Create a new instance of Documents.

pub async fn add( &self, o_path_fd: &BorrowedFd<'_>, reuse_existing: bool, persistent: bool, ) -> Result<DocumentID, Error>

Adds a file to the document store. The file is passed in the form of an open file descriptor to prove that the caller has access to the file.

Arguments

• o_path_fd - Open file descriptor for the file to add.
• reuse_existing - Whether to reuse an existing document store entry for the file.
• persistent - Whether to add the file only for this session or permanently.

Returns

The ID of the file in the document store.

Specifications

See also Add.

pub async fn add_full( &self, o_path_fds: &[&BorrowedFd<'_>], flags: BitFlags<DocumentFlags>, app_id: Option<&AppID>, permissions: &[Permission], ) -> Result<(Vec<DocumentID>, HashMap<String, OwnedValue>), Error>

Adds multiple files to the document store. The files are passed in the form of an open file descriptor to prove that the caller has access to the file.

Arguments

• o_path_fds - Open file descriptors for the files to export.
• flags - A DocumentFlags.
• app_id - An application ID, or None.
• permissions - The permissions to grant.

Returns

The IDs of the files in the document store along with other extra info.

Required version

The method requires the 2nd version implementation of the portal and would fail with Error::RequiresVersion otherwise.

Specifications

See also AddFull.

pub async fn add_named( &self, o_path_parent_fd: &BorrowedFd<'_>, filename: impl AsRef<Path>, reuse_existing: bool, persistent: bool, ) -> Result<DocumentID, Error>

Creates an entry in the document store for writing a new file.

Arguments

• o_path_parent_fd - Open file descriptor for the parent directory.
• filename - The basename for the file.
• reuse_existing - Whether to reuse an existing document store entry for the file.
• persistent - Whether to add the file only for this session or permanently.

Returns

The ID of the file in the document store.

Specifications

See also AddNamed.

pub async fn add_named_full( &self, o_path_fd: &BorrowedFd<'_>, filename: impl AsRef<Path>, flags: BitFlags<DocumentFlags>, app_id: Option<&AppID>, permissions: &[Permission], ) -> Result<(DocumentID, HashMap<String, OwnedValue>), Error>

Adds multiple files to the document store. The files are passed in the form of an open file descriptor to prove that the caller has access to the file.

Arguments

• o_path_fd - Open file descriptor for the parent directory.
• filename - The basename for the file.
• flags - A DocumentFlags.
• app_id - An application ID, or None.
• permissions - The permissions to grant.

Returns

The ID of the file in the document store along with other extra info.

Required version

The method requires the 3nd version implementation of the portal and would fail with Error::RequiresVersion otherwise.

Specifications

See also AddNamedFull.

pub async fn delete(&self, doc_id: impl Into<DocumentID>) -> Result<(), Error>

Removes an entry from the document store. The file itself is not deleted.

Note This call is available inside the sandbox if the application has the Permission::Delete for the document.

Arguments

• doc_id - The ID of the file in the document store.

Specifications

See also Delete.

pub async fn mount_point(&self) -> Result<FilePath, Error>

Returns the path at which the document store fuse filesystem is mounted. This will typically be /run/user/$UID/doc/.

Specifications

See also GetMountPoint.

pub async fn grant_permissions( &self, doc_id: impl Into<DocumentID>, app_id: &AppID, permissions: &[Permission], ) -> Result<(), Error>

Grants access permissions for a file in the document store to an application.

Note This call is available inside the sandbox if the application has the Permission::GrantPermissions for the document.

Arguments

• doc_id - The ID of the file in the document store.
• app_id - The ID of the application to which permissions are granted.
• permissions - The permissions to grant.

Specifications

See also GrantPermissions.

pub async fn info( &self, doc_id: impl Into<DocumentID>, ) -> Result<(FilePath, Permissions), Error>

Gets the filesystem path and application permissions for a document store entry.

Note This call is not available inside the sandbox.

Arguments

• doc_id - The ID of the file in the document store.

Returns

The path of the file in the host filesystem along with the Permissions.

Specifications

See also Info.

pub async fn list( &self, app_id: Option<&AppID>, ) -> Result<HashMap<DocumentID, FilePath>, Error>

Lists documents in the document store for an application (or for all applications).

Note This call is not available inside the sandbox.

Arguments

• app-id - The application ID, or None to list all documents.

Returns

HashMap mapping document IDs to their filesystem path on the host system.

Specifications

See also List.

pub async fn lookup( &self, filename: impl AsRef<Path>, ) -> Result<Option<DocumentID>, Error>

Looks up the document ID for a file.

Note This call is not available inside the sandbox.

Arguments

• filename - A path in the host filesystem.

Returns

The ID of the file in the document store, or None if the file is not in the document store.

Specifications

See also Lookup.

pub async fn revoke_permissions( &self, doc_id: impl Into<DocumentID>, app_id: &AppID, permissions: &[Permission], ) -> Result<(), Error>

Revokes access permissions for a file in the document store from an application.

Note This call is available inside the sandbox if the application has the Permission::GrantPermissions for the document.

Arguments

• doc_id - The ID of the file in the document store.
• app_id - The ID of the application from which the permissions are revoked.
• permissions - The permissions to revoke.

Specifications

See also RevokePermissions.

pub async fn host_paths( &self, doc_ids: &[DocumentID], ) -> Result<HashMap<DocumentID, FilePath>, Error>

Retrieves the host filesystem paths from their document IDs.

Arguments

• doc_ids - A list of file IDs in the document store.

Returns

A dictionary mapping document IDs to the paths in the host filesystem

Specifications

See also GetHostPaths.

Methods from Deref<Target = Proxy<'a>>

pub fn connection(&self) -> &Connection

Get a reference to the associated connection.

pub fn destination(&self) -> &BusName<'_>

Get a reference to the destination service name.

pub fn path(&self) -> &ObjectPath<'_>

Get a reference to the object path.

pub fn interface(&self) -> &InterfaceName<'_>

Get a reference to the interface.

pub async fn introspect(&self) -> Result<String, Error>

Introspect the associated object, and return the XML description.

See the xml module for parsing the result.

pub fn cached_property<T>( &self, property_name: &str, ) -> Result<Option<T>, Error>

where T: TryFrom<OwnedValue>, <T as TryFrom<OwnedValue>>::Error: Into<Error>,

Get the cached value of the property property_name.

This returns None if the property is not in the cache. This could be because the cache was invalidated by an update, because caching was disabled for this property or proxy, or because the cache has not yet been populated. Use get_property to fetch the value from the peer.

pub fn cached_property_raw<'p>( &'p self, property_name: &'p str, ) -> Option<impl Deref<Target = Value<'static>> + 'p>

Get the cached value of the property property_name.

Same as cached_property, but gives you access to the raw value stored in the cache. This is useful if you want to avoid allocations and cloning.

pub async fn get_property<T>(&self, property_name: &str) -> Result<T, Error>

where T: TryFrom<OwnedValue>, <T as TryFrom<OwnedValue>>::Error: Into<Error>,

Get the property property_name.

Get the property value from the cache (if caching is enabled) or call the Get method of the org.freedesktop.DBus.Properties interface.

pub async fn set_property<'t, T>( &self, property_name: &str, value: T, ) -> Result<(), Error>

where T: 't + Into<Value<'t>>,

Set the property property_name.

Effectively, call the Set method of the org.freedesktop.DBus.Properties interface.

pub async fn call_method<'m, M, B>( &self, method_name: M, body: &B, ) -> Result<Message, Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>, B: Serialize + DynamicType,

Call a method and return the reply.

Typically, you would want to use call method instead. Use this method if you need to deserialize the reply message manually (this way, you can avoid the memory allocation/copying, by deserializing the reply to an unowned type).

pub async fn call<'m, M, B, R>( &self, method_name: M, body: &B, ) -> Result<R, Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>, B: Serialize + DynamicType, R: for<'d> DynamicDeserialize<'d>,

Call a method and return the reply body.

Use call_method instead if you need to deserialize the reply manually/separately.

pub async fn call_with_flags<'m, M, B, R>( &self, method_name: M, flags: BitFlags<MethodFlags>, body: &B, ) -> Result<Option<R>, Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>, B: Serialize + DynamicType, R: for<'d> DynamicDeserialize<'d>,

Call a method and return the reply body, optionally supplying a set of method flags to control the way the method call message is sent and handled.

Use call instead if you do not need any special handling via additional flags. If the NoReplyExpected flag is passed , this will return None immediately after sending the message, similar to call_noreply

pub async fn call_noreply<'m, M, B>( &self, method_name: M, body: &B, ) -> Result<(), Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>, B: Serialize + DynamicType,

Call a method without expecting a reply

This sets the NoReplyExpected flag on the calling message and does not wait for a reply.

pub async fn receive_signal<'m, M>( &self, signal_name: M, ) -> Result<SignalStream<'m>, Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>,

Create a stream for signal named signal_name.

pub async fn receive_signal_with_args<'m, M>( &self, signal_name: M, args: &[(u8, &str)], ) -> Result<SignalStream<'m>, Error>

where M: TryInto<MemberName<'m>>, <M as TryInto<MemberName<'m>>>::Error: Into<Error>,

Same as Proxy::receive_signal but with a filter.

The D-Bus specification allows you to filter signals by their arguments, which helps avoid a lot of unnecessary traffic and processing since the filter is run on the server side. Use this method where possible. Note that this filtering is limited to arguments of string types.

The arguments are passed as a tuples of argument index and expected value.

pub async fn receive_all_signals(&self) -> Result<SignalStream<'static>, Error>

Create a stream for all signals emitted by this service.

pub async fn receive_property_changed<'name, T>( &self, name: &'name str, ) -> PropertyStream<'a, T>

where 'name: 'a,

Get a stream to receive property changed events.

Note that zbus doesn’t queue the updates. If the listener is slower than the receiver, it will only receive the last update.

If caching is not enabled on this proxy, the resulting stream will not return any events.

pub async fn receive_owner_changed( &self, ) -> Result<OwnerChangedStream<'_>, Error>

Get a stream to receive destination owner changed events.

If the proxy destination is a unique name, the stream will be notified of the peer disconnection from the bus (with a None value).

If the proxy destination is a well-known name, the stream will be notified whenever the name owner is changed, either by a new peer being granted ownership (Some value) or when the name is released (with a None value).

Note that zbus doesn’t queue the updates. If the listener is slower than the receiver, it will only receive the last update.

Trait Implementations

impl<'a> Debug for Documents<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Deref for Documents<'a>

type Target = Proxy<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.