Add gio.Volume in docs.

2009-03-29  Gian Mario Tagliaretti  <gianmt@gnome.org>

	* docs/Makefile.am:
	* docs/reference/pygio-classes.xml:
	* docs/reference/pygio-constants.xml:
	* docs/reference/pygio-volume.xml: Add gio.Volume in docs.


svn path=/trunk/; revision=1041

5 files changed, 771 insertions, 1 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 12ed4d4..9be2fa5 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -28,6 +28,7 @@ HTML_FILES =					\
 	html/class-giofileicon.html		\
 	html/class-gioicon.html			\
 	html/class-giosimpleasyncresult.html	\
+	html/class-giovolume.html		\
 	html/gio-constants.html			\
 	html/gio-class-reference.html		\
 	html/gobject-constants.html		\
@@ -66,7 +67,8 @@ XML_FILES = 					\
 	reference/pygio-fileattributeinfo.xml	\
 	reference/pygio-fileenumerator.xml	\
 	reference/pygio-fileicon.xml 		\
-	reference/pygio-simpleasyncresult.xml
+	reference/pygio-simpleasyncresult.xml	\
+	reference/pygio-volume.xml
 
 XSL_FILES =			\
 	xsl/common.xsl 		\
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 46be0e7..8fe9c3f 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2009-03-29  Gian Mario Tagliaretti  <gianmt@gnome.org>
+
+	* docs/Makefile.am:
+	* docs/reference/pygio-classes.xml:
+	* docs/reference/pygio-constants.xml:
+	* docs/reference/pygio-volume.xml: Add gio.Volume in docs.
+
 2009-03-28  Gian Mario Tagliaretti  <gianmt@gnome.org>
 
 	* docs/Makefile.am:
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index 90dc71b..8ceb70e 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -19,6 +19,7 @@
 <xi:include href="pygio-fileicon.xml"/>
 <xi:include href="pygio-icon.xml"/>
 <xi:include href="pygio-simpleasyncresult.xml"/>
+<xi:include href="pygio-volume.xml"/>
 <xi:include href="pygio-constants.xml"/>
 
 </chapter>
diff --git a/docs/reference/pygio-constants.xml b/docs/reference/pygio-constants.xml
index d167de8..b2bcbf2 100644
--- a/docs/reference/pygio-constants.xml
+++ b/docs/reference/pygio-constants.xml
@@ -17,6 +17,8 @@
 <xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref>
 <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
 <xref linkend="gio-file-attribute-flags-constants" endterm="gio-file-attribute-flags-constants-title"></xref>
+<xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref>
+<xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>
 </programlisting>
 
   </refsect1>
@@ -388,6 +390,46 @@
 	</varlistentry>
       </variablelist>
     </refsect2>
+
+    <refsect2 id="gio-mount-mount-flags-constants">
+      <title id="gio-mount-mount-flags-constants-title">Gio Mount Mount Flags Constants</title>
+
+      <para>
+	  Flags used when mounting a mount.
+      </para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>gio.MOUNT_MOUNT_NONE</literal></term>
+	  <listitem>
+	    <simpara>No flags set.</simpara>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2 id="gio-mount-unmount-flags-constants">
+      <title id="gio-mount-unmount-flags-constants-title">Gio Mount Unmount Flags Constants</title>
+
+      <para>
+	  Flags used when unmounting a mount.
+      </para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>gio.MOUNT_UNMOUNT_NONE</literal></term>
+	  <listitem>
+	    <simpara>No flags set.</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>gio.MOUNT_UNMOUNT_FORCE</literal></term>
+	  <listitem>
+	    <simpara>Unmount even if there are outstanding file operations on the mount.</simpara>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
 </refentry>
diff --git a/docs/reference/pygio-volume.xml b/docs/reference/pygio-volume.xml
new file mode 100644
index 0000000..8ff981c
--- /dev/null
+++ b/docs/reference/pygio-volume.xml
@@ -0,0 +1,718 @@
+<?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-giovolume">
+    <refnamediv>
+        <refname>gio.Volume</refname>
+        <refpurpose>Volume management.</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.Volume</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>
+
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--can-eject">can_eject</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--can-mount">can_mount</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--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-giovolume--eject-finish">eject_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--enumerate-identifiers">enumerate_identifiers</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-activation-root">get_activation_root</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-drive">get_drive</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-icon">get_icon</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-identifier">get_identifier</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-name">get_name</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--get-uuid">get_uuid</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--mount">mount</link></methodname>
+        <methodparam><parameter role="keyword">mount_operation</parameter></methodparam>
+        <methodparam><parameter role="keyword">callback</parameter></methodparam>
+        <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_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-giovolume--mount-finish">mount_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giovolume--should-automount">should_automount</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
+  +-- <link linkend="class-giovolume">gio.Volume</link>
+</synopsis>
+
+    </refsect1>
+    
+    <refsect1>
+        <title>Prerequisites</title>
+        <para>
+            <link linkend="class-giovolume"><classname>gio.Volume</classname></link> requires
+            <link linkend="class-gobject"><classname>gobject.GObject</classname></link>
+        </para>
+    </refsect1>
+
+    <refsect1 id="signal-prototypes-giovolume">
+        <title>gio.Volume Signal Prototypes</title>
+  
+        <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
+  
+        <variablelist>
+            <varlistentry>
+                <term><link linkend="signal-giovolume--changed">"changed"</link></term>
+                <listitem>
+                    <methodsynopsis language="python"><methodname>callback</methodname>
+                        <methodparam><parameter>volume</parameter></methodparam>
+                        <methodparam><parameter>user_param1</parameter></methodparam>
+                        <methodparam><parameter>...</parameter></methodparam>
+                    </methodsynopsis>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><link linkend="signal-giovolume--changed">"removed"</link></term>
+                <listitem>
+                    <methodsynopsis language="python"><methodname>callback</methodname>
+                        <methodparam><parameter>volume</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-giovolume"><classname>gio.Volume</classname></link>
+            interface represents user-visible objects that can be mounted. Note, when porting
+            from GnomeVFS, <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+            is the moral equivalent of GnomeVFSDrive. 
+        </para>
+        <para>
+            Mounting a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+            instance is an asynchronous operation. For more information about asynchronous operations.
+            To mount a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>, first call
+            <methodname><link linkend="method-giovolume--mount">gio.Volume.mount</link></methodname>()
+            with (at least) the <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+            instance, optionally a
+            <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
+            object and a GAsyncReadyCallback. 
+        </para>
+        <para>
+            Typically, one will only want to pass <literal>None</literal> for the GMountOperation
+            if automounting all volumes when a desktop session starts since it's not desirable
+            to put up a lot of dialogs asking for credentials. 
+        </para>
+        <para>
+            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
+            <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
+            with the GVolume instance and the GAsyncReady data to see if the operation was completed
+            successfully. If an error is present when
+            <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
+            is called, then it will be filled with any error information. 
+        </para>
+        <para>
+            It is sometimes necessary to directly access the underlying operating system object behind a volume
+            (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain
+            an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs,
+            filesystem labels, traditional Unix devices (e.g. /dev/sda2), uuids. GIO uses predefind strings
+            as names for the different kinds of identifiers:
+            "hal-udi", "label", etc. Use
+            <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>()
+            to obtain an identifier for a volume. 
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+        
+        <refsect2 id="method-giovolume--can-eject">
+            <title>gio.Volume.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 volume can be ejected,
+                    <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>can_eject</methodname>() method checks if a volume can be ejected.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--can-mount">
+            <title>gio.Volume.can_mount</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>can_mount</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if the volume can be mounted
+                    for media changes, <literal>False</literal> otherwise. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>can_mount</methodname>() method checks if a volume
+                can be mounted.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giovolume--eject">
+            <title>gio.Volume.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.
+                  </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 volume. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-giovolume--eject-finish">gio.Volume.eject_finish</link></methodname>()
+                to obtain the result of the operation.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giovolume--eject-finish">
+            <title>gio.Volume.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 volume has been ejected
+                    successfully, <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>eject_finish</methodname>() method finishes ejecting a volume.
+                If any errors occured during the operation, error will be set to contain the
+                errors and <literal>False</literal> will be returned.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giovolume--enumerate-identifiers">
+            <title>gio.Volume.enumerate_identifiers</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>enumerate_identifiers</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>a list of strings containing kinds of identifiers.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>enumerate_identifiers</methodname>() method gets the kinds
+                of identifiers that volume has. Use
+                <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>()
+                to obtain the identifiers themselves.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-activation-root">
+            <title>gio.Volume.get_activation_root</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_activation_root</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>the activation root of volume or <literal>None</literal>.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_activation_root</methodname>() method gets the activation
+                root for a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+                if it is known ahead of mount time. Returns <literal>None</literal> otherwise.
+                If not <literal>None</literal> and if volume is mounted, then the result of
+                <methodname><link linkend="method-giomount--get-root">gio.Mount.get_root</link></methodname>()
+                on the GMount object obtained from
+                <methodname><link linkend="method-giovolume--get-mount">gio.Volume.get_mount</link></methodname>()
+                will always either be equal or a prefix of what this function returns.
+                In other words, in code:
+            </para>
+<programlisting>
+mount = volume.get_mount() # mounted, so never None
+mount_root = mount.get_root()
+volume_activation_root = volume.get_activation_root() # assume not None
+</programlisting>
+            <para>
+                then the expression
+            </para>
+<programlisting>
+volume_activation_root.has_prefix(mount_root) || volume_activation_root.equal(mount_root)
+</programlisting>
+            <para>
+                will always be <literal>True</literal>.
+            </para>
+            <para>
+                Activation roots are typically used in
+                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
+                implementations to find the underlying mount to shadow, see
+                <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
+                for more details.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-drive">
+            <title>gio.Volume.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>A <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+                    or <literal>None</literal> if volume is not associated with a drive.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_drive</methodname>() method gets the drive for the volume.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-icon">
+            <title>gio.Volume.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 volume.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_icon</methodname>() method gets the icon for volume.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-identifier">
+            <title>gio.Volume.get_identifier</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_identifier</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>A string containing the requested identfier, or
+                    <literal>None</literal> if the
+                    <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+                    doesn't have this kind of identifier. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_identifier</methodname>() method gets the identifier of
+                the given kind for volume.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-mount">
+            <title>gio.Volume.get_mount</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_mount</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>A 
+                    <link linkend="class-giomount"><classname>gio.Mount</classname></link>
+                    or <literal>None</literal> if volume isn't mounted.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_mount</methodname>() method gets the mount for the volume.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-name">
+            <title>gio.Volume.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>A string containing volume's name.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_name</methodname>() method gets the name of volume.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--get-uuid">
+            <title>gio.Volume.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 volume 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 volume.
+                The reference is typically based on the file system UUID for the volume in
+                question and should be considered an opaque string.
+                Returns <literal>None</literal> if there is no UUID available.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giovolume--mount">
+            <title>gio.Volume.mount</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>mount</methodname>
+                <methodparam>
+                    <parameter role="keyword">mount_operation</parameter>
+                </methodparam>
+                <methodparam>
+                    <parameter role="keyword">callback</parameter>
+                </methodparam>
+                <methodparam>
+                    <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_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">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">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 operation 
+                  </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>mount</methodname>() method mounts a volume. This is an
+                asynchronous operation, and is finished by calling
+                <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
+                with the volume and GAsyncResult returned in the callback.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giovolume--mount-finish">
+            <title>gio.Volume.mount_finish</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>mount_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 volume has been mounted
+                    successfully, <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>mounted</methodname>() method finishes mounting a volume.
+                If any errors occured during the operation, error will be set to contain
+                the errors and <literal>False</literal> will be returned. 
+            </para>
+            <para>
+                If the mount operation succeeded,
+                <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname>()
+                on volume is guaranteed to return the mount right after calling this function;
+                there's no need to listen for the 'mount-added' signal on
+                <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giovolume--should-automount">
+            <title>gio.Volume.should_automount</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>should_automount</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if the volume should
+                    be automatically mounted. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>should_automount</methodname>() method returns whether
+                the volume should be automatically mounted.
+            </para>
+        </refsect2>
+    </refsect1>
+
+    <refsect1>
+        <title>Signals</title>
+    
+        <refsect2 id="signal-giovolume--changed">
+            <title>The "changed" gio.Volume Signal</title>
+      
+            <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
+                <methodparam><parameter>volume</parameter></methodparam>
+                <methodparam><parameter>user_param1</parameter></methodparam>
+                <methodparam><parameter>...</parameter></methodparam>
+            </methodsynopsis></programlisting>
+      
+            <variablelist>
+                <varlistentry>
+                    <term><parameter>volume</parameter>&nbsp;:</term>
+                    <listitem><simpara>the volume</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 volume has been changed.
+            </para>
+        </refsect2>
+    
+        <refsect2 id="signal-giovolume--removed">
+            <title>The "removed" gio.Volume Signal</title>
+      
+            <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
+                <methodparam><parameter>volume</parameter></methodparam>
+                <methodparam><parameter>user_param1</parameter></methodparam>
+                <methodparam><parameter>...</parameter></methodparam>
+            </methodsynopsis></programlisting>
+      
+            <variablelist>
+                <varlistentry>
+                    <term><parameter>volume</parameter>&nbsp;:</term>
+                    <listitem><simpara>the volume</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-giovolume"><classname>gio.Volume</classname></link>
+                have been removed. If the recipient is holding references to the object
+                they should release them so the object can be finalized.
+            </para>
+        </refsect2>
+  
+  </refsect1>
+</refentry>