Skip to content
Back to top
View this page

# Web Extensions

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

This documentation describes version 1 of this interface.

## Properties

### org.freedesktop.portal.WebExtensions:version

    version readable u

## Methods

### 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

    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

    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

    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.