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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<book xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Portal Documentation</title>
<releaseinfo>Version @VERSION@</releaseinfo>
</bookinfo>
<chapter id="common-conventions">
<title>Common Conventions</title>
<para>
Requests made via portal interfaces generally involve user interaction,
and dialogs that can stay open for a long time. Therefore portal APIs
don't just use async method calls (which time out after at most 25 seconds),
but instead return results via a Response signal on Request objects.
</para>
<para>
Portal APIs don't use properties very much. This is partially because
we need to be careful about the flow of information, and partially because
it would be unexpected to have a dialog appear when you just set a property.
</para>
<section>
<title>Portal requests</title>
<para>
The general flow of the portal API is that the application makes
a portal request, the portal replies to that method call with a
handle (i.e. object path) to Request object that corresponds to the
request. The object is exported on the bus and stays alive as long
as the user interaction lasts. When the user interaction is over,
the portal sends a Response signal back to the application with
the results from the interaction, if any.
</para>
<para>
To avoid a race condition between the caller subscribing to the signal
after receiving the reply for the method call and the signal getting emitted,
a convention for Request object paths has been established that allows the
caller to subscribe to the signal before making the method call.
</para>
</section>
<section>
<title>Sessions</title>
<para>
Some portal requests are connected to each other and need to be used in
sequence. The pattern we use in such cases is a Session object. Just like
Requests, Sessions are represented by an object path, that is returned by
the initial CreateSession call. Subsequent calls take the object path of
the session they operate on as an argument.
</para>
<para>
Sessions can be ended from the application side by calling the Close()
method. They can also be closed from the service side, in which case the
::Closed signal is emitted to inform the application.
</para>
</section>
<section id="parent_window">
<title>Parent window identifiers</title>
<para>
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 "parent_window" string argument for
this reason.
</para>
<para>
Under X11, the "parent_window" argument should have the form
"x11:<replaceable>XID</replaceable>", where <replaceable>XID</replaceable>
is the XID of the application window in hexadecimal notation.
</para>
<para>
Under Wayland, it should have the form "wayland:<replaceable>HANDLE</replaceable>",
where <replaceable>HANDLE</replaceable> is a surface handle obtained with the
<ulink url="https://github.com/wayland-project/wayland-protocols/blob/master/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml">xdg_foreign</ulink> protocol.
</para>
<para>
For other windowing systems, or if you don't have a suitable handle, just
pass an empty string for "parent_window".
</para>
</section>
</chapter>
<reference>
<title>Portal API Reference</title>
<partintro>
<para>
Portal interfaces are available to sandboxed applications with the
default filtered session bus access of Flatpak. Unless otherwise
specified, they appear under the bus name org.freedesktop.portal.Desktop
and the object path /org/freedesktop/portal/desktop on the session
bus.
</para>
</partintro>
<xi:include href="portal-org.freedesktop.portal.Account.xml"/>
<xi:include href="portal-org.freedesktop.portal.Background.xml"/>
<xi:include href="portal-org.freedesktop.portal.Camera.xml"/>
<xi:include href="portal-org.freedesktop.portal.Clipboard.xml"/>
<xi:include href="portal-org.freedesktop.portal.Device.xml"/>
<xi:include href="portal-org.freedesktop.portal.Documents.xml"/>
<xi:include href="portal-org.freedesktop.portal.DynamicLauncher.xml"/>
<xi:include href="portal-org.freedesktop.portal.Email.xml"/>
<xi:include href="portal-org.freedesktop.portal.FileChooser.xml"/>
<xi:include href="portal-org.freedesktop.portal.FileTransfer.xml"/>
<xi:include href="portal-org.freedesktop.portal.Flatpak.UpdateMonitor.xml"/>
<xi:include href="portal-org.freedesktop.portal.Flatpak.xml"/>
<xi:include href="portal-org.freedesktop.portal.GameMode.xml"/>
<xi:include href="portal-org.freedesktop.portal.GlobalShortcuts.xml"/>
<xi:include href="portal-org.freedesktop.portal.Inhibit.xml"/>
<xi:include href="portal-org.freedesktop.portal.InputCapture.xml"/>
<xi:include href="portal-org.freedesktop.portal.Location.xml"/>
<xi:include href="portal-org.freedesktop.portal.MemoryMonitor.xml"/>
<xi:include href="portal-org.freedesktop.portal.NetworkMonitor.xml"/>
<xi:include href="portal-org.freedesktop.portal.Notification.xml"/>
<xi:include href="portal-org.freedesktop.portal.OpenURI.xml"/>
<xi:include href="portal-org.freedesktop.portal.PowerProfileMonitor.xml"/>
<xi:include href="portal-org.freedesktop.portal.Print.xml"/>
<xi:include href="portal-org.freedesktop.portal.ProxyResolver.xml"/>
<xi:include href="portal-org.freedesktop.portal.Realtime.xml"/>
<xi:include href="portal-org.freedesktop.portal.RemoteDesktop.xml"/>
<xi:include href="portal-org.freedesktop.portal.Request.xml"/>
<xi:include href="portal-org.freedesktop.portal.ScreenCast.xml"/>
<xi:include href="portal-org.freedesktop.portal.Screenshot.xml"/>
<xi:include href="portal-org.freedesktop.portal.Secret.xml"/>
<xi:include href="portal-org.freedesktop.portal.Session.xml"/>
<xi:include href="portal-org.freedesktop.portal.Settings.xml"/>
<xi:include href="portal-org.freedesktop.portal.Trash.xml"/>
<xi:include href="portal-org.freedesktop.portal.Wallpaper.xml"/>
</reference>
<reference>
<title>Portal Backend API Reference</title>
<partintro>
<para>
The backend interfaces are used by the portal frontend to
carry out portal requests. They are provided by a separate process
(or processes), and are not accessible to sandboxed applications.
</para>
<para>
The separation of the portal infrastructure into frontend and backend
is a clean way to provide suitable user interfaces that fit into
different desktop environments, while sharing the portal frontend.
</para>
<para>
The portal backends are focused on providing user interfaces and
accessing session- or host-specific APIs and resources. Details of
interacting with the containment infrastructure such as checking
access, registering files in the document portal, etc., are handled
by the portal frontend.
</para>
</partintro>
<xi:include href="portal-org.freedesktop.impl.portal.Access.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Account.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.AppChooser.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Background.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Clipboard.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Email.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.FileChooser.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.GlobalShortcuts.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Inhibit.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.InputCapture.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Lockdown.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Notification.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.PermissionStore.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Print.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.RemoteDesktop.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Request.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.ScreenCast.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Screenshot.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Secret.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Session.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Settings.xml"/>
<xi:include href="portal-org.freedesktop.impl.portal.Wallpaper.xml"/>
</reference>
<reference>
<title>Background Apps Monitoring API</title>
<partintro>
<para>
In addition to managing the regular interfaces that sandboxed
applications use to interfact with the host system, xdg-desktop-portals
also monitors running applications without an active window - if the
portal backend provides an implementation of the Background portal.
</para>
<para>
This API can be used by host system services to provide rich interfaces
to manage background running applications.
</para>
</partintro>
<xi:include href="portal-org.freedesktop.background.Monitor.xml"/>
</reference>
</book>
|
