path: root/docs/reference/pygio-mount.xml

<?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-giomount">
    <refnamediv>
        <refname>gio.Mount</refname>
        <refpurpose>Mount management</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gio.Mount</classname></ooclass>
        <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>

    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--can-eject">can_eject</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis><methodsynopsis language="python">
        <methodname><link linkend="method-giomount--can-unmount">can_unmount</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--eject">eject</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--eject-finish">eject_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-drive">get_drive</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-icon">get_icon</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-name">get_name</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-root">get_root</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-uuid">get_uuid</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--get-volume">get_volume</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--guess-content-type">guess_content_type</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">force_rescan</parameter></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--guess-content-type-finish">guess_content_type_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--guess-content-type-sync">guess_content_type_sync</link></methodname>
        <methodparam><parameter role="keyword">force_rescan</parameter></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--is-shadowed">is_shadowed</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--remount">remount</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">mount_operation</parameter><initializer><literal>None</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--remount-finish">remount_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--shadow">shadow</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--unmount">unmount</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--unmount-finish">unmount_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giomount--unshadow">unshadow</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    
    </classsynopsis>

    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
  +-- <link linkend="class-giomount">gio.Mount</link>
</synopsis>

    </refsect1>
    
    <refsect1>
	<title>Prerequisites</title>
        <para>
            <link linkend="class-giomount"><classname>gio.Mount</classname></link> requires
            <link linkend="class-gobject"><classname>gobject.GObject</classname></link>
        </para>
    </refsect1>

    <refsect1 id="signal-prototypes-giomount">
        <title>gio.Mount Signal Prototypes</title>
  
        <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
  
        <variablelist>
            <varlistentry>
                <term><link linkend="signal-giomount--aborted">"aborted"</link></term>
                <listitem>
                    <methodsynopsis language="python"><methodname>callback</methodname>
                        <methodparam><parameter>mount</parameter></methodparam>
                        <methodparam><parameter>user_param1</parameter></methodparam>
                        <methodparam><parameter>...</parameter></methodparam>
                    </methodsynopsis>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><link linkend="signal-giomount--changed">"changed"</link></term>
                <listitem>
                    <methodsynopsis language="python"><methodname>callback</methodname>
                        <methodparam><parameter>mount</parameter></methodparam>
                        <methodparam><parameter>user_param1</parameter></methodparam>
                        <methodparam><parameter>...</parameter></methodparam>
                    </methodsynopsis>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><link linkend="signal-giomount--unmounted">"unmounted"</link></term>
                <listitem>
                    <methodsynopsis language="python"><methodname>callback</methodname>
                        <methodparam><parameter>mount</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-giomount"><classname>gio.Mount</classname></link>
            interface represents user-visible mounts. Note, when porting from GnomeVFS,
            <link linkend="class-giomount"><classname>gio.Mount</classname></link>
            is the moral equivalent of GnomeVFSVolume.
            
        </para>
        <para>
            <link linkend="class-giomount"><classname>gio.Mount</classname></link>
            is a "mounted" filesystem that you can access. Mounted is in quotes because
            it's not the same as a unix mount, it might be a gvfs mount, but you can still
            access the files on it if you use GIO. Might or might not be related to a volume object.
        </para>
        <para>
            Unmounting a GMount instance is an asynchronous operation. For more information
            about asynchronous operations, see GAsyncReady and GSimpleAsyncReady. To unmount
            a <link linkend="class-giomount"><classname>gio.Mount</classname></link> instance,
            first call
            g_mount_unmount()
            with (at least) the GMount instance and a GAsyncReadyCallback. The callback will
            be fired when the operation has resolved (either with success or failure), and a
            GAsyncReady structure will be passed to the callback. That callback should then call
            g_mount_unmount_finish()
            with the GMount and the GAsyncReady data to see if the operation was completed successfully.
            If an error is present when g_mount_unmount_finish() is called, then it will be filled
            with any error information.
        </para>
    </refsect1>

    <refsect1>
        <title>Methods</title>
        
        <refsect2 id="method-giomount--can-eject">
            <title>gio.Mount.can_eject</title>

            <programlisting><methodsynopsis language="python">
                <methodname>can_eject</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the mount can be ejected,
                    <literal>False</literal> otherwise.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>can_eject</methodname>() method checks if a mount can be ejected.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--can-unmount">
            <title>gio.Mount.can_unmount</title>

            <programlisting><methodsynopsis language="python">
                <methodname>can_unmount</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the mount can be unmounted,
                    <literal>False</literal> otherwise.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>can_eject</methodname>() method checks if a mount can be unmounted.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--eject">
            <title>gio.Mount.eject</title>

            <programlisting><methodsynopsis language="python">
                <methodname>eject</methodname>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
                  <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
                  <listitem><simpara>flags affecting the unmount if required for eject
                  <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>Optional
                  <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                  object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
                  <listitem><simpara>The data to pass to callback function.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>eject</methodname>() method asynchronously ejects a mount. 
            </para>
            <para>
                When the operation is finished, callback will be called. You can then call
                <methodname><link linkend="method-giomount--eject-finish">gio.Mount.eject_finish</link></methodname>()
                to obtain the result of the operation.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--eject-finish">
            <title>gio.Mount.eject_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>eject_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the mount has been ejected
                    successfully, <literal>False</literal> otherwise.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>eject_finish</methodname>() method finishes ejecting a mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-drive">
            <title>gio.Mount.get_drive</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_drive</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><link linkend="class-giodrive"><classname>gio.Drive</classname></link>
                    or <literal>None</literal> if mount is not associated with a volume or a drive.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_drive</methodname>() method gets the drive for the mount.
            </para>
            <para>
                This is a convenience method for getting the
                <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
                and then using that object to get the
                <link linkend="class-giodrive"><classname>gio.Drive</classname></link>.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-icon">
            <title>gio.Mount.get_icon</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_icon</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><link linkend="class-gioicon"><classname>gio.Icon</classname></link>
                    for the mount.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_icon</methodname>() method gets the icon for mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-name">
            <title>gio.Mount.get_name</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_name</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the name for the given mount.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_name</methodname>() method gets the name of mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-root">
            <title>gio.Mount.get_root</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_root</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link>.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_root</methodname>() method gets the root directory on mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-uuid">
            <title>gio.Mount.get_uuid</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_uuid</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the UUID for mount or <literal>None</literal>
                    if no UUID can be computed.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_uuid</methodname>() method gets the UUID for the mount.
                The reference is typically based on the file system UUID for the mount in
                question and should be considered an opaque string. Returns <literal>None</literal>
                if there is no UUID available
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--get-volume">
            <title>gio.Mount.get_volume</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_volume</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
                    or <literal>None</literal> if mount is not associated with a volume.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_volume</methodname>() method gets the volume for the mount.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--guess-content-type">
            <title>gio.Mount.guess_content_type</title>

            <programlisting><methodsynopsis language="python">
                <methodname>guess_content_type</methodname>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam><parameter role="keyword">force_rescan</parameter></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
                  <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">force_rescan</parameter>&nbsp;:</term>
                  <listitem><simpara>Whether to force a rescan of the content. Otherwise a cached result will be used if available.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>Optional
                  <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                  object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
                  <listitem><simpara>The data to pass to callback function.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>guess_content_type</methodname>() method asynchronously tries to guess the type of
                content stored on mount. Returns one or more textual identifiers of well-known content
                types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory
                cards. See the shared-mime-info specification for more on x-content types.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled
                by triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be returned.
            </para>
            <para>
                When the operation is finished, callback will be called. You can then call
                <methodname><link linkend="method-giomount--guess-content-type-finish">gio.Mount.guess_content_type_finish</link></methodname>()
                to obtain the result of the operation.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--guess-content-type-finish">
            <title>gio.Mount.guess_content_type_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>guess_content_type_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>A list of types or <literal>None</literal> on error.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>guess_content_type_finish</methodname>() method finishes guessing content
                types of mount. If any errors occured during the operation, error will be set to
                contain the errors and FALSE will be returned. In particular, you may get an
                gio.ERROR_NOT_SUPPORTED if the mount does not support content guessing.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--guess-content-type-sync">
            <title>gio.Mount.guess_content_type_sync</title>

            <programlisting><methodsynopsis language="python">
                <methodname>guess_content_type_sync</methodname>
                <methodparam><parameter role="keyword">force_rescan</parameter></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">force_rescan</parameter>&nbsp;:</term>
                  <listitem><simpara>Whether to force a rescan of the content. Otherwise a cached result will be used if available.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>Optional
                  <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                  object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>guess_content_type_sync</methodname>() method tries to guess
                the type of content stored on mount. Returns one or more textual identifiers
                of well-known content types (typically prefixed with "x-content/"), e.g.
                x-content/image-dcf for camera memory cards. See the shared-mime-info specification
                for more on x-content types.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled
                by triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be returned.
            </para>
            <para>
                This is an synchronous operation and as such may block doing IO; see
                <methodname><link linkend="method-giomount--guess-content-type">gio.Mount.guess_content_type</link></methodname>()
                for the asynchronous version.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--is-shadowed">
            <title>gio.Mount.is_shadowed</title>

            <programlisting><methodsynopsis language="python">
                <methodname>is_shadowed</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if mount is shadowed.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>is_shadowed</methodname>() method determines if mount
                is shadowed. Applications or libraries should avoid displaying mount
                in the user interface if it is shadowed.
            </para>
            <para>
                A mount is said to be shadowed if there exists one or more user visible
                objects (currently
                <link linkend="class-giomount"><classname>gio.Mount</classname></link>
                objects) with a root that is inside the root of mount.
            </para>
            <para>
                One application of shadow mounts is when exposing a single file system
                that is used to address several logical volumes. In this situation, a
                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
                implementation would create two
                <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
                objects (for example, one for the camera functionality of the device
                and one for a SD card reader on the device) with activation URIs
                gphoto2://[usb:001,002]/store1/ and gphoto2://[usb:001,002]/store2/.
                When the underlying mount (with root gphoto2://[usb:001,002]/) is
                mounted, said
                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
                implementation would create two
                <link linkend="class-giomount"><classname>gio.Mount</classname></link>
                objects (each with their root matching the corresponding volume
                activation root) that would shadow the original mount.
            </para>
            <para>
                The proxy monitor in GVfs 2.26 and later, automatically creates and
                manage shadow mounts (and shadows the underlying mount) if the activation
                root on a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
                is set.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--remount">
            <title>gio.Mount.remount</title>

            <programlisting><methodsynopsis language="python">
                <methodname>remount</methodname>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">mount_operation</parameter><initializer><literal>None</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
                  <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
                  <listitem><simpara>flags affecting the unmount if required for eject
                  <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">mount_operation</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
                  or <literal>None</literal> to avoid user interaction.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>Optional
                  <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                  object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
                  <listitem><simpara>The data to pass to callback function.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>remount</methodname>() method asynchronously remounts a mount.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled
                by triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be returned.
            </para>
            <para>
                When the operation is finished, callback will be called. You can then call
                <methodname><link linkend="method-giomount--remount-finish">gio.Mount.remount_finish</link></methodname>()
                to obtain the result of the operation.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--remount-finish">
            <title>gio.Mount.remount_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>remount_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the mount has been remounted
                    successfully, <literal>False</literal> otherwise.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>remount_finish</methodname>() method finishes remounting a mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--shadow">
            <title>gio.Mount.shadow</title>

            <programlisting><methodsynopsis language="python">
                <methodname>shadow</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
            </variablelist>
    
            <para>
                The <methodname>shadow</methodname>() method increments the shadow
                count on mount. Usually used by
                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
                implementations when creating a shadow mount for mount, see
                <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
                for more information. The caller will need to emit the "changed"
                signal on mount manually.
            </para>
            
        </refsect2>

        <refsect2 id="method-giomount--unmount">
            <title>gio.Mount.unmount</title>

            <programlisting><methodsynopsis language="python">
                <methodname>unmount</methodname>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
                <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
                  <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
                  <listitem><simpara>flags affecting the unmount if required for eject
                  <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>Optional
                  <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                  object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
                  <listitem><simpara>The data to pass to callback function.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>unmount</methodname>() method asynchronously unmounts a mount.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled
                by triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be returned.
            </para>
            <para>
                When the operation is finished, callback will be called. You can then call
                <methodname><link linkend="method-giomount--unmount-finish">gio.Mount.unmount_finish</link></methodname>()
                to obtain the result of the operation.
            </para>
        </refsect2>

        <refsect2 id="method-giomount--unmount-finish">
            <title>gio.Mount.unmount_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>unmount_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the mount has been unmounted
                    successfully, <literal>False</literal> otherwise.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>unmount_finish</methodname>() method finishes unmounting a mount.
            </para>
        </refsect2>
        
        <refsect2 id="method-giomount--unshadow">
            <title>gio.Mount.unshadow</title>

            <programlisting><methodsynopsis language="python">
                <methodname>unshadow</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
            </variablelist>
    
            <para>
                The <methodname>unshadow</methodname>() method decrements the shadow
                count on mount. Usually used by
                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
                implementations when destroying a shadow mount for mount, see
                <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
                for more information. The caller will need to emit the "changed"
                signal on mount manually.
            </para>
            
        </refsect2>
    </refsect1>

    <refsect1>
        <title>Signals</title>
    
        <refsect2 id="signal-giomount--aborted">
            <title>The "aborted" gio.Mount Signal</title>
      
            <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
                <methodparam><parameter>mount</parameter></methodparam>
                <methodparam><parameter>user_param1</parameter></methodparam>
                <methodparam><parameter>...</parameter></methodparam>
            </methodsynopsis></programlisting>
      
            <variablelist>
                <varlistentry>
                    <term><parameter>mount</parameter>&nbsp;:</term>
                    <listitem><simpara>the mount</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>user_param1</parameter>&nbsp;:</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>&nbsp;:</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.
            </para>
            <para>
                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-giomount--changed">
            <title>The "changed" gio.Mount Signal</title>
      
            <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
                <methodparam><parameter>mount</parameter></methodparam>
                <methodparam><parameter>user_param1</parameter></methodparam>
                <methodparam><parameter>...</parameter></methodparam>
            </methodsynopsis></programlisting>
      
            <variablelist>
                <varlistentry>
                    <term><parameter>mount</parameter>&nbsp;:</term>
                    <listitem><simpara>the mount</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>user_param1</parameter>&nbsp;:</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>&nbsp;:</term>
                    <listitem><simpara>additional user parameters (if any)</simpara></listitem>
                </varlistentry>
            </variablelist>
      
            <para>
                Emitted when the mount has been changed.
            </para>
        </refsect2>
    
        <refsect2 id="signal-giomount--unmounted">
            <title>The "unmounted" gio.Mount Signal</title>
      
            <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
                <methodparam><parameter>mount</parameter></methodparam>
                <methodparam><parameter>user_param1</parameter></methodparam>
                <methodparam><parameter>...</parameter></methodparam>
            </methodsynopsis></programlisting>
      
            <variablelist>
                <varlistentry>
                    <term><parameter>mount</parameter>&nbsp;:</term>
                    <listitem><simpara>the mount</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>user_param1</parameter>&nbsp;:</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>&nbsp;:</term>
                    <listitem><simpara>additional user parameters (if any)</simpara></listitem>
                </varlistentry>
            </variablelist>
      
            <para>
                This signal is emitted when the
                <link linkend="class-giomount"><classname>gio.Mount</classname></link>
                have been unmounted.
            </para>
        </refsect2>
  
  </refsect1>
</refentry>