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

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-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--removed">"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>