Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Request

## Description

Shared request interface

The Request interface is shared by all portal interfaces. When a portal method is called, the reply includes a handle (i.e. object path) for a Request object, which will stay alive for the duration of the user interaction related to the method call.

The portal indicates that a portal request interaction is over by emitting the org.freedesktop.portal.Request::Response signal on the Request object.

The application can abort the interaction calling org.freedesktop.portal.Request.Close on the Request object.

Since version 0.9 of xdg-desktop-portal, the handle will be of the form

    /org/freedesktop/portal/desktop/request/SENDER/TOKEN

where `SENDER` is the callers unique name, with the initial `':'` removed and all `'.'` replaced by `'_'`, and `TOKEN` is a unique token that the caller provided with the handle_token key in the options vardict.

This change was made to let applications subscribe to the Response signal before making the initial portal call, thereby avoiding a race condition. It is recommended that the caller should verify that the returned handle is what it expected, and update its signal subscription if it isn’t. This ensures that applications will work with both old and new versions of xdg-desktop-portal.

The token that the caller provides should be unique and not guessable. To avoid clashes with calls made from unrelated libraries, it is a good idea to use a per-library prefix combined with a random number.

## Methods

### org.freedesktop.portal.Request.Close

    Close ()

Closes the portal request to which this object refers and ends all related user interaction (dialogs, etc).

A Response signal will not be emitted in this case.

## Signals

### org.freedesktop.portal.Request::Response

    Response (
      response u,
      results a{sv}
    )

Emitted when the user interaction for a portal request is over.

The `response` indicates how the user interaction ended:

- 0: Success, the request is carried out

- 1: The user cancelled the interaction

- 2: The user interaction was ended in some other way

response

  Numeric response

results

  Vardict with results. The keys and values in the vardict depend on the request.