docs/reference/pygio-volume.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <refentry id="class-giovolume">
   6     <refnamediv>
   7         <refname>gio.Volume</refname>
   8         <refpurpose>Volume management.</refpurpose>
   9     </refnamediv>
  10
  11     <refsect1>
  12         <title>Synopsis</title>
  13
  14     <classsynopsis language="python">
  15         <ooclass><classname>gio.Volume</classname></ooclass>
  16         <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>
  17
  18     <methodsynopsis language="python">
  19         <methodname><link linkend="method-giovolume--can-eject">can_eject</link></methodname>
  20         <methodparam></methodparam>
  21     </methodsynopsis>
  22     <methodsynopsis language="python">
  23         <methodname><link linkend="method-giovolume--can-mount">can_mount</link></methodname>
  24         <methodparam></methodparam>
  25     </methodsynopsis>
  26     <methodsynopsis language="python">
  27         <methodname><link linkend="method-giovolume--eject">eject</link></methodname>
  28         <methodparam><parameter role="keyword">callback</parameter></methodparam>
  29         <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
  30         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  31         <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
  32     </methodsynopsis>
  33     <methodsynopsis language="python">
  34         <methodname><link linkend="method-giovolume--eject-finish">eject_finish</link></methodname>
  35         <methodparam><parameter role="keyword">result</parameter></methodparam>
  36     </methodsynopsis>
  37     <methodsynopsis language="python">
  38         <methodname><link linkend="method-giovolume--enumerate-identifiers">enumerate_identifiers</link></methodname>
  39         <methodparam></methodparam>
  40     </methodsynopsis>
  41     <methodsynopsis language="python">
  42         <methodname><link linkend="method-giovolume--get-activation-root">get_activation_root</link></methodname>
  43         <methodparam></methodparam>
  44     </methodsynopsis>
  45     <methodsynopsis language="python">
  46         <methodname><link linkend="method-giovolume--get-drive">get_drive</link></methodname>
  47         <methodparam></methodparam>
  48     </methodsynopsis>
  49     <methodsynopsis language="python">
  50         <methodname><link linkend="method-giovolume--get-icon">get_icon</link></methodname>
  51         <methodparam></methodparam>
  52     </methodsynopsis>
  53     <methodsynopsis language="python">
  54         <methodname><link linkend="method-giovolume--get-identifier">get_identifier</link></methodname>
  55         <methodparam></methodparam>
  56     </methodsynopsis>
  57     <methodsynopsis language="python">
  58         <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname>
  59         <methodparam></methodparam>
  60     </methodsynopsis>
  61     <methodsynopsis language="python">
  62         <methodname><link linkend="method-giovolume--get-name">get_name</link></methodname>
  63         <methodparam></methodparam>
  64     </methodsynopsis>
  65     <methodsynopsis language="python">
  66         <methodname><link linkend="method-giovolume--get-uuid">get_uuid</link></methodname>
  67         <methodparam></methodparam>
  68     </methodsynopsis>
  69     <methodsynopsis language="python">
  70         <methodname><link linkend="method-giovolume--mount">mount</link></methodname>
  71         <methodparam><parameter role="keyword">mount_operation</parameter></methodparam>
  72         <methodparam><parameter role="keyword">callback</parameter></methodparam>
  73         <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_NONE</literal></initializer></methodparam>
  74         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  75         <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
  76     </methodsynopsis>
  77     <methodsynopsis language="python">
  78         <methodname><link linkend="method-giovolume--mount-finish">mount_finish</link></methodname>
  79         <methodparam><parameter role="keyword">result</parameter></methodparam>
  80     </methodsynopsis>
  81     <methodsynopsis language="python">
  82         <methodname><link linkend="method-giovolume--should-automount">should_automount</link></methodname>
  83         <methodparam></methodparam>
  84     </methodsynopsis>
  85
  86     </classsynopsis>
  87
  88     </refsect1>
  89
  90     <refsect1>
  91         <title>Ancestry</title>
  92
  93 <synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
  94   +-- <link linkend="class-giovolume">gio.Volume</link>
  95 </synopsis>
  96
  97     </refsect1>
  98
  99     <refsect1>
 100         <title>Prerequisites</title>
 101         <para>
 102             <link linkend="class-giovolume"><classname>gio.Volume</classname></link> requires
 103             <link linkend="class-gobject"><classname>gobject.GObject</classname></link>
 104         </para>
 105     </refsect1>
 106
 107     <refsect1 id="signal-prototypes-giovolume">
 108         <title>gio.Volume Signal Prototypes</title>
 109
 110         <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
 111
 112         <variablelist>
 113             <varlistentry>
 114                 <term><link linkend="signal-giovolume--changed">"changed"</link></term>
 115                 <listitem>
 116                     <methodsynopsis language="python"><methodname>callback</methodname>
 117                         <methodparam><parameter>volume</parameter></methodparam>
 118                         <methodparam><parameter>user_param1</parameter></methodparam>
 119                         <methodparam><parameter>...</parameter></methodparam>
 120                     </methodsynopsis>
 121                 </listitem>
 122             </varlistentry>
 123             <varlistentry>
 124                 <term><link linkend="signal-giovolume--removed">"removed"</link></term>
 125                 <listitem>
 126                     <methodsynopsis language="python"><methodname>callback</methodname>
 127                         <methodparam><parameter>volume</parameter></methodparam>
 128                         <methodparam><parameter>user_param1</parameter></methodparam>
 129                         <methodparam><parameter>...</parameter></methodparam>
 130                     </methodsynopsis>
 131                 </listitem>
 132             </varlistentry>
 133         </variablelist>
 134
 135     </refsect1>
 136
 137     <refsect1>
 138         <title>Description</title>
 139
 140         <para>
 141             The <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 142             interface represents user-visible objects that can be mounted. Note, when porting
 143             from GnomeVFS, <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 144             is the moral equivalent of GnomeVFSDrive.
 145         </para>
 146         <para>
 147             Mounting a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 148             instance is an asynchronous operation. For more information about asynchronous operations.
 149             To mount a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>, first call
 150             <methodname><link linkend="method-giovolume--mount">gio.Volume.mount</link></methodname>()
 151             with (at least) the <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 152             instance, optionally a
 153             <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
 154             object and a GAsyncReadyCallback.
 155         </para>
 156         <para>
 157             Typically, one will only want to pass <literal>None</literal> for the GMountOperation
 158             if automounting all volumes when a desktop session starts since it's not desirable
 159             to put up a lot of dialogs asking for credentials.
 160         </para>
 161         <para>
 162             The callback will be fired when the operation has resolved (either with success or failure),
 163             and a GAsyncReady structure will be passed to the callback. That callback should then call
 164             <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
 165             with the GVolume instance and the GAsyncReady data to see if the operation was completed
 166             successfully. If an error is present when
 167             <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
 168             is called, then it will be filled with any error information.
 169         </para>
 170         <para>
 171             It is sometimes necessary to directly access the underlying operating system object behind a volume
 172             (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain
 173             an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs,
 174             filesystem labels, traditional Unix devices (e.g. /dev/sda2), uuids. GIO uses predefind strings
 175             as names for the different kinds of identifiers:
 176             "hal-udi", "label", etc. Use
 177             <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>()
 178             to obtain an identifier for a volume.
 179         </para>
 180     </refsect1>
 181
 182     <refsect1>
 183         <title>Methods</title>
 184
 185         <refsect2 id="method-giovolume--can-eject">
 186             <title>gio.Volume.can_eject</title>
 187
 188             <programlisting><methodsynopsis language="python">
 189                 <methodname>can_eject</methodname>
 190                 <methodparam></methodparam>
 191             </methodsynopsis></programlisting>
 192
 193             <variablelist>
 194                 <varlistentry>
 195                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 196                     <listitem><simpara><literal>True</literal> if the volume can be ejected,
 197                     <literal>False</literal> otherwise.
 198                     </simpara></listitem>
 199                 </varlistentry>
 200             </variablelist>
 201
 202             <para>
 203                 The <methodname>can_eject</methodname>() method checks if a volume can be ejected.
 204             </para>
 205         </refsect2>
 206
 207         <refsect2 id="method-giovolume--can-mount">
 208             <title>gio.Volume.can_mount</title>
 209
 210             <programlisting><methodsynopsis language="python">
 211                 <methodname>can_mount</methodname>
 212                 <methodparam></methodparam>
 213             </methodsynopsis></programlisting>
 214
 215             <variablelist>
 216                 <varlistentry>
 217                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 218                     <listitem><simpara><literal>True</literal> if the volume can be mounted
 219                     for media changes, <literal>False</literal> otherwise.
 220                     </simpara></listitem>
 221                 </varlistentry>
 222             </variablelist>
 223
 224             <para>
 225                 The <methodname>can_mount</methodname>() method checks if a volume
 226                 can be mounted.
 227             </para>
 228         </refsect2>
 229
 230         <refsect2 id="method-giovolume--eject">
 231             <title>gio.Volume.eject</title>
 232
 233             <programlisting><methodsynopsis language="python">
 234                 <methodname>eject</methodname>
 235                 <methodparam>
 236                     <parameter role="keyword">callback</parameter>
 237                 </methodparam>
 238                 <methodparam>
 239                     <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer>
 240                 </methodparam>
 241                 <methodparam>
 242                     <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
 243                 </methodparam>
 244                 <methodparam>
 245                     <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer>
 246                 </methodparam>
 247             </methodsynopsis></programlisting>
 248
 249             <variablelist>
 250                 <varlistentry>
 251                   <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
 252                   <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
 253                   </simpara></listitem>
 254                 </varlistentry>
 255                 <varlistentry>
 256                   <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
 257                   <listitem><simpara>flags affecting the unmount if required for eject.
 258                   </simpara></listitem>
 259                 </varlistentry>
 260                 <varlistentry>
 261                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 262                   <listitem><simpara>Optional
 263                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 264                   object, <literal>None</literal> to ignore.
 265                   </simpara></listitem>
 266                 </varlistentry>
 267                 <varlistentry>
 268                   <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
 269                   <listitem><simpara>The data to pass to callback function.
 270                   </simpara></listitem>
 271                 </varlistentry>
 272             </variablelist>
 273
 274             <para>
 275                 The <methodname>eject</methodname>() method asynchronously ejects a volume.
 276             </para>
 277             <para>
 278                 When the operation is finished, callback will be called. You can then call
 279                 <methodname><link linkend="method-giovolume--eject-finish">gio.Volume.eject_finish</link></methodname>()
 280                 to obtain the result of the operation.
 281             </para>
 282         </refsect2>
 283
 284         <refsect2 id="method-giovolume--eject-finish">
 285             <title>gio.Volume.eject_finish</title>
 286
 287             <programlisting><methodsynopsis language="python">
 288                 <methodname>eject_finish</methodname>
 289                 <methodparam><parameter role="keyword">result</parameter></methodparam>
 290             </methodsynopsis></programlisting>
 291
 292             <variablelist>
 293                 <varlistentry>
 294                   <term><parameter role="keyword">result</parameter>&nbsp;:</term>
 295                   <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
 296                   </simpara></listitem>
 297                 </varlistentry>
 298                 <varlistentry>
 299                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 300                     <listitem><simpara><literal>True</literal> if the volume has been ejected
 301                     successfully, <literal>False</literal> otherwise.
 302                     </simpara></listitem>
 303                 </varlistentry>
 304             </variablelist>
 305
 306             <para>
 307                 The <methodname>eject_finish</methodname>() method finishes ejecting a volume.
 308                 If any errors occured during the operation, error will be set to contain the
 309                 errors and <literal>False</literal> will be returned.
 310             </para>
 311         </refsect2>
 312
 313         <refsect2 id="method-giovolume--enumerate-identifiers">
 314             <title>gio.Volume.enumerate_identifiers</title>
 315
 316             <programlisting><methodsynopsis language="python">
 317                 <methodname>enumerate_identifiers</methodname>
 318                 <methodparam></methodparam>
 319             </methodsynopsis></programlisting>
 320
 321             <variablelist>
 322                 <varlistentry>
 323                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 324                     <listitem><simpara>a list of strings containing kinds of identifiers.
 325                     </simpara></listitem>
 326                 </varlistentry>
 327             </variablelist>
 328
 329             <para>
 330                 The <methodname>enumerate_identifiers</methodname>() method gets the kinds
 331                 of identifiers that volume has. Use
 332                 <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>()
 333                 to obtain the identifiers themselves.
 334             </para>
 335         </refsect2>
 336
 337         <refsect2 id="method-giovolume--get-activation-root">
 338             <title>gio.Volume.get_activation_root</title>
 339
 340             <programlisting><methodsynopsis language="python">
 341                 <methodname>get_activation_root</methodname>
 342                 <methodparam></methodparam>
 343             </methodsynopsis></programlisting>
 344
 345             <variablelist>
 346                 <varlistentry>
 347                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 348                     <listitem><simpara>the activation root of volume or <literal>None</literal>.
 349                     </simpara></listitem>
 350                 </varlistentry>
 351             </variablelist>
 352
 353             <para>
 354                 The <methodname>get_activation_root</methodname>() method gets the activation
 355                 root for a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 356                 if it is known ahead of mount time. Returns <literal>None</literal> otherwise.
 357                 If not <literal>None</literal> and if volume is mounted, then the result of
 358                 <methodname><link linkend="method-giomount--get-root">gio.Mount.get_root</link></methodname>()
 359                 on the GMount object obtained from
 360                 <methodname><link linkend="method-giovolume--get-mount">gio.Volume.get_mount</link></methodname>()
 361                 will always either be equal or a prefix of what this function returns.
 362                 In other words, in code:
 363             </para>
 364 <programlisting>
 365 mount = volume.get_mount() # mounted, so never None
 366 mount_root = mount.get_root()
 367 volume_activation_root = volume.get_activation_root() # assume not None
 368 </programlisting>
 369             <para>
 370                 then the expression
 371             </para>
 372 <programlisting>
 373 volume_activation_root.has_prefix(mount_root) || volume_activation_root.equal(mount_root)
 374 </programlisting>
 375             <para>
 376                 will always be <literal>True</literal>.
 377             </para>
 378             <para>
 379                 Activation roots are typically used in
 380                 <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
 381                 implementations to find the underlying mount to shadow, see
 382                 <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
 383                 for more details.
 384             </para>
 385         </refsect2>
 386
 387         <refsect2 id="method-giovolume--get-drive">
 388             <title>gio.Volume.get_drive</title>
 389
 390             <programlisting><methodsynopsis language="python">
 391                 <methodname>get_drive</methodname>
 392                 <methodparam></methodparam>
 393             </methodsynopsis></programlisting>
 394
 395             <variablelist>
 396                 <varlistentry>
 397                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 398                     <listitem><simpara>A <link linkend="class-giodrive"><classname>gio.Drive</classname></link>
 399                     or <literal>None</literal> if volume is not associated with a drive.
 400                     </simpara></listitem>
 401                 </varlistentry>
 402             </variablelist>
 403
 404             <para>
 405                 The <methodname>get_drive</methodname>() method gets the drive for the volume.
 406             </para>
 407         </refsect2>
 408
 409         <refsect2 id="method-giovolume--get-icon">
 410             <title>gio.Volume.get_icon</title>
 411
 412             <programlisting><methodsynopsis language="python">
 413                 <methodname>get_icon</methodname>
 414                 <methodparam></methodparam>
 415             </methodsynopsis></programlisting>
 416
 417             <variablelist>
 418                 <varlistentry>
 419                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 420                     <listitem><simpara><link linkend="class-gioicon"><classname>gio.Icon</classname></link>
 421                     for the volume.
 422                     </simpara></listitem>
 423                 </varlistentry>
 424             </variablelist>
 425
 426             <para>
 427                 The <methodname>get_icon</methodname>() method gets the icon for volume.
 428             </para>
 429         </refsect2>
 430
 431         <refsect2 id="method-giovolume--get-identifier">
 432             <title>gio.Volume.get_identifier</title>
 433
 434             <programlisting><methodsynopsis language="python">
 435                 <methodname>get_identifier</methodname>
 436                 <methodparam></methodparam>
 437             </methodsynopsis></programlisting>
 438
 439             <variablelist>
 440                 <varlistentry>
 441                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 442                     <listitem><simpara>A string containing the requested identfier, or
 443                     <literal>None</literal> if the
 444                     <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 445                     doesn't have this kind of identifier.
 446                     </simpara></listitem>
 447                 </varlistentry>
 448             </variablelist>
 449
 450             <para>
 451                 The <methodname>get_identifier</methodname>() method gets the identifier of
 452                 the given kind for volume.
 453             </para>
 454         </refsect2>
 455
 456         <refsect2 id="method-giovolume--get-mount">
 457             <title>gio.Volume.get_mount</title>
 458
 459             <programlisting><methodsynopsis language="python">
 460                 <methodname>get_mount</methodname>
 461                 <methodparam></methodparam>
 462             </methodsynopsis></programlisting>
 463
 464             <variablelist>
 465                 <varlistentry>
 466                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 467                     <listitem><simpara>A
 468                     <link linkend="class-giomount"><classname>gio.Mount</classname></link>
 469                     or <literal>None</literal> if volume isn't mounted.
 470                     </simpara></listitem>
 471                 </varlistentry>
 472             </variablelist>
 473
 474             <para>
 475                 The <methodname>get_mount</methodname>() method gets the mount for the volume.
 476             </para>
 477         </refsect2>
 478
 479         <refsect2 id="method-giovolume--get-name">
 480             <title>gio.Volume.get_name</title>
 481
 482             <programlisting><methodsynopsis language="python">
 483                 <methodname>get_name</methodname>
 484                 <methodparam></methodparam>
 485             </methodsynopsis></programlisting>
 486
 487             <variablelist>
 488                 <varlistentry>
 489                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 490                     <listitem><simpara>A string containing volume's name.
 491                     </simpara></listitem>
 492                 </varlistentry>
 493             </variablelist>
 494
 495             <para>
 496                 The <methodname>get_name</methodname>() method gets the name of volume.
 497             </para>
 498         </refsect2>
 499
 500         <refsect2 id="method-giovolume--get-uuid">
 501             <title>gio.Volume.get_uuid</title>
 502
 503             <programlisting><methodsynopsis language="python">
 504                 <methodname>get_uuid</methodname>
 505                 <methodparam></methodparam>
 506             </methodsynopsis></programlisting>
 507
 508             <variablelist>
 509                 <varlistentry>
 510                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 511                     <listitem><simpara>the UUID for volume or <literal>None</literal>
 512                     if no UUID can be computed.
 513                     </simpara></listitem>
 514                 </varlistentry>
 515             </variablelist>
 516
 517             <para>
 518                 The <methodname>get_uuid</methodname>() method gets the UUID for the volume.
 519                 The reference is typically based on the file system UUID for the volume in
 520                 question and should be considered an opaque string.
 521                 Returns <literal>None</literal> if there is no UUID available.
 522             </para>
 523         </refsect2>
 524
 525         <refsect2 id="method-giovolume--mount">
 526             <title>gio.Volume.mount</title>
 527
 528             <programlisting><methodsynopsis language="python">
 529                 <methodname>mount</methodname>
 530                 <methodparam>
 531                     <parameter role="keyword">mount_operation</parameter>
 532                 </methodparam>
 533                 <methodparam>
 534                     <parameter role="keyword">callback</parameter>
 535                 </methodparam>
 536                 <methodparam>
 537                     <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_NONE</literal></initializer>
 538                 </methodparam>
 539                 <methodparam>
 540                     <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
 541                 </methodparam>
 542                 <methodparam>
 543                     <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer>
 544                 </methodparam>
 545             </methodsynopsis></programlisting>
 546
 547             <variablelist>
 548                 <varlistentry>
 549                   <term><parameter role="keyword">mount_operation</parameter>&nbsp;:</term>
 550                   <listitem><simpara>A
 551                   <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
 552                   or <literal>None</literal> to avoid user interaction.
 553                   </simpara></listitem>
 554                 </varlistentry>
 555                 <varlistentry>
 556                   <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
 557                   <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
 558                   </simpara></listitem>
 559                 </varlistentry>
 560                 <varlistentry>
 561                   <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
 562                   <listitem><simpara>Flags affecting the operation
 563                   </simpara></listitem>
 564                 </varlistentry>
 565                 <varlistentry>
 566                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 567                   <listitem><simpara>Optional
 568                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 569                   object, <literal>None</literal> to ignore.
 570                   </simpara></listitem>
 571                 </varlistentry>
 572                 <varlistentry>
 573                   <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
 574                   <listitem><simpara>The data to pass to callback function.
 575                   </simpara></listitem>
 576                 </varlistentry>
 577             </variablelist>
 578
 579             <para>
 580                 The <methodname>mount</methodname>() method mounts a volume. This is an
 581                 asynchronous operation, and is finished by calling
 582                 <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>()
 583                 with the volume and GAsyncResult returned in the callback.
 584             </para>
 585         </refsect2>
 586
 587         <refsect2 id="method-giovolume--mount-finish">
 588             <title>gio.Volume.mount_finish</title>
 589
 590             <programlisting><methodsynopsis language="python">
 591                 <methodname>mount_finish</methodname>
 592                 <methodparam><parameter role="keyword">result</parameter></methodparam>
 593             </methodsynopsis></programlisting>
 594
 595             <variablelist>
 596                 <varlistentry>
 597                   <term><parameter role="keyword">result</parameter>&nbsp;:</term>
 598                   <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
 599                   </simpara></listitem>
 600                 </varlistentry>
 601                 <varlistentry>
 602                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 603                     <listitem><simpara><literal>True</literal> if the volume has been mounted
 604                     successfully, <literal>False</literal> otherwise.
 605                     </simpara></listitem>
 606                 </varlistentry>
 607             </variablelist>
 608
 609             <para>
 610                 The <methodname>mounted</methodname>() method finishes mounting a volume.
 611                 If any errors occured during the operation, error will be set to contain
 612                 the errors and <literal>False</literal> will be returned.
 613             </para>
 614             <para>
 615                 If the mount operation succeeded,
 616                 <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname>()
 617                 on volume is guaranteed to return the mount right after calling this function;
 618                 there's no need to listen for the 'mount-added' signal on
 619                 <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>.
 620             </para>
 621         </refsect2>
 622
 623         <refsect2 id="method-giovolume--should-automount">
 624             <title>gio.Volume.should_automount</title>
 625
 626             <programlisting><methodsynopsis language="python">
 627                 <methodname>should_automount</methodname>
 628                 <methodparam></methodparam>
 629             </methodsynopsis></programlisting>
 630
 631             <variablelist>
 632                 <varlistentry>
 633                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 634                     <listitem><simpara><literal>True</literal> if the volume should
 635                     be automatically mounted.
 636                     </simpara></listitem>
 637                 </varlistentry>
 638             </variablelist>
 639
 640             <para>
 641                 The <methodname>should_automount</methodname>() method returns whether
 642                 the volume should be automatically mounted.
 643             </para>
 644         </refsect2>
 645     </refsect1>
 646
 647     <refsect1>
 648         <title>Signals</title>
 649
 650         <refsect2 id="signal-giovolume--changed">
 651             <title>The "changed" gio.Volume Signal</title>
 652
 653             <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
 654                 <methodparam><parameter>volume</parameter></methodparam>
 655                 <methodparam><parameter>user_param1</parameter></methodparam>
 656                 <methodparam><parameter>...</parameter></methodparam>
 657             </methodsynopsis></programlisting>
 658
 659             <variablelist>
 660                 <varlistentry>
 661                     <term><parameter>volume</parameter>&nbsp;:</term>
 662                     <listitem><simpara>the volume</simpara></listitem>
 663                 </varlistentry>
 664                 <varlistentry>
 665                     <term><parameter>user_param1</parameter>&nbsp;:</term>
 666                     <listitem><simpara>the first user parameter (if any) specified
 667                     with the <link
 668                     linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
 669                     method</simpara></listitem>
 670                 </varlistentry>
 671                 <varlistentry>
 672                     <term><parameter>...</parameter>&nbsp;:</term>
 673                     <listitem><simpara>additional user parameters (if any)</simpara></listitem>
 674                 </varlistentry>
 675             </variablelist>
 676
 677             <para>
 678                 Emitted when the volume has been changed.
 679             </para>
 680         </refsect2>
 681
 682         <refsect2 id="signal-giovolume--removed">
 683             <title>The "removed" gio.Volume Signal</title>
 684
 685             <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
 686                 <methodparam><parameter>volume</parameter></methodparam>
 687                 <methodparam><parameter>user_param1</parameter></methodparam>
 688                 <methodparam><parameter>...</parameter></methodparam>
 689             </methodsynopsis></programlisting>
 690
 691             <variablelist>
 692                 <varlistentry>
 693                     <term><parameter>volume</parameter>&nbsp;:</term>
 694                     <listitem><simpara>the volume</simpara></listitem>
 695                 </varlistentry>
 696                 <varlistentry>
 697                     <term><parameter>user_param1</parameter>&nbsp;:</term>
 698                     <listitem><simpara>the first user parameter (if any) specified
 699                     with the <link
 700                     linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
 701                     method</simpara></listitem>
 702                 </varlistentry>
 703                 <varlistentry>
 704                     <term><parameter>...</parameter>&nbsp;:</term>
 705                     <listitem><simpara>additional user parameters (if any)</simpara></listitem>
 706                 </varlistentry>
 707             </variablelist>
 708
 709             <para>
 710                 This signal is emitted when the
 711                 <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
 712                 have been removed. If the recipient is holding references to the object
 713                 they should release them so the object can be finalized.
 714             </para>
 715         </refsect2>
 716
 717   </refsect1>
 718 </refentry>