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 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        This documentation describes version 3 of this interface.
  31   -->
  32   <interface name="org.freedesktop.portal.OpenURI">
  33     <!--
  34         OpenURI:
  35         @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
  36         @uri: The uri to open
  37         @options: Vardict with optional further onformation
  38         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
  39
  40         Asks to open a uri.
  41
  42         Note that file:// uris are explicitly not supported by this method.
  43         To request opening local files, use org.freedesktop.portal.OpenURI.OpenFile().
  44
  45         Supported keys in the @options vardict include:
  46         <variablelist>
  47           <varlistentry>
  48             <term>handle_token s</term>
  49             <listitem><para>
  50               A string that will be used as the last element of the @handle. Must be a valid
  51               object path element. See the #org.freedesktop.portal.Request documentation for
  52               more information about the @handle.
  53             </para></listitem>
  54           </varlistentry>
  55           <varlistentry>
  56             <term>writable b</term>
  57             <listitem><para>
  58               Whether to allow the chosen application to write to the file.
  59             </para><para>
  60               This key only takes effect the uri points to a local file that
  61               is exported in the document portal, and the chosen application
  62               is sandboxed itself.
  63             </para></listitem>
  64           </varlistentry>
  65           <varlistentry>
  66             <term>ask b</term>
  67             <listitem><para>
  68               Whether to ask the user to choose an app. If this is not passed, or false,
  69               the portal may use a default or pick the last choice.
  70             </para><para>
  71               The ask option was introduced in version 3 of the interface.
  72             </para></listitem>
  73           </varlistentry>
  74         </variablelist>
  75
  76     -->
  77     <method name="OpenURI">
  78       <arg type="s" name="parent_window" direction="in"/>
  79       <arg type="s" name="uri" direction="in"/>
  80       <arg type="a{sv}" name="options" direction="in"/>
  81       <arg type="o" name="handle" direction="out"/>
  82     </method>
  83
  84     <!--
  85         OpenFile:
  86         @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
  87         @fd: File descriptor for the file to open
  88         @options: Vardict with optional further onformation
  89         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
  90
  91         Asks to open a local file.
  92
  93         Supported keys in the @options vardict include:
  94         <variablelist>
  95           <varlistentry>
  96             <term>handle_token s</term>
  97             <listitem><para>
  98               A string that will be used as the last element of the @handle. Must be a valid
  99               object path element. See the #org.freedesktop.portal.Request documentation for
 100               more information about the @handle.
 101             </para></listitem>
 102           </varlistentry>
 103           <varlistentry>
 104             <term>writable b</term>
 105             <listitem><para>
 106               Whether to allow the chosen application to write to the file.
 107             </para><para>
 108               This key only takes effect the uri points to a local file that
 109               is exported in the document portal, and the chosen application
 110               is sandboxed itself.
 111             </para></listitem>
 112           </varlistentry>
 113           <varlistentry>
 114             <term>ask b</term>
 115             <listitem><para>
 116               Whether to ask the user to choose an app. If this is not passed, or false,
 117               the portal may use a default or pick the last choice.
 118             </para><para>
 119               The ask option was introduced in version 3 of the interface.
 120             </para></listitem>
 121           </varlistentry>
 122         </variablelist>
 123
 124         The OpenFile method was introduced in version 2 of the OpenURI portal API.
 125     -->
 126     <method name="OpenFile">
 127       <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
 128       <arg type="s" name="parent_window" direction="in"/>
 129       <arg type="h" name="fd" direction="in"/>
 130       <arg type="a{sv}" name="options" direction="in"/>
 131       <arg type="o" name="handle" direction="out"/>
 132     </method>
 133
 134     <!--
 135         OpenDirectory:
 136         @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
 137         @fd: File descriptor for a file
 138         @options: Vardict with optional further onformation
 139         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
 140
 141         Asks to open the directory containing a local file in the file browser.
 142
 143         Supported keys in the @options vardict include:
 144         <variablelist>
 145           <varlistentry>
 146             <term>handle_token s</term>
 147             <listitem><para>
 148               A string that will be used as the last element of the @handle. Must be a valid
 149               object path element. See the #org.freedesktop.portal.Request documentation for
 150               more information about the @handle.
 151             </para></listitem>
 152           </varlistentry>
 153         </variablelist>
 154
 155         The OpenDirectory method was introduced in version 3 of the OpenURI portal API.
 156     -->
 157     <method name="OpenDirectory">
 158       <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
 159       <arg type="s" name="parent_window" direction="in"/>
 160       <arg type="h" name="fd" direction="in"/>
 161       <arg type="a{sv}" name="options" direction="in"/>
 162       <arg type="o" name="handle" direction="out"/>
 163     </method>
 164
 165     <property name="version" type="u" access="read"/>
 166   </interface>
 167 </node>