-
-
Notifications
You must be signed in to change notification settings - Fork 210
/
Copy pathorg.freedesktop.portal.ScreenCast.xml
337 lines (302 loc) · 14.5 KB
/
org.freedesktop.portal.ScreenCast.xml
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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
<?xml version="1.0"?>
<!--
Copyright (C) 2017-2018 Red Hat, Inc.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library. If not, see <http://www.gnu.org/licenses/>.
-->
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<!--
org.freedesktop.portal.ScreenCast:
@short_description: Screen cast portal
The Screen cast portal allows to create screen cast sessions.
This documentation describes version 5 of this interface.
-->
<interface name="org.freedesktop.portal.ScreenCast">
<!--
CreateSession:
@options: Vardict with optional further information
@handle: Object path for the #org.freedesktop.portal.Request object representing this call
Create a screen cast session. A successfully created session can at
any time be closed using org.freedesktop.portal.Session.Close(), or may
at any time be closed by the portal implementation, which will be
signalled via #org.freedesktop.portal.Session::Closed.
Supported keys in the @options vardict include:
<variablelist>
<varlistentry>
<term>handle_token s</term>
<listitem><para>
A string that will be used as the last element of the @handle. Must be a valid
object path element. See the #org.freedesktop.portal.Request documentation for
more information about the @handle.
</para></listitem>
</varlistentry>
<varlistentry>
<term>session_handle_token s</term>
<listitem><para>
A string that will be used as the last element of the session handle. Must be a valid
object path element. See the #org.freedesktop.portal.Session documentation for
more information about the session handle.
</para></listitem>
</varlistentry>
</variablelist>
The following results get returned via the #org.freedesktop.portal.Request::Response signal:
<variablelist>
<varlistentry>
<term>session_handle o</term>
<listitem><para>
The session handle. An object path for the
#org.freedesktop.portal.Session object representing the created
session.
</para></listitem>
</varlistentry>
</variablelist>
-->
<method name="CreateSession">
<arg type="a{sv}" name="options" direction="in"/>
<arg type="o" name="handle" direction="out"/>
</method>
<!--
SelectSources:
@session_handle: Object path for the #org.freedesktop.portal.Session object
@options: Vardict with optional further information
@handle: Object path for the #org.freedesktop.portal.Request object representing this call
Configure what the screen cast session should record. This method must
be called before starting the session.
Passing invalid input to this method will cause the session to be
closed. An application may only attempt to select sources once per
session.
Supported keys in the @options vardict include:
<variablelist>
<varlistentry>
<term>handle_token s</term>
<listitem><para>
A string that will be used as the last element of the @handle. Must be a valid
object path element. See the #org.freedesktop.portal.Request documentation for
more information about the @handle.
</para></listitem>
</varlistentry>
<varlistentry>
<term>types u</term>
<listitem><para>
Bitmask of what types of content to record. Default is MONITOR.
</para></listitem>
</varlistentry>
<varlistentry>
<term>multiple b</term>
<listitem><para>
Whether to allow selecting multiple sources. Default is no.
</para></listitem>
</varlistentry>
<varlistentry>
<term>cursor_mode u</term>
<listitem><para>
Determines how the cursor will be drawn in the screen cast stream. It must be
one of the cursor modes advertised in
#org.freedesktop.portal.ScreenCast.AvailableCursorModes. Setting a cursor mode
not advertised will cause the screen cast session to be closed. The default
cursor mode is 'Hidden'.
This option was added in version 2 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_token s</term>
<listitem><para>
The token to restore a previous session.
If the stored session cannot be restored, this value is ignored
and the user will be prompted normally. This may happen when, for
example, the session contains a monitor or a window that is not
available anymore, or when the stored permissions are withdrawn.
The restore token is invalidated after using it once. To restore
the same session again, use the new restore token sent in response
to starting this session.
Setting a restore_token is only allowed for screen cast sessions.
Persistent remote desktop screen cast sessions can only be handled
via the #org.freedesktop.portal.RemoteDesktop interface.
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>persist_mode u</term>
<listitem><para>
How this session should persist. Default is 0. Accepted values are:
<simplelist>
<member>0: Do not persist (default)</member>
<member>1: Permissions persist as long as the application is running</member>
<member>2: Permissions persist until explicitly revoked</member>
</simplelist>
Setting persist_mode is only allowed for screen cast sessions. Persistent
remote desktop screen cast sessions can only be handled via the
#org.freedesktop.portal.RemoteDesktop interface.
If the permission for the session to persist is granted, a restore token will
be returned via the #org.freedesktop.portal.Request::Response signal of the
#org.freedesktop.portal.ScreenCast.Start method.
This option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
For available source types, see the AvailableSourceTypes property.
-->
<method name="SelectSources">
<arg type="o" name="session_handle" direction="in"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="o" name="handle" direction="out"/>
</method>
<!--
Start:
@session_handle: Object path for the #org.freedesktop.portal.Session object
@parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
@options: Vardict with optional further information
@handle: Object path for the #org.freedesktop.portal.Request object representing this call
Start the screen cast session. This will typically result the portal
presenting a dialog letting the user do the selection set up by
org.freedesktop.portal.ScreenCast.SelectSources(). An application can
only attempt start a session once.
A screen cast session may only be started after having selected sources
using org.freedesktop.portal.ScreenCast.SelectSources().
Supported keys in the @options vardict include:
<variablelist>
<varlistentry>
<term>handle_token s</term>
<listitem><para>
A string that will be used as the last element of the @handle. Must be a valid
object path element. See the #org.freedesktop.portal.Request documentation for
more information about the @handle.
</para></listitem>
</varlistentry>
</variablelist>
The following results get returned via the
#org.freedesktop.portal.Request::Response signal:
<variablelist>
<varlistentry>
<term>streams a(ua{sv})</term>
<listitem><para>
An array of PipeWire streams. Each stream consists of a PipeWire
node ID (the first element in the tuple, and a Vardict of
properties.
The array will contain a single stream if 'multiple' (see
org.freedesktop.portal.ScreenCast.SelectSources())
was set to 'false', or at least one stream if
'multiple' was set to 'true' as part of the
org.freedesktop.portal.ScreenCast.SelectSources() method.
</para></listitem>
</varlistentry>
<varlistentry>
<term>restore_token s</term>
<listitem><para>
The restore token. This token is a single use token that can later
be used to restore a session. See
org.freedesktop.portal.ScreenCast.SelectSources() for details.
This response option was added in version 4 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
Stream properties include:
<variablelist>
<varlistentry>
<term>id s</term>
<listitem><para>
Opaque identifier. Will be unique for this stream and local to this
session. Will persist with future sessions, if they are restored
using a restore token. This property was added in version 4 of this
interface. Optional.
</para></listitem>
</varlistentry>
<varlistentry>
<term>position (ii)</term>
<listitem><para>
A tuple consisting of the position (x, y) in the compositor
coordinate space. Note that the position may not be equivalent to a
position in a pixel coordinate space. Only available for monitor
streams. Optional.
</para></listitem>
</varlistentry>
<varlistentry>
<term>size (ii)</term>
<listitem><para>
A tuple consisting of (width, height). The size represents the size
of the stream as it is displayed in the compositor coordinate
space. Note that this size may not be equivalent to a size in a
pixel coordinate space. The size may differ from the size of the
stream. Optional.
</para></listitem>
</varlistentry>
<varlistentry>
<term>source_type u</term>
<listitem><para>
The type of the content which is being screen casted.
For available source types, see the AvailableSourceTypes property.
This property was added in version 3 of this interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term>mapping_id s</term>
<listitem><para>
An optional identifier used to map different aspects of the
resource this stream corresponds to.
</para><para>
When used in a remote desktop session, the mapping_id can be used to
match a libei region of absolute libei devices. There may be
multiple absolute libei devices, and each device may have multiple
regions, but a mapping_id will only match one of these regions per
device. This property was added in version 5 of this interface.
</para></listitem>
</varlistentry>
</variablelist>
-->
<method name="Start">
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="parent_window" direction="in"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="o" name="handle" direction="out"/>
</method>
<!--
OpenPipeWireRemote:
@session_handle: Object path for the #org.freedesktop.portal.Session object
@options: Vardict with optional further information
@fd: File descriptor of an open PipeWire remote.
Open a file descriptor to the PipeWire remote where the screen cast
streams are available. The file descriptor should be used to create a
<classname>pw_core</classname> object, by using
<function>pw_context_connect_fd</function>. Only the screen cast stream
nodes will be available from this PipeWire node.
-->
<method name="OpenPipeWireRemote">
<annotation name="org.gtk.GDBus.C.Name" value="open_pipewire_remote"/>
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
<arg type="o" name="session_handle" direction="in"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="h" name="fd" direction="out"/>
</method>
<!--
AvailableSourceTypes:
A bitmask of available source types. Currently defined types are:
<simplelist>
<member>1: MONITOR</member>
<member>2: WINDOW</member>
<member>4: VIRTUAL</member>
</simplelist>
-->
<property name="AvailableSourceTypes" type="u" access="read"/>
<!--
AvailableCursorModes:
A bitmask of available cursor modes.
Available cursor mode values:
<simplelist>
<member>1: Hidden. The cursor is not part of the screen cast stream.</member>
<member>2: Embedded: The cursor is embedded as part of the stream buffers.</member>
<member>4: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.</member>
</simplelist>
This property was added in version 2 of this interface.
-->
<property name="AvailableCursorModes" type="u" access="read"/>
<property name="version" type="u" access="read"/>
</interface>
</node>