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>