gio/org.freedesktop.portal.OpenURI.xml

   1 <?xml version="1.0"?>
   2 <!--
   3  Copyright (C) 2016 Red Hat, Inc.
   4
   5  This library is free software; you can redistribute it and/or
   6  modify it under the terms of the GNU Lesser General Public
   7  License as published by the Free Software Foundation; either
   8  version 2.1 of the License, or (at your option) any later version.
   9
  10  This library is distributed in the hope that it will be useful,
  11  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  Lesser General Public License for more details.
  14
  15  You should have received a copy of the GNU Lesser General Public
  16  License along with this library. If not, see <http://www.gnu.org/licenses/>.
  17
  18  Author: Matthias Clasen <mclasen@redhat.com>
  19 -->
  20
  21 <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  22   <!--
  23        org.freedesktop.portal.OpenURI:
  24        @short_description: Portal for opening URIs
  25
  26        The OpenURI portal allows sandboxed applications to open
  27        URIs (e.g. a http: link to the applications homepage)
  28        under the control of the user.
  29   -->
  30   <interface name="org.freedesktop.portal.OpenURI">
  31     <!--
  32         OpenURI:
  33         @parent_window: Identifier for the application window
  34         @uri: The uri to open
  35         @options: Vardict with optional further onformation
  36         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
  37
  38         Asks to open a uri.
  39
  40         The @parent_window identifier must be of the form "x11:$XID" for an X11
  41         window. Support for other window systems may be added in the future.
  42
  43         Note that file:// uris are explicitly not supported by this method.
  44         To request opening local files, use org.freedesktop.portal.OpenFile().
  45
  46         Supported keys in the @options vardict include:
  47         <variablelist>
  48           <varlistentry>
  49             <term>writable b</term>
  50             <listitem><para>
  51               Whether to allow the chosen application to write to the file.
  52             </para><para>
  53               This key only takes effect the uri points to a local file that
  54               is exported in the document portal, and the chosen application
  55               is sandboxed itself.
  56             </para></listitem>
  57           </varlistentry>
  58         </variablelist>
  59
  60     -->
  61     <method name="OpenURI">
  62       <arg type="s" name="parent_window" direction="in"/>
  63       <arg type="s" name="uri" direction="in"/>
  64       <arg type="a{sv}" name="options" direction="in"/>
  65       <arg type="o" name="handle" direction="out"/>
  66     </method>
  67
  68     <!--
  69         OpenFile:
  70         @parent_window: Identifier for the application window
  71         @fd: File descriptor for the file to open
  72         @options: Vardict with optional further onformation
  73         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
  74
  75         Asks to open a local file.
  76
  77         The @parent_window identifier must be of the form "x11:$XID" for an X11
  78         window. Support for other window systems may be added in the future.
  79
  80         Supported keys in the @options vardict include:
  81         <variablelist>
  82           <varlistentry>
  83             <term>writable b</term>
  84             <listitem><para>
  85               Whether to allow the chosen application to write to the file.
  86             </para><para>
  87               This key only takes effect the uri points to a local file that
  88               is exported in the document portal, and the chosen application
  89               is sandboxed itself.
  90             </para></listitem>
  91           </varlistentry>
  92         </variablelist>
  93
  94         The OpenFile method was introduced in version 2 of the OpenURI portal API.
  95     -->
  96     <method name="OpenFile">
  97       <arg type="s" name="parent_window" direction="in"/>
  98       <arg type="h" name="fd" direction="in"/>
  99       <arg type="a{sv}" name="options" direction="in"/>
 100       <arg type="o" name="handle" direction="out"/>
 101     </method>
 102
 103     <property name="version" type="u" access="read"/>
 104   </interface>
 105 </node>