Warning, /plasma/kpipewire/tests/org.freedesktop.portal.ScreenCast.xml is written in an unsupported language. File is not indexed.
0001 <?xml version="1.0"?>
0002 <!--
0003 Copyright (C) 2017-2018 Red Hat, Inc.
0004
0005 This library is free software; you can redistribute it and/or
0006 modify it under the terms of the GNU Lesser General Public
0007 License as published by the Free Software Foundation; either
0008 version 2 of the License, or (at your option) any later version.
0009
0010 This library is distributed in the hope that it will be useful,
0011 but WITHOUT ANY WARRANTY; without even the implied warranty of
0012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
0013 Lesser General Public License for more details.
0014
0015 You should have received a copy of the GNU Lesser General Public
0016 License along with this library. If not, see <http://www.gnu.org/licenses/>.
0017 -->
0018
0019 <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
0020 <!--
0021 org.freedesktop.portal.ScreenCast:
0022 @short_description: Screen cast portal
0023
0024 The Screen cast portal allows to create screen cast sessions.
0025
0026 This documentation describes version 4 of this interface.
0027 -->
0028 <interface name="org.freedesktop.portal.ScreenCast">
0029 <!--
0030 CreateSession:
0031 @options: Vardict with optional further information
0032 @handle: Object path for the #org.freedesktop.portal.Request object representing this call
0033
0034 Create a screen cast session. A successfully created session can at
0035 any time be closed using org.freedesktop.portal.Session.Close(), or may
0036 at any time be closed by the portal implementation, which will be
0037 signalled via #org.freedesktop.portal.Session::Closed.
0038
0039 Supported keys in the @options vardict include:
0040 <variablelist>
0041 <varlistentry>
0042 <term>handle_token s</term>
0043 <listitem><para>
0044 A string that will be used as the last element of the @handle. Must be a valid
0045 object path element. See the #org.freedesktop.portal.Request documentation for
0046 more information about the @handle.
0047 </para></listitem>
0048 </varlistentry>
0049 <varlistentry>
0050 <term>session_handle_token s</term>
0051 <listitem><para>
0052 A string that will be used as the last element of the session handle. Must be a valid
0053 object path element. See the #org.freedesktop.portal.Session documentation for
0054 more information about the session handle.
0055 </para></listitem>
0056 </varlistentry>
0057 </variablelist>
0058
0059 The following results get returned via the #org.freedesktop.portal.Request::Response signal:
0060 <variablelist>
0061 <varlistentry>
0062 <term>session_handle o</term>
0063 <listitem><para>
0064 The session handle. An object path for the
0065 #org.freedesktop.portal.Session object representing the created
0066 session.
0067 </para></listitem>
0068 </varlistentry>
0069 </variablelist>
0070 -->
0071 <method name="CreateSession">
0072 <arg type="a{sv}" name="options" direction="in"/>
0073 <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QVariantMap" />
0074 <arg type="o" name="handle" direction="out"/>
0075 </method>
0076 <!--
0077 SelectSources:
0078 @session_handle: Object path for the #org.freedesktop.portal.Session object
0079 @options: Vardict with optional further information
0080 @handle: Object path for the #org.freedesktop.portal.Request object representing this call
0081
0082 Configure what the screen cast session should record. This method must
0083 be called before starting the session.
0084
0085 Passing invalid input to this method will cause the session to be
0086 closed. An application may only attempt to select sources once per
0087 session.
0088
0089 Supported keys in the @options vardict include:
0090 <variablelist>
0091 <varlistentry>
0092 <term>handle_token s</term>
0093 <listitem><para>
0094 A string that will be used as the last element of the @handle. Must be a valid
0095 object path element. See the #org.freedesktop.portal.Request documentation for
0096 more information about the @handle.
0097 </para></listitem>
0098 </varlistentry>
0099 <varlistentry>
0100 <term>types u</term>
0101 <listitem><para>
0102 Bitmask of what types of content to record. Default is MONITOR.
0103 </para></listitem>
0104 </varlistentry>
0105 <varlistentry>
0106 <term>multiple b</term>
0107 <listitem><para>
0108 Whether to allow selecting multiple sources. Default is no.
0109 </para></listitem>
0110 </varlistentry>
0111 <varlistentry>
0112 <term>cursor_mode u</term>
0113 <listitem><para>
0114 Determines how the cursor will be drawn in the screen cast stream. It must be
0115 one of the cursor modes advertised in
0116 #org.freedesktop.portal.ScreenCast.AvailableCursorModes. Setting a cursor mode
0117 not advertised will cause the screen cast session to be closed. The default
0118 cursor mode is 'Hidden'.
0119
0120 This option was added in version 2 of this interface.
0121 </para></listitem>
0122 </varlistentry>
0123 <varlistentry>
0124 <term>restore_token s</term>
0125 <listitem><para>
0126 The token to restore a previous session.
0127
0128 If the stored session cannot be restored, this value is ignored
0129 and the user will be prompted normally. This may happen when, for
0130 example, the session contains a monitor or a window that is not
0131 available anymore, or when the stored permissions are withdrawn.
0132
0133 The restore token is invalidated after using it once. To restore
0134 the same session again, use the new restore token sent in response
0135 to starting this session.
0136
0137 This option was added in version 4 of this interface.
0138 </para></listitem>
0139 </varlistentry>
0140 <varlistentry>
0141 <term>persist_mode u</term>
0142 <listitem><para>
0143 How this session should persist. Default is 0. Accepted values are:
0144
0145 <simplelist>
0146 <member>0: Do not persist (default)</member>
0147 <member>1: Permissions persist as long as the application is running</member>
0148 <member>2: Permissions persist until explicitly revoked</member>
0149 </simplelist>
0150
0151 Remote desktop screen cast sessions cannot persist. The only allowed
0152 persist_mode for remote desktop sessions is 0.
0153
0154 If the permission for the session to persist is granted, a restore token will
0155 be returned via the #org.freedesktop.portal.Request::Response signal of the
0156 #org.freedesktop.portal.ScreenCast.Start method.
0157
0158 This option was added in version 4 of this interface.
0159 </para></listitem>
0160 </varlistentry>
0161 </variablelist>
0162
0163 For available source types, see the AvailableSourceTypes property.
0164 -->
0165 <method name="SelectSources">
0166 <arg type="o" name="session_handle" direction="in"/>
0167 <arg type="a{sv}" name="options" direction="in"/>
0168 <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap" />
0169 <arg type="o" name="handle" direction="out"/>
0170 </method>
0171 <!--
0172 Start:
0173 @session_handle: Object path for the #org.freedesktop.portal.Session object
0174 @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
0175 @options: Vardict with optional further information
0176 @handle: Object path for the #org.freedesktop.portal.Request object representing this call
0177
0178 Start the screen cast session. This will typically result the portal
0179 presenting a dialog letting the user do the selection set up by
0180 org.freedesktop.portal.ScreenCast.SelectSources(). An application can
0181 only attempt start a session once.
0182
0183 A screen cast session may only be started after having selected sources
0184 using org.freedesktop.portal.ScreenCast.SelectSources().
0185
0186 Supported keys in the @options vardict include:
0187 <variablelist>
0188 <varlistentry>
0189 <term>handle_token s</term>
0190 <listitem><para>
0191 A string that will be used as the last element of the @handle. Must be a valid
0192 object path element. See the #org.freedesktop.portal.Request documentation for
0193 more information about the @handle.
0194 </para></listitem>
0195 </varlistentry>
0196 </variablelist>
0197
0198 The following results get returned via the
0199 #org.freedesktop.portal.Request::Response signal:
0200 <variablelist>
0201 <varlistentry>
0202 <term>streams a(ua{sv})</term>
0203 <listitem><para>
0204 An array of PipeWire streams. Each stream consists of a PipeWire
0205 node ID (the first element in the tuple, and a Vardict of
0206 properties.
0207
0208 The array will contain a single stream if 'multiple' (see
0209 org.freedesktop.portal.ScreenCast.SelectSources())
0210 was set to 'false', or at least one stream if
0211 'multiple' was set to 'true' as part of the
0212 org.freedesktop.portal.ScreenCast.SelectSources() method.
0213 </para></listitem>
0214 </varlistentry>
0215 <varlistentry>
0216 <term>restore_token s</term>
0217 <listitem><para>
0218 The restore token. This token is a single use token that can later
0219 be used to restore a session. See
0220 org.freedesktop.portal.ScreenCast.SelectSources() for details.
0221
0222 This response option was added in version 4 of this interface.
0223 </para></listitem>
0224 </varlistentry>
0225 </variablelist>
0226
0227 Stream properties include:
0228 <variablelist>
0229 <varlistentry>
0230 <term>id s</term>
0231 <listitem><para>
0232 Opaque identifier. Will be unique for this stream and local to this
0233 session. Will persist with future sessions, if they are restored
0234 using a restore token. This property was added in version 4 of this
0235 interface. Optional.
0236 </para></listitem>
0237 </varlistentry>
0238 <varlistentry>
0239 <term>position (ii)</term>
0240 <listitem><para>
0241 A tuple consisting of the position (x, y) in the compositor
0242 coordinate space. Note that the position may not be equivalent to a
0243 position in a pixel coordinate space. Only available for monitor
0244 streams. Optional.
0245 </para></listitem>
0246 </varlistentry>
0247 <varlistentry>
0248 <term>size (ii)</term>
0249 <listitem><para>
0250 A tuple consisting of (width, height). The size represents the size
0251 of the stream as it is displayed in the compositor coordinate
0252 space. Note that this size may not be equivalent to a size in a
0253 pixel coordinate space. The size may differ from the size of the
0254 stream. Optional.
0255 </para></listitem>
0256 </varlistentry>
0257 <varlistentry>
0258 <term>source_type u</term>
0259 <listitem><para>
0260 The type of the content which is being screen casted.
0261 For available source types, see the AvailableSourceTypes property.
0262 This property was added in version 3 of this interface.
0263 </para></listitem>
0264 </varlistentry>
0265 </variablelist>
0266 -->
0267 <method name="Start">
0268 <arg type="o" name="session_handle" direction="in"/>
0269 <arg type="s" name="parent_window" direction="in"/>
0270 <arg type="a{sv}" name="options" direction="in"/>
0271 <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap" />
0272 <arg type="o" name="handle" direction="out"/>
0273 </method>
0274 <!--
0275 OpenPipeWireRemote:
0276 @session_handle: Object path for the #org.freedesktop.portal.Session object
0277 @options: Vardict with optional further information
0278 @fd: File descriptor of an open PipeWire remote.
0279
0280 Open a file descriptor to the PipeWire remote where the screen cast
0281 streams are available. The file descriptor should be used to create a
0282 <classname>pw_core</classname> object, by using
0283 <function>pw_context_connect_fd</function>. Only the screen cast stream
0284 nodes will be available from this PipeWire node.
0285 -->
0286 <method name="OpenPipeWireRemote">
0287 <annotation name="org.gtk.GDBus.C.Name" value="open_pipewire_remote"/>
0288 <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
0289 <arg type="o" name="session_handle" direction="in"/>
0290 <arg type="a{sv}" name="options" direction="in"/>
0291 <arg type="h" name="fd" direction="out"/>
0292 <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap" />
0293 </method>
0294 <!--
0295 AvailableSourceTypes:
0296
0297 A bitmask of available source types. Currently defined types are:
0298
0299 <simplelist>
0300 <member>1: MONITOR</member>
0301 <member>2: WINDOW</member>
0302 <member>4: VIRTUAL</member>
0303 </simplelist>
0304 -->
0305 <property name="AvailableSourceTypes" type="u" access="read"/>
0306 <!--
0307 AvailableCursorModes:
0308
0309 A bitmask of available cursor modes.
0310
0311 Available cursor mode values:
0312 <simplelist>
0313 <member>1: Hidden. The cursor is not part of the screen cast stream.</member>
0314 <member>2: Embedded: The cursor is embedded as part of the stream buffers.</member>
0315 <member>4: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.</member>
0316 </simplelist>
0317
0318 This property was added in version 2 of this interface.
0319 -->
0320 <property name="AvailableCursorModes" type="u" access="read"/>
0321 <property name="version" type="u" access="read"/>
0322 </interface>
0323 </node>