.. _org.freedesktop.portal.WebExtensions:

====================================
 Web Extensions
====================================

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

.. _org.freedesktop.portal.WebExtensions Description:

WebExtensions portal

The WebExtensions portal allows sandboxed web browsers to start
native messaging hosts installed on the host system.

Accompanying documentation for Firefox's implementation is
available: `Native messaging for a strictly-confined Firefox
<https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/native-messaging-portal-design.html>`_.

This documentation describes version 1 of this interface.



.. _org.freedesktop.portal.WebExtensions Properties:

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

.. _org.freedesktop.portal.WebExtensions:version:

org.freedesktop.portal.WebExtensions:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.WebExtensions Methods:

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

.. _org.freedesktop.portal.WebExtensions.CreateSession:

org.freedesktop.portal.WebExtensions.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN options a{sv},
      OUT session_handle o
    )



Create a web extensions 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.

To close a session, the browser should:

1. close the process's stdin/stdout/stderr file descriptors
   obtained from the portal;
2. wait for a D-Bus Closed signal from the portal on the
   org.freedesktop.portal.Session object (which will be
   triggered on SIGCHLD via the g_child_watch_add_full
   handler); and
3. if the Closed signal from the portal doesn't come in time,
   call the Close method on the org.freedesktop.portal.Session
   object.

Supported keys in the ``options`` vardict include:
<variablelist>
  <varlistentry>
    <term>mode s</term>
    <listitem><para>
      A string indicating which behaviour the portal should
      use when locating and starting native messaging
      hosts. Valid values are "mozilla" and "chromium". By
      default, mozilla behaviour is used.
    </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>



options
  Vardict with optional further information

session_handle
  Object path for the `org.freedesktop.portal.Session`_ created by this call.



.. _org.freedesktop.portal.WebExtensions.GetManifest:

org.freedesktop.portal.WebExtensions.GetManifest
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetManifest (
      IN session_handle o,
      IN name s,
      IN extension_or_origin s,
      OUT json_manifest s
    )



Return the JSON manifest of the native messaging host that
Start would invoke.



session_handle
  Object path for the `org.freedesktop.portal.Session`_ object

name
  name of the native messaging host

extension_or_origin
  extension ID or origin URI identifying the extension

json_manifest
  the JSON manifest for the native messaging host



.. _org.freedesktop.portal.WebExtensions.Start:

org.freedesktop.portal.WebExtensions.Start
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Start (
      IN session_handle o,
      IN name s,
      IN extension_or_origin s,
      IN options a{sv},
      OUT handle o
    )



Start the named native messaging host. The caller must
indicate the requesting web extension (either by extension ID
for Firefox, or origin URI for Chrome), which will be matched
against the host's access control list.

If the host can't be started, or invalid data is provided,
the session will be 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>
</variablelist>



session_handle
  Object path for the `org.freedesktop.portal.Session`_ object

name
  name of the native messaging host

extension_or_origin
  extension ID or origin URI identifying the extension

options
  Vardict with optional further information

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



.. _org.freedesktop.portal.WebExtensions.GetPipes:

org.freedesktop.portal.WebExtensions.GetPipes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetPipes (
      IN session_handle o,
      IN options a{sv},
      OUT stdin h,
      OUT stdout h,
      OUT stderr h
    )



Retrieve file descriptors for the native messaging host
identified by the session. This method should only be called
after the Start request recveives a successful response.



session_handle
  Object path for the `org.freedesktop.portal.Session`_ object

options
  Vardict with optional further information

stdin
  File descriptor representing the hosts's stdin.

stdout
  File descriptor representing the host's stdout.

stderr
  File descriptor representing the host's stderr.


