diff options
Diffstat (limited to 'docs/reference/pygio-mountoperation.xml')
| -rw-r--r-- | docs/reference/pygio-mountoperation.xml | 726 |
1 files changed, 726 insertions, 0 deletions
diff --git a/docs/reference/pygio-mountoperation.xml b/docs/reference/pygio-mountoperation.xml new file mode 100644 index 0000000..9648097 --- /dev/null +++ b/docs/reference/pygio-mountoperation.xml @@ -0,0 +1,726 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giomountoperation"> + <refnamediv> + <refname>gio.MountOperation</refname> + <refpurpose>Application launch context.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.MountOperation</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giomountoperation">gio.MountOperation</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-anonymous">get_anonymous</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-choice">get_choice</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-domain">get_domain</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-password">get_password</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-password-save">get_password_save</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-username">get_username</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--reply">replay</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-anonymous">set_anonymous</link></methodname> + <methodparam><parameter role="keyword">anonymous</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-choice">set_choice</link></methodname> + <methodparam><parameter role="keyword">choice</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-domain">set_domain</link></methodname> + <methodparam><parameter role="keyword">domain</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-password">set_password</link></methodname> + <methodparam><parameter role="keyword">password</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-password-save">set_password_save</link></methodname> + <methodparam><parameter role="keyword">save</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-username">set_username</link></methodname> + <methodparam><parameter role="keyword">username</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giomountoperation">gio.MountOperation</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giomountoperation"> + <title>gio.MountOperation Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"anonymous"</entry> + <entry>Read/Write</entry> + <entry> + Whether to use an anonymous user when authenticating. + Default value: <literal>False</literal> + </entry> + </row> + <row valign="top"> + <entry>"choice"</entry> + <entry>Read/Write</entry> + <entry> + The index of the user's choice when a question is asked during + the mount operation. See the "ask-question" signal. + Allowed values: >= 0 Default value: 0 + </entry> + </row> + <row valign="top"> + <entry>"domain"</entry> + <entry>Read/Write</entry> + <entry> + The domain to use for the mount operation. Default value: <literal>None</literal> + </entry> + </row> + <row valign="top"> + <entry>"password"</entry> + <entry>Read/Write</entry> + <entry> + The password that is used for authentication when carrying out the + mount operation. Default value: <literal>None</literal> + </entry> + </row> + <row valign="top"> + <entry>"password-save"</entry> + <entry>Read/Write</entry> + <entry> + Determines if and how the password information should be saved. + Default value: gio.PASSWORD_SAVE_NEVER + </entry> + </row> + <row valign="top"> + <entry>"username"</entry> + <entry>Read/Write</entry> + <entry> + The user name that is used for authentication when carrying out the + mount operation. Default value: <literal>None</literal> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1 id="signal-prototypes-giomountoperation"> + <title>gio.MountOperation Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <variablelist> + <varlistentry> + <term><link linkend="signal-giomountoperation--aborted">"aborted"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--ask-password">"ask-password"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>default_user</parameter></methodparam> + <methodparam><parameter>default_domain</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--ask-question">"ask-question"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>choices</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--reply">"reply"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>result</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + provides a mechanism for authenticating mountable operations, such as loop mounting files, + hard drive partitions or server locations. + </para> + <para> + Mounting operations are handed a + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + that then can use if they require any privileges or authentication for their volumes to be + mounted (e.g. a hard disk partition or an encrypted filesystem), or if they are implementing + a remote server protocol which requires user credentials such as FTP or WebDAV. + </para> + <para> + Users should instantiate a subclass of this that implements all the various callbacks + to show the required dialogs, such as + <link linkend="class-gtkmountoperation"><classname>gtk.MountOperation</classname></link>. + </para> + </refsect1> + + <refsect1 id="constructor-giomountoperation"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.MountOperation</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new mount operation. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giomountoperation--get-anonymous"> + <title>gio.MountOperation.get_anonymous</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_anonymous</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if mount operation is anonymous. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_anonymous</methodname>() method check to see whether + the mount operation is being used for an anonymous user + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-choice"> + <title>gio.MountOperation.get_choice</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_choice</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer containing an index of the user's + choice from the choice's list, or 0. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_anonymous</methodname>() method gets a choice + from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-domain"> + <title>gio.MountOperation.get_domain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_domain</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string set to the domain. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_domain</methodname>() method gets the domain + of the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-password"> + <title>gio.MountOperation.get_password</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_password</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the password within + the mountoperation. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_password</methodname>() method gets a password + from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-password-save"> + <title>gio.MountOperation.get_password_save</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_password_save</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <xref linkend="gio-password-save-constants" endterm="gio-password-save-constants-title"></xref> + flag. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_password_save</methodname>() method gets the state + of saving passwords for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-username"> + <title>gio.MountOperation.get_username</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_username</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the user name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_username</methodname>() method get the user + name from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--reply"> + <title>gio.MountOperation.reply</title> + + <programlisting><methodsynopsis language="python"> + <methodname>reply</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>result</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-mount-operation-result-constants" endterm="gio-mount-operation-result-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>reply</methodname>() method emits the "reply" signal. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-anonymous"> + <title>gio.MountOperation.set_anonymous</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_anonymous</methodname> + <methodparam><parameter role="keyword">anonymous</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>anonymous</parameter> :</term> + <listitem><simpara>boolean value. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_anonymous</methodname>() method sets the mount operation + to use an anonymous user if anonymous is <literal>True</literal>. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-choice"> + <title>gio.MountOperation.set_choice</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_choice</methodname> + <methodparam><parameter role="keyword">choice</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>choice</parameter> :</term> + <listitem><simpara>an integer. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_choice</methodname>() method sets a default choice for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-domain"> + <title>gio.MountOperation.set_domain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_domain</methodname> + <methodparam><parameter role="keyword">domain</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>domain</parameter> :</term> + <listitem><simpara>the domain to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_domain</methodname>() method sets the mount operation's domain. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-password"> + <title>gio.MountOperation.set_password</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_password</methodname> + <methodparam><parameter role="keyword">password</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>password</parameter> :</term> + <listitem><simpara>password to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_password</methodname>() method sets the mount + operation's password to password. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-password-save"> + <title>gio.MountOperation.set_password_save</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_password_save</methodname> + <methodparam><parameter role="keyword">save</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>save</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-password-save-constants" endterm="gio-password-save-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_password_save</methodname>() method sets the state + of saving passwords for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-username"> + <title>gio.MountOperation.set_username</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_username</methodname> + <methodparam><parameter role="keyword">username</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>username</parameter> :</term> + <listitem><simpara>input username. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_anonymous</methodname>() method sets the user + name within op to username. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-giomountoperation--aborted"> + <title>The "aborted" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</term> + <listitem><simpara>the first user parameter (if any) specified + with the <link + linkend="method-gobject--connect"><methodname>connect</methodname>()</link> + method</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional user parameters (if any)</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress. + Implementations of <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + should handle this signal by dismissing open password dialogs. + </para> + </refsect2> + + <refsect2 id="signal-giomountoperation--ask-password"> + <title>The "ask-password" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>default_user</parameter></methodparam> + <methodparam><parameter>default_domain</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter> :</term> + <listitem><simpara>string containing a message to display to the user.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>default_user</parameter> :</term> + <listitem><simpara>string containing the default user name.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>default_domain</parameter> :</term> + <listitem><simpara>string containing the default domain.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-ask-password-flags-constants" endterm="gio-ask-password-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</term> + <listitem><simpara>the first user parameter (if any) specified + with the <link + linkend="method-gobject--connect"><methodname>connect</methodname>()</link> + method</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional user parameters (if any)</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + This signal is emitted when a mount operation asks the user for a password. + If the message contains a line break, the first line should be presented as a heading. + For example, it may be used as the primary text in a + <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>. + </para> + </refsect2> + + <refsect2 id="signal-giomountoperation--ask-question"> + <title>The "ask-question" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>choices</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter> :</term> + <listitem><simpara>string containing a message to display to the user.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>choices</parameter> :</term> + <listitem><simpara>a list of strings for each possible choice.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</term> + <listitem><simpara>the first user parameter (if any) specified + with the <link + linkend="method-gobject--connect"><methodname>connect</methodname>()</link> + method</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional user parameters (if any)</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + This signal is emitted when asking the user a question and gives a list of choices + for the user to choose from. If the message contains a line break, the first line should be + presented as a heading. For example, it may be used as the primary text in a + <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>. + </para> + </refsect2> + + <refsect2 id="signal-giomountoperation--reply"> + <title>The "reply" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>result</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>result</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-mount-operation-result-constants" endterm="gio-mount-operation-result-constants-title"></xref> + indicating how the request was handled</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</term> + <listitem><simpara>the first user parameter (if any) specified + with the <link + linkend="method-gobject--connect"><methodname>connect</methodname>()</link> + method</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional user parameters (if any)</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + This signal is emitted when the user has replied to the mount operation. + </para> + </refsect2> + + </refsect1> +</refentry> |