.. _org.freedesktop.portal.OpenURI:

==============================
OpenURI
==============================

-----------
Description
-----------

.. _org.freedesktop.portal.OpenURI Description:

Portal for opening URIs

The OpenURI portal allows sandboxed applications to open
URIs (e.g. a http: link to the applications homepage)
under the control of the user.

This documentation describes version 4 of this interface.



.. _org.freedesktop.portal.OpenURI Properties:

----------
Properties
----------

.. _org.freedesktop.portal.OpenURI:version:

org.freedesktop.portal.OpenURI:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.OpenURI Methods:

-------
Methods
-------

.. _org.freedesktop.portal.OpenURI.OpenURI:

org.freedesktop.portal.OpenURI.OpenURI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    OpenURI (
      IN parent_window s,
      IN uri s,
      IN options a{sv},
      OUT handle o
    )



Asks to open a URI.

Note that ``file://`` URIs are explicitly not supported by this method.
To request opening local files, use `org.freedesktop.portal.OpenURI.OpenFile`_.

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

* ``writable`` (``b``)

  Whether to allow the chosen application to write to the file.

  This key only takes effect the uri points to a local file that
  is exported in the document portal, and the chosen application
  is sandboxed itself.

* ``ask`` (``b``)

  Whether to ask the user to choose an app. If this is not passed, or false,
  the portal may use a default or pick the last choice.

  The ask option was introduced in version 3 of the interface.

* ``activation_token`` (``s``)

  A token that can be used to activate the chosen application.

  The activation_token option was introduced in version 4 of the interface.



parent_window
  Identifier for the application window, see :doc:`window-identifiers`

uri
  The uri to open

options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.OpenURI.OpenFile:

org.freedesktop.portal.OpenURI.OpenFile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    OpenFile (
      IN parent_window s,
      IN fd h,
      IN options a{sv},
      OUT handle o
    )



Asks to open a local file.

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

* ``writable`` (``b``)

  Whether to allow the chosen application to write to the file.

  This key only takes effect the uri points to a local file that is
  exported in the document portal, and the chosen application is
  sandboxed itself.

* ``ask`` (``b``)

  Whether to ask the user to choose an app. If this is not passed, or false,
  the portal may use a default or pick the last choice.

  The ask option was introduced in version 3 of the interface.

* ``activation_token`` (``s``)

  A token that can be used to activate the chosen application.

  The activation_token option was introduced in version 4 of the interface.

The OpenFile method was introduced in version 2 of the OpenURI portal API.



parent_window
  Identifier for the application window, see :doc:`window-identifiers`

fd
  File descriptor for the file to open

options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.OpenURI.OpenDirectory:

org.freedesktop.portal.OpenURI.OpenDirectory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    OpenDirectory (
      IN parent_window s,
      IN fd h,
      IN options a{sv},
      OUT handle o
    )



Asks to open the directory containing a local file in the file browser. This is implemented using
the ``org.freedesktop.FileManager1.ShowItems()`` D-Bus API and if that service doesn't exist falls back
to the ``OpenURI`` method on the directory of the file.

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

* ``activation_token`` (``s``)

  A token that can be used to activate the chosen application.

  The activation_token option was introduced in version 4 of the interface.

The OpenDirectory method was introduced in version 3 of the OpenURI portal API.



parent_window
  Identifier for the application window, see :doc:`window-identifiers`

fd
  File descriptor for a file

options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call