Add gio.Drive in docs.

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

	* docs/Makefile.am:
	* docs/reference/pygio-classes.xml:
	* docs/reference/pygio-drive.xml:
	Add gio.Drive in docs.


svn path=/trunk/; revision=1036

4 files changed, 557 insertions, 0 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index adb7672..12ed4d4 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -20,6 +20,7 @@ HTML_FILES =					\
 	html/class-gioappinfo.html		\
 	html/class-gioasyncresult.html		\
 	html/class-giocancellable.html		\
+	html/class-giodrive.html		\
 	html/class-gioemblem.html		\
 	html/class-gioemblemedicon.html		\
 	html/class-giofileattributeinfo.html	\
@@ -57,6 +58,8 @@ XML_FILES = 					\
 	reference/pygio-applaunchcontext.xml 	\
 	reference/pygio-appinfo.xml 		\
 	reference/pygio-asyncresult.xml 	\
+	reference/pygio-cancellable.xml 	\
+	reference/pygio-drive.xml 		\
 	reference/pygio-emblem.xml		\
 	reference/pygio-emblemedicon.xml	\
 	reference/pygio-icon.xml		\
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 7ad8485..46be0e7 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2009-03-28  Gian Mario Tagliaretti  <gianmt@gnome.org>
+
+	* docs/Makefile.am:
+	* docs/reference/pygio-classes.xml:
+	* docs/reference/pygio-drive.xml:
+	Add gio.Drive in docs.
+
 2009-03-25  Gian Mario Tagliaretti  <gianmt@gnome.org>
 
 	* docs/Makefile.am:
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index e49d65f..90dc71b 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -11,6 +11,7 @@
 <xi:include href="pygio-applaunchcontext.xml"/>
 <xi:include href="pygio-asyncresult.xml"/>
 <xi:include href="pygio-cancellable.xml"/>
+<xi:include href="pygio-drive.xml"/>
 <xi:include href="pygio-emblem.xml"/>
 <xi:include href="pygio-emblemedicon.xml"/>
 <xi:include href="pygio-fileattributeinfo.xml"/>
diff --git a/docs/reference/pygio-drive.xml b/docs/reference/pygio-drive.xml
new file mode 100644
index 0000000..73766cd
--- /dev/null
+++ b/docs/reference/pygio-drive.xml
@@ -0,0 +1,546 @@
+<?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-giodrive">
+    <refnamediv>
+        <refname>gio.Drive</refname>
+        <refpurpose>Virtual File System drive management.</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.Drive</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>
+
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--can-eject">can_eject</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--can-poll-for-media">can_poll_for_media</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--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-giodrive--eject-finish">eject_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--enumerate-identifiers">enumerate_identifiers</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--get-icon">get_icon</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--get-identifier">get_identifier</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--get-name">get_name</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--get-volumes">get_volumes</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--has-media">has_media</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--has-volumes">has_volumes</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--is-media-check-automatic">is_media_check_automatic</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--is-media-removable">is_media_removable</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giodrive--poll-for-media">poll_for_media</link></methodname>
+        <methodparam><parameter role="keyword">callback</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-giodrive--poll-for-media-finish">poll_for_media_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
+  +-- <link linkend="class-giodrive">gio.Drive</link>
+</synopsis>
+
+    </refsect1>
+    
+    <refsect1>
+	<title>Prerequisites</title>
+        <para>
+            <link linkend="class-giodrive"><classname>gio.Drive</classname></link> requires
+            <link linkend="class-gobject"><classname>gobject.GObject</classname></link>
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+            - this represent a piece of hardware connected to the machine. Its generally
+            only created for removable hardware or hardware with removable media. 
+        </para>
+        <para>
+            <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+            is a container class for GVolume objects that stem from the same piece of media.
+            As such, <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+            abstracts a drive with (or without) removable media and provides operations for
+            querying whether media is available, determing whether media change is automatically
+            detected and ejecting the media. 
+        </para>
+        <para>
+            If the <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+            reports that media isn't automatically detected, one can poll for media; typically
+            one should not do this periodically as a poll for media operation is potententially
+            expensive and may spin up the drive creating noise. 
+        </para>
+        <para>
+            For porting from GnomeVFS note that there is no equivalent of
+            <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
+            in that API.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+        
+        <refsect2 id="method-giodrive--can-eject">
+            <title>gio.Drive.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 drive can be ejected,
+                    <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>can_eject</methodname>() method checks if a drive can be ejected.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giodrive--can-poll-for-media">
+            <title>gio.Drive.can_poll_for_media</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>can_poll_for_media</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if the drive can be polled
+                    for media changes, <literal>False</literal> otherwise. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>can_poll_for_media</methodname>() method checks if a drive
+                can be polled for media changes.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--eject">
+            <title>gio.Drive.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 drive. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-giodrive--eject-finish">gio.Drive.eject_finish</link></methodname>()
+                to obtain the result of the operation.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--eject-finish">
+            <title>gio.Drive.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 drive has been ejected
+                    successfully, <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>eject_finish</methodname>() method finishes ejecting a drive.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--enumerate-identifiers">
+            <title>gio.Drive.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 drive has. Use
+                <methodname><link linkend="method-giodrive--get-identifier">gio.Drive.get_identifier</link></methodname>()
+                to obtain the identifiers themselves.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giodrive--get-icon">
+            <title>gio.Drive.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 drive.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_icon</methodname>() method gets the icon for drive.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giodrive--get-identifier">
+            <title>gio.Drive.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-giodrive"><classname>gio.Drive</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 drive.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giodrive--get-name">
+            <title>gio.Drive.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 drive's name.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_name</methodname>() method gets the name of drive.
+            </para>
+        </refsect2>
+        
+        <refsect2 id="method-giodrive--get-volumes">
+            <title>gio.Drive.get_volumes</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_volumes</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>A list containing any
+                    <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+                    objects on the given drive. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_volumes</methodname>() method get a list of mountable
+                volumes for drive. 
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--has-media">
+            <title>gio.Drive.has_media</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>has_media</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if drive has media,
+                    <literal>False</literal> otherwise.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>has_media</methodname>() method checks if the drive
+                has media. Note that the OS may not be polling the drive for media changes; see
+                <methodname><link linkend="method-giodrive--is-media-check-automatic">gio.Drive.is_media_check_automatic</link></methodname>()
+                for more details.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--has-volumes">
+            <title>gio.Drive.has_volumes</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>has_volumes</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if drive contains volumes,
+                    <literal>False</literal> otherwise.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>has_volumes</methodname>() method check if drive has any mountable volumes.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--is-media-check-automatic">
+            <title>gio.Drive.is_media_check_automatic</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>is_media_check_automatic</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if drive is capabable
+                    of automatically detecting media changes,
+                    <literal>False</literal> otherwise.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>is_media_check_automatic</methodname>() method checks if
+                drive is capabable of automatically detecting media changes.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--is-media-removable">
+            <title>gio.Drive.is_media_removable</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>is_media_removable</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if drive supports removable media,
+                    <literal>False</literal> otherwise.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>is_media_removable</methodname>() method checks if the
+                drive supports removable media.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--poll-for-media">
+            <title>gio.Drive.poll_for_media</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>poll_for_media</methodname>
+                <methodparam>
+                    <parameter role="keyword">callback</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">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>poll_for_media</methodname>() method asynchronously polls
+                drive to see if media has been inserted or removed. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-giodrive--poll-for-media-finish">gio.Drive.poll_for_media_finish</link></methodname>()
+                to obtain the result of the operation.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giodrive--poll-for-media-finish">
+            <title>gio.Drive.poll_for_media_finish</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>poll_for_media_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 drive has been poll_for_mediaed
+                    successfully, <literal>False</literal> otherwise.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>poll_for_media_finish</methodname>() method finishes
+                an operation started with
+                <methodname><link linkend="method-giodrive--poll-for-media">gio.Drive.poll_for_media</link></methodname>()
+                on a drive.
+            </para>
+        </refsect2>
+    </refsect1>
+</refentry>