org.freedesktop.portal.ScreenCast.xml

<?xml version="1.0"?>
<!--
 Copyright (C) 2017-2018 Red Hat, Inc.

 SPDX-License-Identifier: LGPL-2.1-or-later

 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.1 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 :ref:`org.freedesktop.portal.Request` object representing this call

        Create a screen cast session. A successfully created session can at
        any time be closed using :ref:`org.freedesktop.portal.Session.Close`, or may
        at any time be closed by the portal implementation, which will be
        signalled via :ref:`org.freedesktop.portal.Session::Closed`.

        Supported keys in the @options vardict include:

        * ``handle_token`` (``s``)

          A string that will be used as the last element of the @handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
          more information about the @handle.

        * ``session_handle_token`` (``s``)

          A string that will be used as the last element of the session handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Session` documentation for
          more information about the session handle.

        The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

        * ``session_handle`` (``o``)

          The session handle. An object path for the
          :ref:`org.freedesktop.portal.Session` object representing the created
          session.
    -->
    <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 :ref:`org.freedesktop.portal.Session` object
        @options: Vardict with optional further information
        @handle: Object path for the :ref:`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:

        * ``handle_token`` (``s``)

          A string that will be used as the last element of the @handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
          more information about the @handle.

        * ``types`` (``u``)

          Bitmask of what types of content to record. Default is MONITOR.

        * ``multiple`` (``b``)

          Whether to allow selecting multiple sources. Default is no.

        * ``cursor_mode`` (``u``)

          Determines how the cursor will be drawn in the screen cast stream. It must be
          one of the cursor modes advertised in
          :ref:`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.

        * ``restore_token`` (``s``)

          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 :ref:`org.freedesktop.portal.RemoteDesktop` interface.

          This option was added in version 4 of this interface.

        * ``persist_mode`` (``u``)

          How this session should persist. Default is 0. Accepted values are:

          - ``0``: Do not persist (default)
          - ``1``: Permissions persist as long as the application is running
          - ``2``: Permissions persist until explicitly revoked

          Setting persist_mode is only allowed for screen cast sessions. Persistent
          remote desktop screen cast sessions can only be handled via the
          :ref:`org.freedesktop.portal.RemoteDesktop` interface.

          If the permission for the session to persist is granted, a restore token will
          be returned via the :ref:`org.freedesktop.portal.Request::Response` signal of the
          :ref:`org.freedesktop.portal.ScreenCast.Start` method.

          This option was added in version 4 of this interface.

        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 :ref:`org.freedesktop.portal.Session` object
        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
        @options: Vardict with optional further information
        @handle: Object path for the :ref:`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:

        * ``handle_token`` (``s``)

          A string that will be used as the last element of the @handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
          more information about the @handle.

        The following results get returned via the
        :ref:`org.freedesktop.portal.Request::Response` signal:

        * ``streams`` (``a(ua{sv})``)

          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.

          Each stream contains the following properties:

          * ``id`` (``s``)

            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.

          * ``position`` (``(ii)``)

            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.

          * ``size`` (``(ii)``)

            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.

          * ``source_type`` (``u``)

            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.

          * ``mapping_id`` (``s``)

            An optional identifier used to map different aspects of the
            resource this stream corresponds to.

            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.

        * ``restore_token`` (``s``)

          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.
    -->
    <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 :ref:`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:

        - ``1``: MONITOR: Share existing monitors
        - ``2``: WINDOW: Share application windows
        - ``4``: VIRTUAL: Extend with new virtual monitor
    -->
    <property name="AvailableSourceTypes" type="u" access="read"/>
    <!--
        AvailableCursorModes:

        A bitmask of available cursor modes.

        Available cursor mode values:

        - ``1``: Hidden. The cursor is not part of the screen cast stream.
        - ``2``: Embedded: The cursor is embedded as part of the stream buffers.
        - ``4``: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.

        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>